X509CertificateToXmlDoc (String function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
m (→‎See also: add method to list)
 
(27 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Template:String:X509CertificateToXmlDoc subtitle}}
{{Template:String:X509CertificateToXmlDoc subtitle}}
 
X509 is a general authentication framework that establishes standard formats for for public-key certificates, certificate revocation lists (CRLs), and more. <var>X509CertificateToXmlDoc</var> converts a string (<var>Longstring</var>) that contains a certificate to an <var>[[XmlDoc class|XmlDoc]]</var>. DER (Distinguished Encoding Rules), a subset of BER (Basic Encoding Rules, provide a way to uniquely encode an Abstract Syntax Notation One (ASN.1) type value as a string of eight-bit octets.
X509 is a general authentication framework that establishes standard formats for for public-key certificates, certificate revocation lists (CRLs), and more. <var>X509CertificateToXmlDoc</var> converts a string (<var>Longstring</var>) that contains a certificate to an <var>[[XmlDoc]]</var>.


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


===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table>
<tr><th>%doc</th><td>An <var>XmlDoc</var> object variable to contain the decoded value of the method object, <var class="term">string</var>.</td></tr>
<tr><th>%doc</th>
<td>An <var>XmlDoc</var> object variable to contain the decoded value of the method object, <var class="term">string</var>.</td></tr>
 
<tr><th>string</th>
<tr><th>string</th>
<td>A DER encoded string that contains the contents of a digital certificate.</td></tr>
<td>A DER encoded string that contains the contents of a digital certificate. </td></tr>
</table>
</table>


==Usage notes==
==Usage notes==
<ul>
<ul>
<li>Prior to version 7.7 of Model&nbsp;204, input to this method that created any element in the result <var>XmlDoc</var> with a text child whose length exceeded 650 characters produced an error. As of version 7.7, the lengths of the created text nodes are not restricted. </li>
<li><var>X509CertificateToXmlDoc</var> is very similar to   
<li><var>X509CertificateToXmlDoc</var> is very similar to   
<var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var>, except that <var>X509CrlToXmlDoc</var> understands the semantics of the certificate tags, so it provides more meaningful XML element names. Contrast the [[DerToXmlDoc (String function)#Examples|DerToXmlDoc example]] with the <var>X509CertificateToXmlDoc</var> [[X509CertificateToXmlDoc (String function)#Examples|example]], below.  
<var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var>, except that <var>X509CertificateToXmlDoc</var> understands the semantics of the certificate tags, so it provides more meaningful XML element names. Contrast the [[DerToXmlDoc (String function)#Examples|DerToXmlDoc example]] with the <var>X509CertificateToXmlDoc</var> [[X509CertificateToXmlDoc (String function)#Examples|example]], below. </li>
<li><var>X509CertificateToXmlDoc</var> is a complete implementation of the PKCS standards for X509 certificates.  
 
<li><var>X509CertificateToXmlDoc</var> is a complete implementation of the PKCS standards for X509 certificates. </li>
<li>While <var>X509CertificateToXmlDoc</var> is a complete implementation of the PKCS standard, the <code>&lt;RelativeDistinguishedName&gt;</code> element can contain a wide variety of attributes that <var>X509CertificateToXmlDoc</var> does not understand. Under Model 204 7.6 and earlier, this results in a parse exception, but under 7.7 and later, such attributes are added as <code>&lt;unknown&gt;</code> elements with an <code>&lt;ObjectIdentifier&gt;</code> element that indicates the ASN.1 object identifier.
<p class="note"><b>Note:</b> You are advised not to use an <code>&lt;unknown&gt;</code> element in your programs, since future updates to the <var>X509CertificateToXmlDoc</var> method may add support for the element, in which case the element name will change to a proper name. If such an element is of interest, [[Contacting Rocket Software Technical Support|contact Rocket Software technical support]]. </p></li>
 
<li>Currently, no method is available to produce a DER stream from an <var>XmlDoc</var> nor to validate the signature on a certificate.
<li>Currently, no method is available to produce a DER stream from an <var>XmlDoc</var> nor to validate the signature on a certificate.
</ul>
</ul>


==Examples==
==Examples==
In the following example, the <var>[[PemToString (Stringlist function)|PemToString]]</var> method loads a <var>Longstring</var> with the contents of a base64 encoded Certificate. The <var>Longstring</var> is then converted to the <var>XmlDoc</var> whose contents are printed thereafter: <p class="code">begin
<ol>
%ls    is longstring
<li>In the following example, the <var>[[PemToString (Stringlist function)|PemToString]]</var> method loads <var>Longstring</var> <code>%ls</code> with the contents of a base64 encoded Certificate. The <var>Longstring</var> is then converted to an <var>XmlDoc</var> whose contents are printed: <p class="code"> ...
%sl    is object stringlist
%doc  is object xmldoc
 
text to %sl = new raw
text to %sl = new raw
&#45;----BEGIN X509 CERTIFICATE-----
&#45;----BEGIN X509 CERTIFICATE-----
Line 33: Line 38:
IFNvZnR3YXJlIEluYy4xHTAbBgNVBAsTFFNvZnR3YXJlIERldmVsb3BtZW50MTsw
IFNvZnR3YXJlIEluYy4xHTAbBgNVBAsTFFNvZnR3YXJlIERldmVsb3BtZW50MTsw
OQYDVQQDEzJzaXJpdXN8c2lyaXVzLXNvZnR3YXJlLmNvbXx3d3cuc2lyaXVzLXNv
OQYDVQQDEzJzaXJpdXN8c2lyaXVzLXNvZnR3YXJlLmNvbXx3d3cuc2lyaXVzLXNv
ZnR3YXJlLmNvbTAeFw0xMjAxMjkxNzQ2NDFaFw0xMzAxMjkxNzQ2NDFaMIGpMQsw
...
CQYDVQQGEwJVUzELMAkGA1UECBMCTUExEjAQBgNVBAcTCUNhbWJyaWRnZTEdMBsG
A1UEChMUU2lyaXVzIFNvZnR3YXJlIEluYy4xHTAbBgNVBAsTFFNvZnR3YXJlIERl
dmVsb3BtZW50MTswOQYDVQQDEzJzaXJpdXN8c2lyaXVzLXNvZnR3YXJlLmNvbXx3
d3cuc2lyaXVzLXNvZnR3YXJlLmNvbTCCASAwDQYJKoZIhvcNAQEBBQADggENADCC
AQgCggEBAK64Djria2RMkAgUhNME8yfP15vprKFo5jQXw1hTkK2IvkmVeUY6/TSF
FO6ueOM/Zpx4M+ke0k2cbQhge0zCaTvMoiACeK3uR0F7cXKgAqoCHw87o0W5+zPp
p4XLCe41xQ16/GIunbCGidYMoy9lL45BsCgY2tpd7dq/FP0eO6JPogyZa8DeDqFY
tvof6HtcVBwzKT0ZH/Wg3H++VnbUwE+15itvVuIIdRra7UKqctDdw/2JW/NJsQVb
lZxIGO307dwm1BPzoHw+IkAoVUorcVn1+ZV5M4yDkjfv7D9BKAyI6eyM1UiCyX3C
Zv27MHz+Ui/rrF1GPUsQRoUcLtTATdkCAQMwDQYJKoZIhvcNAQEEBQADggEBAAo1
QU/u3Yg8tBlbHT9RZOIQihw6HMDDjjFwrN0Yl4Dw70qh6ADI/u8MfxVBpt4gLqjP
OAb1oGHslTjllqSoHIN6nP58SZHHL5ExOIFQJnWodRQyCyQ0dFWv4/TB6NihYZLb
3YJysceP8RdU9u6KMFca9AaXKIiBhDClAq0jXk/0ew4xlXJM8bRUXEVVWPGjXiP6
3YJysceP8RdU9u6KMFca9AaXKIiBhDClAq0jXk/0ew4xlXJM8bRUXEVVWPGjXiP6
owT5jqCxVO6YyYMabVa1+fIu7g2EKOW26+2xdOBoti8wUHV5u/v7EhX4gl1SFRA0
owT5jqCxVO6YyYMabVa1+fIu7g2EKOW26+2xdOBoti8wUHV5u/v7EhX4gl1SFRA0
Line 54: Line 47:


%ls = %sl:pemToString('X509 CERTIFICATE')
%ls = %sl:pemToString('X509 CERTIFICATE')
%doc = %ls:x509certificateTOXMLDOC     
%ls:x509certificateToXmldoc:print      
%doc:print  
...  </p>
end  </p>


The result is shown below:
The result is shown below:
Line 117: Line 109:
         </RelativeDistinguishedName>                             
         </RelativeDistinguishedName>                             
         <RelativeDistinguishedName>                             
         <RelativeDistinguishedName>                             
             <localityName type="PrintableString">               
             ...
              Cambridge                                       
            </localityName>                                     
        </RelativeDistinguishedName>                           
        <RelativeDistinguishedName>                           
            <organizationName type="PrintableString">           
              Sirius Software Inc.                            
            </organizationName>                                 
        </RelativeDistinguishedName>                           
        <RelativeDistinguishedName>                           
            <organizationalUnitName type="PrintableString">     
              Software Development
            </organizationalUnitName>
        </RelativeDistinguishedName>
        <RelativeDistinguishedName>
            <commonName type="PrintableString">
              sirius|sirius-software.com|www.sirius-software.com
            </commonName>
         </RelativeDistinguishedName>           
         </RelativeDistinguishedName>           
       </subject>       
       </subject>       
Line 144: Line 119:
           <parameters/>
           <parameters/>
         </algorithm>
         </algorithm>
         <subjectPublicKey bits="2144"> 308201080282010100AEB80E3AE26B644C90081484D304F327CFD79BE9ACA168E63417C3585390AD88BE499579463AFD348514EEAE78E33F669C783-
         <subjectPublicKey bits="2144">  
3E91ED24D9C6D08607B4CC2693BCCA2200278ADEE47417B7172A002AA021F0F3BA345B9FB33E9A785CB09EE35C50D7AFC622E9DB08689D60CA32F652F8E41B02818-
            308201080282010100AEB80E3AE26B644C90081484D304F327CFD79BE9ACA168 ...
DADA5DEDDABF14FD1E3BA24FA20C996BC0DE0EA158B6FA1FE87B5C541C33293D191FF5A0DC7FBE5676D4C04FB5E62B6F56E208751ADAED42AA72D0DDC3FD895BF34-
            ... 1046851C2ED4C04DD9020103  
9B1055B959C4818EDF4EDDC26D413F3A07C3E224028554A2B7159F5F99579338C839237EFEC3F41280C88E9EC8CD54882C97DC266FDBB307CFE522FEBAC5D463D4B-
1046851C2ED4C04DD9020103      
         </subjectPublicKey>   
         </subjectPublicKey>   
       </subjectPublicKeyInfo>   
       </subjectPublicKeyInfo>   
</tbsCertificate>     
  </tbsCertificate>     
    <signatureAlgorithm>     
  <signatureAlgorithm>     
      <algorithm name="md5WithRSAEncryption">  
      <algorithm name="md5WithRSAEncryption">  
          1.2.840.113549.1.1.4
        1.2.840.113549.1.1.4
      </algorithm>
      </algorithm>
      <parameters/>
      <parameters/>
    </signatureAlgorithm>     
  </signatureAlgorithm>     
    <signatureValuebits="2048">
  <signatureValue bits="2048">
0A35414FEEDD883CB4195B1D3F5164E2108A1C3A1CC0C38E3170ACDD189780F0EF4AA1E800C8FEEF0C7F1541A6DE202EA8CF3806F5A061EC9538E596A4A81-
      0A35414FEEDD883CB4195B1D3F5164E2108A1C3A1CC0C38E3170 ...
C837A9CFE7C4991C72F91313881502675A87514320B24347455AFE3F4C1E8D8A16192DBDD8272B1C78FF11754F6EE8A30571AF406972888818430A502AD235E4FF4-
      ... 002BB104E801978045ABE6AD7C5DCD
7B0E3195724CF1B4545C455558F1A35E23FAA304F98EA0B154EE98C9831A6D56B5F9F22EEE0D8428E5B6EBEDB174E068B62F30507579BBFBFB1215F8825D5215103-
  </signatureValue>
41C3AA34FF3D56330242CFAFB2EB31552D3DA13AA2CB633F8B8B2ABE4AF08533FD0EE869BFAC1DE8931A4F6A85F9533002BB104E801978045ABE6AD7C5DCD
    </signatureValue>
</Certificate>  </p>
</Certificate>  </p>
<li>To load a client certificate, you might do the following:
<p class="code">%string = %(System):[[ClientCertificate (System function)|ClientCertificate]](RequestCertificate=true)
%doc = %string:X509CertificateToXmlDoc </p>
</ol>


==See also==
==See also==
Related methods:
<p>
<var>String</var> methods:</p>
<ul>
<li><var>[[CertificateRequest (String function)|CertificateRequest]]</var> </li>
 
<li><var>[[ClientCertificateRequest (String function)|ClientCertificateRequest]]</var> </li>
 
<li><var>[[SignedCertificate (String function)|SignedCertificate]]</var> </li>
 
<li><var>[[SignedClientCertificate (String function)|SignedClientCertificate]]</var> </li>
 
<li><var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var> </li>
 
<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>Stringlist</var> methods: </p>
{{Template:Stringlist crypto methods}}
<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>
 
Background information:
<ul>
<ul>
<li><var>String</var> class: <var>[[DerToXmlDoc_(String_function)|DerToXmlDoc]]</var>, <var>[[X509CrlToXmlDoc_(String_function)|X509CrlToXmlDoc]]</var>, and <var>[[RSAPrivateKeyToXmlDoc _(String_function)|RSAPrivateKeyToXmlDoc]]</var>
<li>[http://en.wikipedia.org/wiki/Abstract_Syntax_Notation_One "Abstract Syntax Notation One"]
<li><var>System</var> class: <var>[[ClientCertificate (System function)|ClientCertificate]]</var>
<li>[http://luca.ntop.org/Teaching/Appunti/asn1.html "A Layman's Guide to a Subset of ASN.1, BER, and DER"]
<li><var>Socket</var> class: <var>[[Certificate (Socket function)|Certificate]]</var>
<li><var>HttpRequest</var> class: <var>[[Get (HttpRequest function)|Get]]</var>, <var>[[Post (HttpRequest function)|Post]]</var>, and <var>[[Send (HttpRequest function)|Send]]</var>
<li><var>Stringlist</var> class: <var>[[PemToString_(Stringlist_function)|PemToString]]</var>
</ul>
</ul>


{{Template:String:X509CertificateToXmlDoc footer}}
{{Template:String:X509CertificateToXmlDoc footer}}

Latest revision as of 15:08, 6 September 2018

Convert BER encoded X.509 certificate to XML (String class)

[Introduced in Sirius Mods 8.0]

X509 is a general authentication framework that establishes standard formats for for public-key certificates, certificate revocation lists (CRLs), and more. X509CertificateToXmlDoc converts a string (Longstring) that contains a certificate to an XmlDoc. DER (Distinguished Encoding Rules), a subset of BER (Basic Encoding Rules, provide a way to uniquely encode an Abstract Syntax Notation One (ASN.1) type value as a string of eight-bit octets.

Syntax

%doc = string:X509CertificateToXmlDoc Throws InvalidBerData

Syntax terms

%doc An XmlDoc object variable to contain the decoded value of the method object, string.
string A DER encoded string that contains the contents of a digital certificate.

Usage notes

  • Prior to version 7.7 of Model 204, input to this method that created any element in the result XmlDoc with a text child whose length exceeded 650 characters produced an error. As of version 7.7, the lengths of the created text nodes are not restricted.
  • X509CertificateToXmlDoc is very similar to DerToXmlDoc, except that X509CertificateToXmlDoc understands the semantics of the certificate tags, so it provides more meaningful XML element names. Contrast the DerToXmlDoc example with the X509CertificateToXmlDoc example, below.
  • X509CertificateToXmlDoc is a complete implementation of the PKCS standards for X509 certificates.
  • While X509CertificateToXmlDoc is a complete implementation of the PKCS standard, the <RelativeDistinguishedName> element can contain a wide variety of attributes that X509CertificateToXmlDoc does not understand. Under Model 204 7.6 and earlier, this results in a parse exception, but under 7.7 and later, such attributes are added as <unknown> elements with an <ObjectIdentifier> element that indicates the ASN.1 object identifier.

    Note: You are advised not to use an <unknown> element in your programs, since future updates to the X509CertificateToXmlDoc method may add support for the element, in which case the element name will change to a proper name. If such an element is of interest, contact Rocket Software technical support.

  • Currently, no method is available to produce a DER stream from an XmlDoc nor to validate the signature on a certificate.

Examples

  1. In the following example, the PemToString method loads Longstring %ls with the contents of a base64 encoded Certificate. The Longstring is then converted to an XmlDoc whose contents are printed:

    ... text to %sl = new raw -----BEGIN X509 CERTIFICATE----- MIIDyjCCArICBQG6t2wFMA0GCSqGSIb3DQEBBAUAMIGpMQswCQYDVQQGEwJVUzEL MAkGA1UECBMCTUExEjAQBgNVBAcTCUNhbWJyaWRnZTEdMBsGA1UEChMUU2lyaXVz IFNvZnR3YXJlIEluYy4xHTAbBgNVBAsTFFNvZnR3YXJlIERldmVsb3BtZW50MTsw OQYDVQQDEzJzaXJpdXN8c2lyaXVzLXNvZnR3YXJlLmNvbXx3d3cuc2lyaXVzLXNv ... 3YJysceP8RdU9u6KMFca9AaXKIiBhDClAq0jXk/0ew4xlXJM8bRUXEVVWPGjXiP6 owT5jqCxVO6YyYMabVa1+fIu7g2EKOW26+2xdOBoti8wUHV5u/v7EhX4gl1SFRA0 HDqjT/PVYzAkLPr7LrMVUtPaE6ostjP4uLKr5K8IUz/Q7oab+sHeiTGk9qhflTMA K7EE6AGXgEWr5q18Xc0= -----END X509 CERTIFICATE----- end text %ls = %sl:pemToString('X509 CERTIFICATE') %ls:x509certificateToXmldoc:print ...

    The result is shown below:

    <Certificate> <tbsCertificate> <version>0</version> <serialNumber>7427550213</serialNumber> <signature> <algorithm name="md5WithRSAEncryption"> 1.2.840.113549.1.1.4 </algorithm> <parameters/> </signature> <issuer> <RelativeDistinguishedName> <countryName>US</countryName> </RelativeDistinguishedName> <RelativeDistinguishedName> <stateOrProvinceName type="PrintableString"> MA </stateOrProvinceName> </RelativeDistinguishedName> <RelativeDistinguishedName> <localityName type="PrintableString"> Cambridge </localityName> </RelativeDistinguishedName> <RelativeDistinguishedName> <organizationName type="PrintableString"> Sirius Software Inc. </organizationName> </RelativeDistinguishedName> <RelativeDistinguishedName> <organizationalUnitName type="PrintableString"> Software Development </organizationalUnitName> </RelativeDistinguishedName> <commonName type="PrintableString"> sirius|sirius-software.com|www.sirius-software.com </commonName> </RelativeDistinguishedName> </issuer> <validity> <notBefore type="UTCTime"> 20120129174641.000Z </notBefore> <notAfter type="UTCTime"> 20130129174641.000Z </notAfter> </validity> <subject> <RelativeDistinguishedName> <countryName>US</countryName> </RelativeDistinguishedName> <RelativeDistinguishedName> <stateOrProvinceName type="PrintableString"> MA </stateOrProvinceName> </RelativeDistinguishedName> <RelativeDistinguishedName> ... </RelativeDistinguishedName> </subject> <subjectPublicKeyInfo> <algorithm> <algorithm name="rsaEncryption"> 1.2.840.113549.1.1.1 </algorithm> <parameters/> </algorithm> <subjectPublicKey bits="2144"> 308201080282010100AEB80E3AE26B644C90081484D304F327CFD79BE9ACA168 ... ... 1046851C2ED4C04DD9020103 </subjectPublicKey> </subjectPublicKeyInfo> </tbsCertificate> <signatureAlgorithm> <algorithm name="md5WithRSAEncryption"> 1.2.840.113549.1.1.4 </algorithm> <parameters/> </signatureAlgorithm> <signatureValue bits="2048"> 0A35414FEEDD883CB4195B1D3F5164E2108A1C3A1CC0C38E3170 ... ... 002BB104E801978045ABE6AD7C5DCD </signatureValue> </Certificate>

  2. To load a client certificate, you might do the following:

    %string = %(System):ClientCertificate(RequestCertificate=true) %doc = %string:X509CertificateToXmlDoc

See also

String methods:

Stringlist methods:

System methods:

Socket methods:

Background information:

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=X509CertificateToXmlDoc_(String_function)&oldid=116771"