AppendSignedCertificate (Stringlist function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (→‎See also: add method to list)
 
(27 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{Template:Stringlist:AppendSignedCertificate subtitle}}
{{Template:Stringlist:AppendSignedCertificate subtitle}}
 
This [[Notation conventions for methods#Callable functions|callable]] method signs an X.509 certificate request and adds the lines of the signed certificate to the end of a <var>Stringlist</var>. It requires a valid private key and certificate request.
This [[Notation conventions for methods#Callable functions|callable]] method signs an X.509 certificate request and adds the lines of the signed certificate to the end of a <var>Stringlist</var>.


==Syntax==
==Syntax==
Line 7: Line 6:


===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table>
<tr><th>%rc</th>
<tr><th>%rc</th>
<td>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|"Return codes"]]. </td></tr>
<td>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|Return codes]]. </td></tr>
 
<tr><th>sl</th>
<tr><th>sl</th>
<td>A <var>Stringlist</var> object.</td></tr>
<td>A <var>Stringlist</var> object.</td></tr>
<tr><th><var>PrivateKey</var></th>
<tr><th><var>PrivateKey</var></th>
<td>This [[Notation conventions for methods#Named parameters|name allowed]] argument is a <var>Stringlist</var> that contains the private key to be used for signing.</td></tr>
<td>This [[Notation conventions for methods#Named parameters|name allowed]] argument is a string or <var>Stringlist</var> that contains the private key to be used for signing. The key length may be a maximum of 4096 bits (as of version 7.7 of Model 204). The pre-7.7 maximum is 2048. </td></tr>
 
<tr><th><var>Request</var></th>
<tr><th><var>Request</var></th>
<td>This name allowed argument is a <var>Stringlist</var> that contains the base-64 encoded X.509 certificate request.</td></tr>
<td>This name allowed argument is a string or <var>Stringlist</var> that contains the base64 encoded X.509 certificate request.</td></tr>
 
<tr><th><var>Signer</var></th>
<tr><th><var>Signer</var></th>
<td>This optional, name allowed, argument is a <var>Stringlist</var> that contains the base-64 encoded CA (certifying authority) X.509 certificate. If not specified, the <var>Request</var> <var>Stringlist</var> is used: that is, the certificate will be self-signed. </td></tr>
<td>This optional, name allowed, argument is a string or <var>Stringlist</var> that contains the base64 encoded CA (certifying authority) X.509 certificate. If not specified, the <var>Request</var> value is used: that is, the certificate will be self-signed. </td></tr>
 
<tr><th><var>StartDate</var></th>
<tr><th><var>StartDate</var></th>
<td>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.</td></tr>
<td>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.</td></tr>
<tr><th><var>EndDate</var></th>
<tr><th><var>EndDate</var></th>
<td>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 <var>StartDate</var>.</td></tr>
<td>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 <var>StartDate</var>.  <code>YY</code> may not be less then the current 2-digit year.</td></tr>
 
<tr><th><var>SerialNumber</var></th>
<tr><th><var>SerialNumber</var></th>
<td>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
<td>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. </td></tr>
of signing occurrences. </td></tr>
<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 values 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>
</table>


===Return codes===
===Return codes===
<table>
<table class="thJustBold">
<tr><th>0</th><td>All is well.</td></tr>
<tr><th>0</th>
<tr><th>3</th><td>Out of CCATEMP.</td></tr>
<td>All is well.</td></tr>
<tr><th>5</th><td><var>Stringlist</var> identifier missing.</td></tr>
 
<tr><th>6</th><td>Invalid <var>Stringlist</var> identifier.</td></tr>
<tr><th>7</th>
<tr><th>7</th><td>Insufficient storage.</td></tr>
<td>Insufficient storage.</td></tr>
<tr><th>10</th><td>Private key <var>Stringlist</var> identifier missing.</td></tr>
 
<tr><th>11</th><td>Invalid private key <var>Stringlist</var> identifier.</td></tr>
<tr><th>10</th>
<tr><th>12</th><td>Invalid private key <var>Stringlist</var> data (not correctly base-64 encoded).</td></tr>
<td>Private key <var>Stringlist</var> identifier missing.</td></tr>
<tr><th>13</th><td>Certificate request <var>Stringlist</var> identifier missing.</td></tr>
 
<tr><th>14</th><td>Invalid certificate request <var>Stringlist</var> identifier.</td></tr>  
<tr><th>11</th>
<tr><th>15</th><td>Invalid certificate request.</td></tr>                 
<td>Invalid private key <var>Stringlist</var> identifier.</td></tr>
<tr><th>16</th><td>Invalid CA certificate <var>Stringlist</var> identifier.</td></tr>       
 
<tr><th>17</th><td>Invalid CA certificate.</td></tr>                    
<tr><th>12</th>
<tr><th>18</th><td>Invalid start date.</td></tr>                           
<td>Invalid private key <var>Stringlist</var> data (not correctly base64 encoded).</td></tr>
<tr><th>19</th><td>Invalid end date.</td></tr>                             
 
<tr><th>20</th><td>Invalid serial number.</td></tr>                      
<tr><th>13</th>
<tr><th>21</th><td>Private key does not match signer public key.</td></tr>
<td>Certificate request <var>Stringlist</var> identifier missing.</td></tr>
 
<tr><th>14</th>
<td>Invalid certificate request <var>Stringlist</var> identifier.</td></tr>  
 
<tr><th>15</th>
<td>Invalid certificate request.</td></tr>  
                
<tr><th>16</th>
<td>Invalid CA certificate <var>Stringlist</var> identifier.</td></tr>  
      
<tr><th>17</th>
<td>Invalid CA certificate.</td></tr>  
                 
<tr><th>18</th>
<td>Invalid start date.</td></tr>  
                          
<tr><th>19</th>
<td>Invalid end date.</td></tr>  
                            
<tr><th>20</th>
<td>Invalid serial number.</td></tr>  
                   
<tr><th>21</th>
<td>Private key does not match signer public key.</td></tr>
</table>
</table>
==Usage notes==
For some background information concerning certificates, see [https://en.wikipedia.org/wiki/Public-key_cryptography Public-key cryptography] and [https://en.wikipedia.org/wiki/Certificate_signing_request Certificate signing request].


==Examples==
==Examples==
This example uses a self-generated private key and certificate request and simply displays the <var>AppendSignedCertificate</var> base64 encoded output.
<p class="code">b
%sl  is object stringlist
%ls  is longstring
%cr  is longstring
%sc  is longstring
%rc is float 
%ls = [[GeneratedPrivateKey_(System_function)|%(System):GeneratedPrivateKey]](Length=512)
%cr = %ls:[[CertificateRequest_(String_function)|CertificateRequest]]
%sl = new
%rc = %sl:appendSignedCertificate(%ls, %cr)
%sl:print
end </p>
<p>
The result is: </p>
<p class="output">&#45;----BEGIN X509 CERTIFICATE-----
MIHvMIGaAgkA3narlNAAAAkwDQYJKoZIhvcNAQELBQAwADAeFw0xNjAzMzAyMDQ3
MjVaFw0xNjAzMzAyMDQ3MjVaMAAwWjANBgkqhkiG9w0BAQEFAANJADBGAkEAxFfX
HX5yDlQg/Jp/fA2KqZqpuz/N+Ga1vrGs3+RSQ5zjrwjkyg9Ltd8pHgvcvnCt38MV
BqoqWKDOXU/kVRaYCQIBAzANBgkqhkiG9w0BAQsFAANBAG8BPhU1lLQFGGW2TZon
MrzOypC/ztchIxU3CSUFCSRaD6h5N6b6DmLVKnHgbiUPZEDqZ0sSqy6mrOd9yI/2
zPg= 
&#45;----END X509 CERTIFICATE----- 
8 </p>
<p>
You can use the following statements to somewhat "unpack" the base64
result, but the resulting element names are not very meaningful: </p>
<p class="code">%sc = %sl:pemToString('X509 CERTIFICATE')
%sc:derToXmlDoc:print
</p>
<p>
The result is:  </p>
<p class="output">%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>
</p>
<p>
The <var>DerToXmlDoc</var> 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 <var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var> does for a private key. </p>


==See also==
==See also==
<p>
<var>Stringlist</var> methods: </p>
{{Template:Stringlist crypto methods}}
<p>
<var>String</var> methods:</p>
<ul>
<ul>
<li><var>[[AppendCertificateInfo (Stringlist function)|AppendCertificateInfo]]</var>
<li><var>[[CertificateRequest (String function)|CertificateRequest]]</var> </li>
<li><var>[[AppendCertificateRequest (Stringlist function)|AppendCertificateRequest]]</var>
 
<li><var>[[AppendCertificateRequestInfo (Stringlist function)|AppendCertificateRequestInfo]]</var>
<li><var>[[SignedCertificate (String function)|SignedCertificate]]</var> </li>
<li><var>[[AppendClientCertificateRequest (Stringlist function)|AppendClientCertificateRequest]]</var>
 
<li><var>[[AppendEncryptedSecurityData (Stringlist subroutine)|AppendEncryptedSecurityData]]</var>
<li><var>[[SignedClientCertificate (String function)|SignedClientCertificate]]</var> </li>
<li><var>[[AppendGeneratedPrivateKey (Stringlist subroutine)|AppendGeneratedPrivateKey]]</var>
 
<li><var>[[AppendPrivateKeyInfo (Stringlist function)|AppendPrivateKeyInfo]]</var>
<li><var>[[SignedClientCertificate (String function)|SignedClientCertificate]]</var> </li>
<li><var>[[AppendSignedClientCertificate (Stringlist function)|AppendSignedClientCertificate]]</var>
 
<li><var>[[CheckCertificate (Stringlist function)|CheckCertificate]]</var>
<li><var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var> </li>
<li><var>[[CheckCertificateRequest (Stringlist function)|CheckCertificateRequest]]</var>
 
<li>[[Release notes for Sirius Mods V8.0#XmlDoc version of SSL entities|DER-to-XmlDoc String methods]]
<li><var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var></li>
 
<li><var>[[X509CertificateToXmlDoc (String function)|X509CertificateToXmlDoc]]</var> </li>
 
<li><var>[[X509CrlToXmlDoc (String function)|X509CrlToXmlDoc]]</var> </li>
 
<li>Multiple cryptographic cipher methods </li>
</ul>
<p>
<var>System</var> methods: </p>
<ul>
<li><var>[[ClientCertificate (System function)|ClientCertificate]]</var> </li><li><var>[[GeneratedPrivateKey (System function)|GeneratedPrivateKey]]</var> </li>
</ul>
<p>
<var>Socket</var> methods: </p>
<ul>
<li><var>[[Certificate (Socket function)|Certificate]]</var> </li>
</ul>
</ul>
{{Template:Stringlist:AppendSignedCertificate footer}}
{{Template:Stringlist:AppendSignedCertificate footer}}

Latest revision as of 15:14, 6 September 2018

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. The key length may be a maximum of 4096 bits (as of version 7.7 of Model 204). The pre-7.7 maximum is 2048.
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. YY may not be less then the current 2-digit year.
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 values 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.
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:

-----BEGIN X509 CERTIFICATE----- MIHvMIGaAgkA3narlNAAAAkwDQYJKoZIhvcNAQELBQAwADAeFw0xNjAzMzAyMDQ3 MjVaFw0xNjAzMzAyMDQ3MjVaMAAwWjANBgkqhkiG9w0BAQEFAANJADBGAkEAxFfX HX5yDlQg/Jp/fA2KqZqpuz/N+Ga1vrGs3+RSQ5zjrwjkyg9Ltd8pHgvcvnCt38MV BqoqWKDOXU/kVRaYCQIBAzANBgkqhkiG9w0BAQsFAANBAG8BPhU1lLQFGGW2TZon MrzOypC/ztchIxU3CSUFCSRaD6h5N6b6DmLVKnHgbiUPZEDqZ0sSqy6mrOd9yI/2 zPg= -----END X509 CERTIFICATE----- 8

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.

See also

Stringlist methods:

String methods:

System methods:

Socket methods:

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=AppendSignedCertificate_(Stringlist_function)&oldid=116781"