AppendSignedCertificate (Stringlist function): Difference between revisions

Revision as of 03:11, 11 April 2016

Add base64 encoded signed certificate to a Stringlist (Stringlist class)

[Requires Janus Network Security]

This callable method signs an X.509 certificate request and adds the lines of the signed certificate to the end of a Stringlist. It requires a valid private key and certificate request.

Syntax

[%rc =] sl:AppendSignedCertificate( [PrivateKey=] string, [Request=] string, - [[Signer=] string], - [[StartDate=] string], - [[EndDate=] string], - [[SerialNumber=] number], - [SignatureAlgorithm= digestAlgorithm])

Syntax terms

%rc	An, optional, numeric variable that is set to zero if the function is a success. The possible return codes are described below in Return codes.
sl	A `Stringlist` object.
`PrivateKey`	This name allowed argument is a string or `Stringlist` that contains the private key to be used for signing.
`Request`	This name allowed argument is a string or `Stringlist` that contains the base64 encoded X.509 certificate request.
`Signer`	This optional, name allowed, argument is a string or `Stringlist` that contains the base64 encoded CA (certifying authority) X.509 certificate. If not specified, the `Request` value is used: that is, the certificate will be self-signed.
`StartDate`	This optional, name allowed, argument is a string that contains the Start date for the signed certificate (in YYMMDDHHMISS format). The default is today's date.
`EndDate`	This optional, name allowed, argument is a string that contains the End date for the signed certificate (in YYMMDDHHMISS format). The default is 24 hours from `StartDate`.
`SerialNumber`	This optional, name allowed, argument is a numeric value that is the Serial number for the signed certificate. The default is a number guaranteed to increase by 1 for every call and guaranteed to increase from run to run, unless there is an extreme amount of signing occurrences.
`SignatureAlgorithm`	This optional, name required, argument is a `DigestAlgorithm` enumeration value. Valid options are: `MD5`, `SHA1`, `SHA256`, `SHA384` (Model 204 7.7 and later), and `SHA512` (Model 204 7.7 and later). The default value is `SHA256` as of Model 204 7.7 (and zap maintenance for versions 7.6 and 7.5). Note: Although supported and formerly the default, most modern browsers are deprecating `SHA1`.

Return codes

0	All is well.
3	Out of CCATEMP.
5	`Stringlist` identifier missing.
6	Invalid `Stringlist` identifier.
7	Insufficient storage.
10	Private key `Stringlist` identifier missing.
11	Invalid private key `Stringlist` identifier.
12	Invalid private key `Stringlist` data (not correctly base64 encoded).
13	Certificate request `Stringlist` identifier missing.
14	Invalid certificate request `Stringlist` identifier.
15	Invalid certificate request.
16	Invalid CA certificate `Stringlist` identifier.
17	Invalid CA certificate.
18	Invalid start date.
19	Invalid end date.
20	Invalid serial number.
21	Private key does not match signer public key.

Usage notes

For some background information concerning certificates, see Public-key cryptography and Certificate signing request.

Examples

This example uses a self-generated private key and certificate request and simply displays the AppendSignedCertificate base64 encoded output.

b %sl is object stringlist %ls is longstring %cr is longstring %sc is longstring %rc is float %ls = %(System):GeneratedPrivateKey(Length=512) %cr = %ls:CertificateRequest %sl = new %rc = %sl:appendSignedCertificate(%ls, %cr) %sl:print end

The result is:

You can use the following statements to somewhat "unpack" the base64 result, but the resulting element names are not very meaningful:

%sc = %sl:pemToString('X509 CERTIFICATE') %sc:derToXmlDoc:print

The result is:

%sc:derToXmlDoc:print: <Sequence> <Sequence> <Integer>16030188579305029648</Integer> <Sequence> <ObjectIdentifier>1.2.840.113549.1.1.11</ObjectIdentifier> <Null/> </Sequence> <Sequence/> <Sequence> <UTCTime>20160330214812.000Z</UTCTime> <UTCTime>20160330214812.000Z</UTCTime> </Sequence> <Sequence/> <Sequence> <Sequence> <ObjectIdentifier>1.2.840.113549.1.1.1</ObjectIdentifier> <Null/> </Sequence> <BitString bits="576"> 304602410085C691E0BCB563 ... BE261FE07892276D227180203F- 5AF8C0199094369020103 </BitString> </Sequence> </Sequence> <Sequence> <ObjectIdentifier>1.2.840.113549.1.1.11</ObjectIdentifier> <Null/> </Sequence> <BitString bits="512"> 571F364D0665995B6623E475 ... 149C9EA91D2D047F7658E8657A </BitString> </Sequence>

The DerToXmlDoc method that is used above does not understand the semantics of the standard tags for the signed certificate items. No SOUL method interprets signed certificate items as well as, for example, the RSAPrivateKeyToXmlDoc does for a private key.

@@ Line 33: / Line 33: @@
 <tr><th><var>SignatureAlgorithm</var></th>
-<td>This optional, [[Notation conventions for methods#Named parameters|name required]], argument is a <var>[[DigestAlgorithm enumeration|DigestAlgorithm]]</var> enumeration value.  Valid options are: <var>MD5</var>, <var>SHA1</var>, <var>SHA256</var>. The default value is <var>SHA256</var> as of Model 204 7.7 (and zap maintenance for versions 7.6 and 7.5).
+<td>This optional, [[Notation conventions for methods#Named parameters|name required]], argument is a <var>[[DigestAlgorithm enumeration|DigestAlgorithm]]</var> enumeration value. Valid options are: <var>MD5</var>, <var>SHA1</var>, <var>SHA256</var>, <var>SHA384</var> (Model 204 7.7 and later), and <var>SHA512</var> (Model 204 7.7 and later). The default value is <var>SHA256</var> as of Model 204 7.7 (and zap maintenance for versions 7.6 and 7.5).
 <p class="note"><b>Note:</b> Although supported and formerly the default, most modern browsers are deprecating <var>SHA1</var>.</p></td></tr>
 </table>

Stringlist class	List of Stringlist methods	Stringlist methods syntax
Notation conventions for methods