...
 
Commits (1)
  • Deuce's avatar
    Add support for documenting class properties to jsdocs. · ceb901d4
    Deuce authored
    Then, add JSDOC support to crypto class constant objects.
    
    Also, since crypto stuff is almost half of all the docs, move all
    the crypto classes and objects to the end. It would be nice if these
    massive lists were hidden by default line the menu tree at the start.
    ceb901d4
......@@ -53,23 +53,28 @@ function verstr(ver)
return str;
}
function document_methods(name,obj)
function document_methods(name,obj,type)
{
var method;
var func;
if(type === undefined)
type="object";
var l = (name + " " + type).replace(/\s+/g, '_');
if(obj._method_list == undefined)
return;
f.writeln(li_tag);
f.writeln("<a href=#" + name +"_methods>methods</a>");
f.writeln("<a href=#" + l +"_methods>methods</a>");
table_close();
table_open(name);
docwriteln("<caption align=left><b><tt>" + name + "</tt>");
docwriteln("<a name=" + name + "_methods> methods</a>");
docwriteln("<a name=" + l + "_methods> methods</a>");
docwriteln("</b></caption>");
docwriteln("<tr bgcolor=gray>");
docwriteln("<th align=left width=100>");
......@@ -112,17 +117,19 @@ function document_methods(name,obj)
function object_header(name, obj, type)
{
if(type==undefined)
if(type === undefined)
type="object";
var l = (name + " " + type).replace(/\s+/g, '_');
f.writeln(li_tag);
if(!object_depth)
f.write("[+] &nbsp");
f.writeln(name.bold().link("#"+name) + " " + type);
f.writeln(name.bold().link("#"+l) + " " + type);
if(table_depth)
table_close();
docwriteln("<h2><a name=" + name + ">" + name + " " + type + "</a>");
docwriteln("<h2><a name=" + l + ">" + name + " " + type + "</a>");
if(obj._description!=undefined)
docwriteln("<br><font size=-1>"+obj._description+"</font>");
if(!min_ver && obj._ver>310)
......@@ -132,11 +139,13 @@ function object_header(name, obj, type)
docwriteln("<p>" + obj._constructor + "</p>");
}
function properties_header(name, obj)
function properties_header(name, obj, type)
{
if (type === undefined)
type = 'object';
var l = (name + " " + type).replace(/\s+/g, '_');
f.writeln(li_tag);
f.writeln("<a href=#" + name +"_properties>properties</a>");
f.writeln("<a href=#" + l +"_properties>properties</a>");
table_close();
if(obj._method_list != undefined)
......@@ -144,7 +153,7 @@ function properties_header(name, obj)
table_open(name);
docwriteln("<caption align=left><b><tt>" + name + "</tt>");
docwriteln("<a name=" + name + "_properties> properties</a>");
docwriteln("<a name=" + l + "_properties> properties</a>");
docwriteln("</b></caption>");
docwriteln("<tr bgcolor=gray>");
docwriteln("<th align=left width=100>");
......@@ -159,7 +168,7 @@ function properties_header(name, obj)
docwriteln("Description".fontcolor("white"));
}
function document_properties(name, obj)
function document_properties(name, obj, type)
{
var prop_name;
var count=0;
......@@ -168,6 +177,8 @@ function document_properties(name, obj)
var prop_hdr=false;
var p;
if (type === undefined)
type = typeof(obj);
p=0;
for(prop in obj) {
prop_num=count++;
......@@ -235,9 +246,13 @@ function document_object(name, obj, type)
break;
}
f.writeln("<ul>");
document_methods(name,obj);
document_methods(name,obj,type);
object_depth++;
document_properties(name,obj);
document_properties(name,obj,type);
if (type === 'class') {
if (Object.keys(js.global[obj.constructor.name]).length > 0)
document_object(obj.constructor.name, js.global[obj.constructor.name], "class object");
}
object_depth--;
f.writeln("</ul>");
table_close();
......@@ -333,6 +348,11 @@ if(js.global.COM != undefined) {
com.close();
if(com != undefined) document_object("COM" ,com, "class");
}
if(js.global.conio != undefined) {
document_object("conio",js.global.conio);
}
if(js.global.uifc != undefined) document_object("uifc" ,uifc);
if(js.global.CryptContext != undefined) {
var cc = new CryptContext(CryptContext.ALGO.AES);
if(cc != undefined) document_object("CryptContext",cc, "class");
......@@ -343,13 +363,10 @@ if(js.global.CryptKeyset != undefined) {
}
if(js.global.CryptCert != undefined) {
var ccert = new CryptCert(CryptCert.TYPE.CERTIFICATE);
if(ccert != undefined) document_object("CryptCert",ccert, "class");
}
if(js.global.conio != undefined) {
document_object("conio",js.global.conio);
if(ccert != undefined) {
document_object("CryptCert",ccert, "class");
}
}
if(js.global.uifc != undefined) document_object("uifc" ,uifc);
f.writeln("</ol>");
f.write(body);
......
......@@ -3557,6 +3557,45 @@ js_cryptcert_constructor(JSContext *cx, uintN argc, jsval *arglist)
return(JS_TRUE);
}
#ifdef BUILD_JSDOCS
static char* cryptcert_cursor_prop_desc[] = {
"Move the cursor to the first group or attribute.",
"Move the cursor to the last group or attribute.",
"Move the cursor to the next group or attribute.",
"Move the cursor to the previous group or attribute.",
NULL
};
static char* cryptcert_type_prop_desc[] = {
"No certificate type",
"Certificate.",
"Attribute certificate.",
"PKCS #7 certificate chain.",
"PKCS #10 certification request.",
"CRMF certificate request",
"CRMF certificate revocation request",
"CRL",
"PKCS #7/CMS attributes.",
"RTCS request",
"RTCS response",
"OCSP request",
"OCSP response",
"PKI user information.",
NULL
};
static char* cryptcert_format_prop_desc[] = {
"No certificate format",
"A certification request, certificate, or CRL in binary data format. The certificate object is encoded according to the ASN.1 distinguished encoding rules. This is the normal certificate encoding format.",
"A certificate encoded as a PKCS #7 certificate chain.",
"As CERTIFICATE but with base64 armouring of the binary data.",
"As CERTCHAIN but with base64 armouring of the binary data.",
"XML wrapped cert",
"XML wrapped certchain",
NULL
};
#endif
JSObject* DLLCALL js_CreateCryptCertClass(JSContext* cx, JSObject* parent)
{
JSObject* cksobj;
......@@ -3587,6 +3626,10 @@ JSObject* DLLCALL js_CreateCryptCertClass(JSContext* cx, JSObject* parent)
, JSPROP_PERMANENT|JSPROP_ENUMERATE|JSPROP_READONLY);
JS_DefineProperty(cx, cursor, "LAST", INT_TO_JSVAL(CRYPT_CURSOR_LAST), NULL, NULL
, JSPROP_PERMANENT|JSPROP_ENUMERATE|JSPROP_READONLY);
#ifdef BUILD_JSDOCS
js_CreateArrayOfStrings(cx, cursor, "_property_desc_list", cryptcert_cursor_prop_desc, JSPROP_READONLY);
js_DescribeSyncObject(cx, cursor, "Associative array of cursor constants",318);
#endif
JS_DeepFreezeObject(cx, cursor);
}
type = JS_DefineObject(cx, constructor, "TYPE", NULL, NULL, JSPROP_PERMANENT|JSPROP_ENUMERATE|JSPROP_READONLY);
......@@ -3619,6 +3662,10 @@ JSObject* DLLCALL js_CreateCryptCertClass(JSContext* cx, JSObject* parent)
, JSPROP_PERMANENT|JSPROP_ENUMERATE|JSPROP_READONLY);
JS_DefineProperty(cx, type, "PKIUSER", INT_TO_JSVAL(CRYPT_CERTTYPE_PKIUSER), NULL, NULL
, JSPROP_PERMANENT|JSPROP_ENUMERATE|JSPROP_READONLY);
#ifdef BUILD_JSDOCS
js_CreateArrayOfStrings(cx, type, "_property_desc_list", cryptcert_type_prop_desc, JSPROP_READONLY);
js_DescribeSyncObject(cx, type, "Associative array of certificate type constants",318);
#endif
JS_DeepFreezeObject(cx, type);
}
format = JS_DefineObject(cx, constructor, "FORMAT", NULL, NULL, JSPROP_PERMANENT|JSPROP_ENUMERATE|JSPROP_READONLY);
......@@ -3637,6 +3684,10 @@ JSObject* DLLCALL js_CreateCryptCertClass(JSContext* cx, JSObject* parent)
, JSPROP_PERMANENT|JSPROP_ENUMERATE|JSPROP_READONLY);
JS_DefineProperty(cx, format, "XML_CERTCHAIN", INT_TO_JSVAL(CRYPT_CERTFORMAT_XML_CERTCHAIN), NULL, NULL
, JSPROP_PERMANENT|JSPROP_ENUMERATE|JSPROP_READONLY);
#ifdef BUILD_JSDOCS
js_CreateArrayOfStrings(cx, format, "_property_desc_list", cryptcert_format_prop_desc, JSPROP_READONLY);
js_DescribeSyncObject(cx, format, "Associative array of certificate format constants",318);
#endif
JS_DeepFreezeObject(cx, format);
}
attr = JS_DefineObject(cx, constructor, "ATTR", NULL, NULL, JSPROP_PERMANENT|JSPROP_ENUMERATE|JSPROP_READONLY);
......@@ -4281,6 +4332,10 @@ JSObject* DLLCALL js_CreateCryptCertClass(JSContext* cx, JSObject* parent)
, JSPROP_PERMANENT|JSPROP_ENUMERATE|JSPROP_READONLY);
JS_DefineProperty(cx, attr, "CMS_SPCOPUSINFO_URL", INT_TO_JSVAL(CRYPT_CERTINFO_CMS_SPCOPUSINFO_URL), NULL, NULL
, JSPROP_PERMANENT|JSPROP_ENUMERATE|JSPROP_READONLY);
#ifdef BUILD_JSDOCS
js_CreateArrayOfStrings(cx, attr, "_property_desc_list", cryptcert_prop_desc, JSPROP_READONLY);
js_DescribeSyncObject(cx, attr, "Associative array of certificate attribute constants",318);
#endif
JS_DeepFreezeObject(cx, attr);
}
}
......
......@@ -653,28 +653,7 @@ enum {
#ifdef BUILD_JSDOCS
static char* cryptcon_prop_desc[] = {
"Algorithm constant (CryptContext.ALGO.XXX):<ul class=\"showList\">\n"
"<li>CryptContext.ALGO.NONE</li>\n"
"<li>CryptContext.ALGO.DES</li>\n"
"<li>CryptContext.ALGO.3DES</li>\n"
"<li>CryptContext.ALGO.IDEA</li>\n"
"<li>CryptContext.ALGO.CAST</li>\n"
"<li>CryptContext.ALGO.RC2</li>\n"
"<li>CryptContext.ALGO.RC4</li>\n"
"<li>CryptContext.ALGO.AES</li>\n"
"<li>CryptContext.ALGO.DH</li>\n"
"<li>CryptContext.ALGO.RSA</li>\n"
"<li>CryptContext.ALGO.DSA</li>\n"
"<li>CryptContext.ALGO.ELGAMAL</li>\n"
"<li>CryptContext.ALGO.ECDSA</li>\n"
"<li>CryptContext.ALGO.ECDH</li>\n"
"<li>CryptContext.ALGO.MD5</li>\n"
"<li>CryptContext.ALGO.SHA1</li>\n"
"<li>CryptContext.ALGO.SHA2</li>\n"
"<li>CryptContext.ALGO.SHAng</li>\n"
"<li>CryptContext.ALGO.HMAC-SHA1</li>\n"
"<li>CryptContext.ALGO.HMAC-SHA2</li>\n"
"<li>CryptContext.ALGO.HMAC-SHAng</li></ul>"
"Algorithm constant (CryptContext.ALGO.XXX)"
,"Cipher block size in bytes"
,"Output of hasing algorithms (ie: MD5, SHA1, etc)"
,"Cipher IV"
......@@ -684,12 +663,7 @@ static char* cryptcon_prop_desc[] = {
,"The salt value used to derive an encryption key from a key (Length must be between 8 and 64)"
,"Key size in bytes"
,"Key label"
,"Mode constant (CryptContext.MODE.XXX):<ul class=\"showList\">\n"
"<li>CryptContext.MODE.None</li>\n"
"<li>CryptContext.MODE.ECB</li>\n"
"<li>CryptContext.MODE.CBC</li>\n"
"<li>CryptContext.MODE.CFB</li>\n"
"<li>CryptContext.MODE.GCM</li></ul>"
,"Mode constant (CryptContext.MODE.XXX)"
,"Algorithm name"
,"Mode name"
,NULL
......@@ -1037,6 +1011,51 @@ js_cryptcon_constructor(JSContext *cx, uintN argc, jsval *arglist)
return(JS_TRUE);
}
#ifdef BUILD_JSDOCS
static char* cryptcon_algo_prop_desc[] = {
"No encryption",
"<p>DES is a 64-bit block cipher with a 56-bit key. Note that this algorithm is no longer considered secure and should not be used. It is present in cryptlib only for compatibility with legacy applications.</p>"
"<p>Although cryptlib uses 64-bit DES keys, only 56 bits of the key are actually used. The least significant bit in each byte is used as a parity bit (cryptlib will set the correct parity values for you, so you don't have to worry about this). You can treat the algorithm as having a 64-bit key, but bear in mind that only the high 7 bits of each byte are actually used as keying material.</p>"
"<p>Loading a key will return a CRYPT_ERROR_PARAM3 error if the key is a weak key. cryptExportKey will export the correct parity-adjusted version of the key.</p>",
"<p>Triple DES is a 64-bit block cipher with a 112/168-bit key.</p>"
"<p>Although cryptlib uses 128, or 192-bit DES keys (depending on whether two- or three-key triple DES is being used), only 112 or 168 bits of the key are actually used. The least significant bit in each byte is used as a parity bit (cryptlib will set the correct parity values for you, so you don't have to worry about this). You can treat the algorithm as having a 128 or 192-bit key, but bear in mind that only the high 7 bits of each byte are actually used as keying material.</p>"
"<p>Loading a key will return a CRYPT_ERROR_PARAM3 error if the key is a weak key. cryptExportKey will export the correct parity-adjusted version of the key.</p>",
"IDEA is a 64-bit block cipher with a 128-bit key. IDEA was formerly covered by patents, but these have now all expired.",
"CAST-128 is a 64-bit block cipher with a 128-bit key",
"RC2 (disabled by default, used for PKCS #12)",
"RC4 is an 8-bit stream cipher with a key of up to 1024 bits. Some weaknesses have been found in this algorithm, and it's proven to be extremely difficult to employ in a safe manner. For this reason it should not be used any more except for legacy application support, and is disabled by default.</p>"
"<p>The term \"RC4\" is trademarked in the US. It may be necessary to refer to it as \"an algorithm compatible with RC4\" in products that use RC4 and are distributed in the US. Common practice is to refer to it as ArcFour.</p>",
"AES is a 128-bit block cipher with a 128-bit key.",
"<p>Diffie-Hellman is a key-agreement algorithm with a key size of up to 4096 bits.</p>"
"<p>Diffie-Hellman was formerly covered by a patent in the US, this has now expired.</p>",
"<p>RSA is a public-key encryption/digital signature algorithm with a key size of up to 4096 bits.</p>"
"<p>RSA was formerly covered by a patent in the US, this has now expired.</p>",
"<p>DSA is a digital signature algorithm with a key size of up to 1024 bits and has the cryptlib algorithm identifier CRYPT_ALGO_DSA.</p>"
"<p>DSA is covered by US patent 5,231,668, with the patent held by the US government. This patent has been made available royalty-free to all users world-wide. The US Department of Commerce is not aware of any other patents that would be infringed by the DSA. US patent 4,995,082, \"Method for identifying subscribers and for generating and verifying electronic signatures in a data exchange system\" (\"the Schnorr patent\") relates to the DSA algorithm but only applies to a very restricted set of smart-card based applications and does not affect the DSA implementation in cryptlib.</p>",
"<p>Elgamal is a public-key encryption/digital signature algorithm with a key size of up to 4096 bits.</p>"
"<p>Elgamal was formerly covered (indirectly) by a patent in the US, this has now expired.</p>",
"ECDSA is a digital signature algorithm with a key size of up to 521 bits.",
"ECDH is a key-agreement algorithm with a key size of up to 521 bits.",
"MD5 (only used for TLS 1.0/1.1)",
"SHA1 is a message digest/hash algorithm with a digest/hash size of 160 bits. This algorithm has poor long-term security prospects and should be deprecated in favour of SHA-2.",
"SHA2/SHA256 is a message digest/hash algorithm with a digest/hash size of 256 bits.",
"Future SHA-nextgen standard",
"HMAC-SHA1 is a MAC algorithm with a key size of up to 1024 bits.",
"HMAC-SHA2 is a MAC algorithm with a key size of up to 1024 bits.",
"HMAC-future-SHA-nextgen",
NULL
};
static char* cryptcon_mode_prop_desc[] = {
"No encryption mode",
"ECB",
"CBC",
"CFB",
"GCM",
NULL
};
#endif
JSObject* DLLCALL js_CreateCryptContextClass(JSContext* cx, JSObject* parent)
{
JSObject* ccobj;
......@@ -1104,6 +1123,10 @@ JSObject* DLLCALL js_CreateCryptContextClass(JSContext* cx, JSObject* parent)
/* CRYPT_ALGO_HMAC_RIPEMD160 no longer supported */
JS_DefineProperty(cx, algo, "HMAC-SHAng", INT_TO_JSVAL(CRYPT_ALGO_HMAC_SHAng), NULL, NULL
, JSPROP_PERMANENT|JSPROP_ENUMERATE|JSPROP_READONLY);
#ifdef BUILD_JSDOCS
js_CreateArrayOfStrings(cx, algo, "_property_desc_list", cryptcon_algo_prop_desc, JSPROP_READONLY);
js_DescribeSyncObject(cx, algo, "Associative array of crypto algorithm constants",318);
#endif
JS_DeepFreezeObject(cx, algo);
}
mode = JS_DefineObject(cx, constructor, "MODE", NULL, NULL, JSPROP_PERMANENT|JSPROP_ENUMERATE|JSPROP_READONLY);
......@@ -1119,6 +1142,10 @@ JSObject* DLLCALL js_CreateCryptContextClass(JSContext* cx, JSObject* parent)
/* CRYPT_MODE_OFB no longer supported */
JS_DefineProperty(cx, mode, "GCM", INT_TO_JSVAL(CRYPT_MODE_GCM), NULL, NULL
, JSPROP_PERMANENT|JSPROP_ENUMERATE|JSPROP_READONLY);
#ifdef BUILD_JSDOCS
js_CreateArrayOfStrings(cx, mode, "_property_desc_list", cryptcon_mode_prop_desc, JSPROP_READONLY);
js_DescribeSyncObject(cx, mode, "Associative array of crypto mode constants",318);
#endif
JS_DeepFreezeObject(cx, mode);
}
}
......
......@@ -510,6 +510,16 @@ js_cryptkeyset_constructor(JSContext *cx, uintN argc, jsval *arglist)
return(JS_TRUE);
}
#ifdef BUILD_JSDOCS
static char* cryptkeyset_keyopt_prop_desc[] = {
"No special access options (this option implies read/write access).",
"<p>Read-only keyset access. This option is automatically enabled by cryptlib for keyset types that have read-only restrictions enforced by the nature of the keyset, the operating system, or user access rights.</p>"
"<p>Unless you specifically require write access to the keyset, you should use this option since it allows cryptlib to optimise its buffering and access strategies for the keyset.</p>",
"Create a new keyset. This option is only valid for writeable keyset types, which includes keysets implemented as databases and cryptlib key files.",
NULL
};
#endif
JSObject* DLLCALL js_CreateCryptKeysetClass(JSContext* cx, JSObject* parent)
{
JSObject* cksobj;
......@@ -535,6 +545,10 @@ JSObject* DLLCALL js_CreateCryptKeysetClass(JSContext* cx, JSObject* parent)
, JSPROP_PERMANENT|JSPROP_ENUMERATE|JSPROP_READONLY);
JS_DefineProperty(cx, opts, "CREATE", INT_TO_JSVAL(CRYPT_KEYOPT_CREATE), NULL, NULL
, JSPROP_PERMANENT|JSPROP_ENUMERATE|JSPROP_READONLY);
#ifdef BUILD_JSDOCS
js_CreateArrayOfStrings(cx, opts, "_property_desc_list", cryptkeyset_keyopt_prop_desc, JSPROP_READONLY);
js_DescribeSyncObject(cx, opts, "Associative array of keyset option constants",318);
#endif
JS_DeepFreezeObject(cx, opts);
}
}
......
......@@ -3438,6 +3438,7 @@ JSObject* DLLCALL js_CreateMsgBaseClass(JSContext* cx, JSObject* parent, scfg_t*
{
JSObject* obj;
JSObject* constructor;
JSObject* pobj;
jsval val;
obj = JS_InitClass(cx, parent, NULL
......@@ -3451,8 +3452,18 @@ JSObject* DLLCALL js_CreateMsgBaseClass(JSContext* cx, JSObject* parent, scfg_t*
if(JS_GetProperty(cx, parent, js_msgbase_class.name, &val) && !JSVAL_NULL_OR_VOID(val)) {
JS_ValueToObject(cx,val,&constructor);
JS_DefineObject(cx,constructor,"IndexPrototype",NULL,NULL,JSPROP_PERMANENT|JSPROP_ENUMERATE);
JS_DefineObject(cx,constructor,"HeaderPrototype",NULL,NULL,JSPROP_PERMANENT|JSPROP_ENUMERATE);
pobj = JS_DefineObject(cx,constructor,"IndexPrototype",NULL,NULL,JSPROP_PERMANENT|JSPROP_ENUMERATE);
#ifdef BUILD_JSDOCS
if (pobj) {
js_DescribeSyncObject(cx, pobj, "Prototype for all index objects. Can be used to extend these objects.",317);
}
#endif
pobj = JS_DefineObject(cx,constructor,"HeaderPrototype",NULL,NULL,JSPROP_PERMANENT|JSPROP_ENUMERATE);
#ifdef BUILD_JSDOCS
if (pobj) {
js_DescribeSyncObject(cx, pobj, "Prototype for all header objects. Can be used to extend these objects.",317);
}
#endif
}
return(obj);
......