зеркало из https://github.com/mozilla/gecko-dev.git
503 строки
16 KiB
HTML
503 строки
16 KiB
HTML
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<meta name="GENERATOR" content="Mozilla/4.7 [en] (WinNT; U) [Netscape]">
|
|
<title>Javascript API for Client Certificate Management</title>
|
|
</head>
|
|
<body>
|
|
|
|
<table WIDTH="100%" >
|
|
<tr>
|
|
<td>
|
|
<h1>
|
|
<font face="Arial,Helvetica">Personal Security Manager 1.0</font></h1>
|
|
|
|
<h2>
|
|
<font face="Arial,Helvetica">JavaScript API for Client Certificate Management</font></h2>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
Version 0.3 - 10/27/1999
|
|
<br>Comments to: <a href="mailto:psmfeedback@netscape.com?subject=JavaScript%20API%20Feedback">psmfeedback@netscape.com</a>
|
|
<p>This document describes a new JavaScript API for performing user certificate
|
|
management operations within a client. The JavaScript runs in the context
|
|
of a web page operated by a Certificate Authority (CA) or Registration
|
|
Authority (RA). The API allows the CA or RA to instruct the client to perform
|
|
PKI operations such as key generation, certificate request generation,
|
|
key escrow, import of user certificates, key recovery, and revocation requests.
|
|
<p>These properties and methods reflect behavior currently implemented
|
|
in Personal Security Manager 1.0.
|
|
<p>The messages imported by or generated by these JavaScript methods are
|
|
defined in the CRMF, CMMF, and CMC internet drafts.
|
|
<h2>
|
|
<font face="Arial,Helvetica">Overview of New Cert Issuing Process</font></h2>
|
|
|
|
<ol>
|
|
<li>
|
|
User fills out enrollment form</li>
|
|
|
|
<li>
|
|
User action initiates script</li>
|
|
|
|
<li>
|
|
Script calls key generation method</li>
|
|
|
|
<li>
|
|
Signing and Encryption keys are generated</li>
|
|
|
|
<li>
|
|
Encryption Private Key is wrapped with public key of Key Recovery Authority
|
|
(KRA) (passed in in the form of a certificate as part of the script, and
|
|
checked against a pre-installed certificate copy in the local certificate
|
|
database)</li>
|
|
|
|
<li>
|
|
The public keys, wrapped encryption private key, and text string from the
|
|
script (possibly containing naming or enrollment info) are signed by the
|
|
user</li>
|
|
|
|
<li>
|
|
Signed blob is returned to the script</li>
|
|
|
|
<li>
|
|
Script submits signed blob and any other necessary info to the CA/RA</li>
|
|
|
|
<li>
|
|
CA/RA verifies signature on signed blob</li>
|
|
|
|
<li>
|
|
CA/RA validates identity of user</li>
|
|
|
|
<li>
|
|
CA/RA sends wrapped encryption private key to KRA</li>
|
|
|
|
<li>
|
|
KRA sends escrow verification back to CA</li>
|
|
|
|
<li>
|
|
CA creates and signs certificates</li>
|
|
|
|
<li>
|
|
CA sends certificates back to Communicator</li>
|
|
</ol>
|
|
|
|
<h2>
|
|
<font face="Arial,Helvetica">JavaScript API</font></h2>
|
|
|
|
<h3>
|
|
<font face="Arial,Helvetica">Properties</font></h3>
|
|
<tt>crypto.algorithms.dh.keySizes</tt>
|
|
<br><tt>crypto.algorithms.dsa.keySizes</tt>
|
|
<br><tt>crypto.algorithms.rsa.signing.keySizes</tt>
|
|
<br><tt>crypto.algorithms.rsa.keyEx.keySizes</tt>
|
|
<p><tt>keySizes</tt> is an an array that describes the available key sizes
|
|
for the particular algorithms and operations.
|
|
<p>The table below describes the key sizes that will be supported in the
|
|
US and Export versions of Communicator.
|
|
<br>
|
|
<table BORDER WIDTH="100%" >
|
|
<tr>
|
|
<td ALIGN=CENTER><b>Algorithm</b></td>
|
|
|
|
<td ALIGN=CENTER><b>US Version Key Sizes</b></td>
|
|
|
|
<td ALIGN=CENTER><b>Export Version Key Sizes</b></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>DSA Signing Only</td>
|
|
|
|
<td>1024, 2048</td>
|
|
|
|
<td>1024, 2048</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>RSA Signing Only</td>
|
|
|
|
<td>1024, 2048</td>
|
|
|
|
<td>1024, 2048</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>RSA Encryption Only</td>
|
|
|
|
<td>1024, 2048</td>
|
|
|
|
<td>512,1024</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>RSA Dual Use Signing And Encryption</td>
|
|
|
|
<td>1024, 2048</td>
|
|
|
|
<td>512,1024</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>DH Key Exchange</td>
|
|
|
|
<td>1024, 2048</td>
|
|
|
|
<td>512,1024</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h3>
|
|
<font face="Arial,Helvetica">Methods</font></h3>
|
|
|
|
<h4>
|
|
<font face="Arial,Helvetica">generateCRMFRequest()</font></h4>
|
|
<tt>crmfObject = crypto.generateCRMFRequest(<i>"requestedDN", "regToken",
|
|
"authenticator","escrowAuthorityCert", "KeyGen Done Code",keySize1, "keyParams1",
|
|
"keyGenAlg1",..., keySizeN, "keyParamsN", "keyGenAlgN");</i></tt>
|
|
<p>This method will generate a sequence of CRMF requests that has N requests.
|
|
One request for each key pair that is generated. The first three
|
|
parameters will be applied to every request. the "escrowAuthorityCert"
|
|
parameter will only be used for requests that pertain to a key that is
|
|
being escrowed. After the "escrowAuthorityCert" parameter, the method
|
|
takes some JavaScript code that is invoked when the CRMF request
|
|
is ready. Finally, there are 1 or more sets of key generation arguments.
|
|
Each key generation will be associated with its own request. All
|
|
the requests will have the same DN.
|
|
<br>
|
|
<table BORDER WIDTH="100%" >
|
|
<tr>
|
|
<td ALIGN=CENTER VALIGN=TOP><b>Argument</b></td>
|
|
|
|
<td ALIGN=CENTER><b>Description</b></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><i><tt>"requestedDN"</tt></i></td>
|
|
|
|
<td>An RFC1485 formatted DN to include in the certificate request.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><i><tt>"regToken"</tt></i></td>
|
|
|
|
<td>A value used to authenticate the user to the RA/CA.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><i><tt>"authenticator"</tt></i></td>
|
|
|
|
<td>A value that the user can authenticate with in the future when their
|
|
private key is not available. Can be used for key recovery or revocation
|
|
requests.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><i><tt>"escrowAuthorityCert"</tt></i></td>
|
|
|
|
<td>If this value is NULL, then no key escrow will be performed. This value
|
|
specifies which KRA certificate should be used to wrap the private key
|
|
being escrowed. The user will be prompted for confirmation whenever a key
|
|
will be escrowed. Only key exchange keys will be escrowed. If a dual
|
|
use key is being generated, it will not be escrowed. The value of
|
|
this argument is a base-64 encoded certificate.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><i><tt>"CRMF Generation Done Code"</tt></i></td>
|
|
|
|
<td>This parameter is JavaScript to execute when the CRMF generation is
|
|
complete. </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i><tt>keySizeN</tt></i></td>
|
|
|
|
<td>The size in bits of the Nth key to generate</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i><tt>"keyParamsN"</tt></i></td>
|
|
|
|
<td>This string is an optional algorithm dependent parameter value. For
|
|
Diffie-Hellman it is used to specify p and g parameters. For DSA,
|
|
it will be used to specify pqg. If the key generation requires parameters
|
|
and the value passed in is NULL, then the client will generate the parameters
|
|
on its own. Currently, this value is ignored.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i><tt>"keyGenAlgN"</tt></i></td>
|
|
|
|
<td>Which algorithm the generated key will support. Acceptable values are
|
|
(the mentioned values for keyUsage pertain to the keyUsage value of the
|
|
Certificate Extension that will ultimately be in the issued certificate):
|
|
<ul>
|
|
<li>
|
|
"rsa-ex" - generate an RSA key for key exchange only (This will have keyEncipherment
|
|
set for keyUsage.)</li>
|
|
|
|
<li>
|
|
"rsa-dual-use" - generate a single RSA key for both signing and encryption.
|
|
(This will have digitalSignature, keyEncipherment, and nonRepudiation set
|
|
for keyUsage.)</li>
|
|
|
|
<li>
|
|
"rsa-sign" - generate an RSA key for signing only. (This will have digitalSignature
|
|
set for keyUsage.)</li>
|
|
|
|
<li>
|
|
"rsa-nonrepudiation" - generate a single RSA key for nonRepudiation only.
|
|
(This will have non-repudiation set for keyUsage.)</li>
|
|
|
|
<li>
|
|
"rsa-sign-nonrepudiation" - generate a single RSA key use for both signing
|
|
and nonRepudiation. (This will have both digitalSignature and nonRepudiation
|
|
set for keyUsage.)</li>
|
|
|
|
<li>
|
|
"dsa-sign" - generate a single DSA key for signing only. (This will have
|
|
digitalSignature set for keyUsage.)</li>
|
|
|
|
<li>
|
|
"dsa-nonrepudiation" - generate a single DSA key for nonRepudiation. (This
|
|
will have nonRepudiation set for keyUsage.)</li>
|
|
|
|
<li>
|
|
"dsa-sign-nonrepudiation" - generate a single DSA key for signing and non-repudiation.
|
|
(This will have digitalSignature and nonRepudiation set for keyUsage.)</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>The <b>generateCRMFRequest()</b> method will cause the user to be presented
|
|
with a key generation dialog. The dialog describes the key generation process
|
|
and gives the user the opportunity to cancel the operation.
|
|
<p>The method <b>generateCRMFRequest() </b>will return an instance of a
|
|
CRMF object. The JavaScript passed in as the <i><tt>"CRMF Generation Done
|
|
Code"</tt></i> parameter should look at the attribute <i>request </i>of
|
|
the returned object to get the result of the CRMF generation.
|
|
<p>The string found by accessing <i><tt>crmfObject.request</tt></i> is
|
|
the base-64 encoded CRMF message to be sent to the CA/RA, or an error string.
|
|
The possible error strings are:
|
|
<br>
|
|
<table BORDER WIDTH="100%" >
|
|
<tr>
|
|
<td ALIGN=CENTER><b>Error String</b></td>
|
|
|
|
<td ALIGN=CENTER><b>Description</b></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>"error:invalidParameter:XXX"</td>
|
|
|
|
<td>The parameter XXX was an invalid value.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>"error:userCancel"</td>
|
|
|
|
<td>the user has canceled the key generation operation</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>"error:internalError"</td>
|
|
|
|
<td>the software encountered some internal error, such as out of memory</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h4>
|
|
<font face="Arial,Helvetica">importUserCertificates()</font></h4>
|
|
<tt><i>resultString</i> = crypto.importUserCertificates(<i>"nicknameString"</i>,
|
|
<i>"certString"</i>,
|
|
<i>allowBackup</i>)</tt>
|
|
<br>
|
|
<br>
|
|
<table BORDER WIDTH="100%" >
|
|
<tr>
|
|
<td ALIGN=CENTER><b>Argument</b></td>
|
|
|
|
<td ALIGN=CENTER><b>Description</b></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i><tt>"nicknameString"</tt></i></td>
|
|
|
|
<td>This is the nickname that will be used to describe the certificate
|
|
in the client's certificate management UI. It should serve to uniquely
|
|
identify the certificate to the user. For example, "John Smith's VeriSign
|
|
Class 3 Digital ID" or "John Smith's Ford ID Certificate". However, if
|
|
this certificate has the same DN as one or more certificates that already
|
|
exist in the user's certificate store, the nickname associated with the
|
|
certificate(s) of the same DN in the certificate store is used, and the
|
|
<tt>"nicknameString"</tt> parameter is ignored. If the string is null and
|
|
no certificate with the same DN exists in the user's certificate store,
|
|
Personal Security Manager uses the following pattern to derive the nickname:
|
|
<tt><Common Name>'s <Issuer Name> ID</tt>.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i><tt>"certRepString"</tt></i></td>
|
|
|
|
<td>This string is the CMMF Certification Response from the CA that contains
|
|
the user's certificate(s). The response is base-64 encoded.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><i><tt>allowBackup</tt></i></td>
|
|
|
|
<td>This is a Boolean argument. It allows the CA or RA to indicate to the
|
|
client whether to force the user to back up a newly issued certificate
|
|
(PKCS #12).</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>The <b>importUserCertificates()</b> method is used to import newly issued
|
|
certificates for the user. The private key for the certificates must already
|
|
reside in the user's personal private key database.
|
|
<p>The request ID in the response being imported must match the request
|
|
ID in the associated Certification Request or Recovery Request.
|
|
<p>If the import operation succeeds, an empty string will be returned.
|
|
If it fails, one of the following error strings will be returned:
|
|
<br>
|
|
<br>
|
|
<table BORDER WIDTH="100%" >
|
|
<tr>
|
|
<td ALIGN=CENTER><b>Error String</b></td>
|
|
|
|
<td ALIGN=CENTER><b>Description</b></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>"error:userCancel"</td>
|
|
|
|
<td>The user canceled the import operation</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>"error:invalidCertificate"</td>
|
|
|
|
<td>One of the certificate packages was incorrectly formatted</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>"error:internalError"</td>
|
|
|
|
<td>The software encountered some internal error, such as out of memory</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>"error:invalidRequestID"</td>
|
|
|
|
<td>The request ID in the response message does not match any outstanding
|
|
request</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h4>
|
|
<font face="Arial,Helvetica">popChallengeResponse()</font></h4>
|
|
<tt><i>resultString</i> = crypto.popChallengeResponse(<i>"challengeString"</i>);</tt>
|
|
<br>
|
|
<table BORDER WIDTH="100%" >
|
|
<tr>
|
|
<td ALIGN=CENTER VALIGN=TOP><b>Argument</b></td>
|
|
|
|
<td ALIGN=CENTER><b>Description</b></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i><tt>"challengeString"</tt></i></td>
|
|
|
|
<td>A base-64 encoded CMMF POPODecKeyChallContent message. The current
|
|
implementation does not conform to that defined in the CMMF draft, and
|
|
we intend to change this implementation to that defined in the CMC RFC..
|
|
See below for the current implementation.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>The resultString will either be a base-64 encoded POPODecKeyRespContent
|
|
message, or one of the following error strings:
|
|
<br>
|
|
<br>
|
|
<table BORDER WIDTH="100%" >
|
|
<tr>
|
|
<td ALIGN=CENTER><b>Error String</b></td>
|
|
|
|
<td ALIGN=CENTER><b>Description</b></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>"error:invalidParameter:XXX"</td>
|
|
|
|
<td>The parameter XXX was an invalid value.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>"error:internalError"</td>
|
|
|
|
<td>the software encountered some internal error, such as out of memory</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><b>Challenge-Response Proof Of Possession</b>
|
|
<p><tt>Expected Input:</tt>
|
|
<p><tt>POPODecKeyChallContent ::= SEQUENCE OF Challenge</tt>
|
|
<br><tt> -- One Challenge per encryption key certification
|
|
request (in the</tt>
|
|
<br><tt> -- same order as these requests appear in FullCertTemplates).</tt>
|
|
<p><tt>Challenge ::= SEQUENCE {</tt>
|
|
<br><tt> owf
|
|
AlgorithmIdentifier OPTIONAL,</tt>
|
|
<br><tt> -- MUST be present in the first
|
|
Challenge; MAY be omitted in any</tt>
|
|
<br><tt> -- subsequent Challenge in POPODecKeyChallContent
|
|
(if omitted,</tt>
|
|
<br><tt> -- then the owf used in the immediately
|
|
preceding Challenge is</tt>
|
|
<br><tt> -- to be used).</tt>
|
|
<br><tt> witness
|
|
OCTET STRING,</tt>
|
|
<br><tt> -- the result of applying the one-way
|
|
function (owf) to a</tt>
|
|
<br><tt> -- randomly-generated INTEGER, A.
|
|
[Note that a different</tt>
|
|
<br><tt> -- INTEGER MUST be used for each
|
|
Challenge.]</tt>
|
|
<br><tt> sender
|
|
GeneralName,</tt>
|
|
<br><tt> -- the name of the sender.</tt>
|
|
<br><tt> key
|
|
OCTET STRING,</tt>
|
|
<br><tt> -- the public key used to encrypt
|
|
the challenge. This will allow</tt>
|
|
<br><tt> -- the client to find the appropriate
|
|
key to do the decryption.</tt>
|
|
<br><tt> challenge
|
|
OCTET STRING</tt>
|
|
<br><tt> -- the encryption (under the public
|
|
key for which the cert.</tt>
|
|
<br><tt> -- request is being made) of Rand,
|
|
where Rand is specified as</tt>
|
|
<br><tt> -- Rand ::= SEQUENCE
|
|
{</tt>
|
|
<br><tt> --
|
|
int INTEGER,</tt>
|
|
<br><tt> --
|
|
- the randomly-generated INTEGER A (above)</tt>
|
|
<br><tt> --
|
|
senderHash OCTET STRING</tt>
|
|
<br><tt> --
|
|
- the result of applying the one-way function (owf) to</tt>
|
|
<br><tt> --
|
|
- the sender's general name</tt>
|
|
<br><tt> -- }</tt>
|
|
<br><tt> -- the size of "int" must be small
|
|
enough such that "Rand" can be</tt>
|
|
<br><tt> -- contained within a single PKCS
|
|
#1 encryption block.</tt>
|
|
<br><tt> }</tt>
|
|
<p>© Copyright 1999 Netscape Communications Corporation
|
|
</body>
|
|
</html>
|