X509CrlToXmlDoc (String function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (→‎See also: add method to list)
 
(14 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Template:String:X509CrlToXmlDoc subtitle}}
{{Template:String:X509CrlToXmlDoc subtitle}}
 
X509 is a general authentication framework that establishes standard formats for for public-key certificates, certificate revocation list (CRLs), and more. <var>X509CrlToXmlDoc</var> converts a string (<var>Longstring</var>) that contains a CRL 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 list (CRLs), and more. <var>X509CrlToXmlDoc</var> converts a string (<var>Longstring</var>) that contains a CRL to an <var>[[XmlDoc]]</var>.


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


===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table>
<tr><th>%doc</th>
<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>
<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 CRL (Certificate Revocation List). <br>'''Note:''' This method fails if the XML representation of <var class="term">string</var> is longer than 650 characters. </td></tr>
<td>A DER encoded string that contains the contents of a CRL (Certificate Revocation List). </td></tr>
</table>
</table>
===Exceptions===
<var>X509CrlToXmlDoc</var> can throw the following [[Exceptions|exception]]:
<dl>
<dt><var>[[InvalidBerData class|InvalidBerData]]</var>
<dd>If the method encounters data that does not conform to the PEM standard, properties of the exception object may indicate the position and description of the error.
</dl>


==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>X509CrlToXmlDoc</var> is very similar to   
<li><var>X509CrlToXmlDoc</var> is very similar to   
<var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var>, except that <var>X509CrlToXmlDoc</var> understands the semantics of the CRL tags, so it provides more meaningful XML element names. Contrast the [[DerToXmlDoc (String function)#Examples|DerToXmlDoc example]] with the <var>X509CrlToXmlDoc</var> [[X509CrlToXmlDoc (String function)#Examples|example]], below.  
<var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var>, except that <var>X509CrlToXmlDoc</var> understands the semantics of the CRL tags, so it provides more meaningful XML element names. Contrast the [[DerToXmlDoc (String function)#Examples|DerToXmlDoc example]] with the <var>X509CrlToXmlDoc</var> [[X509CrlToXmlDoc (String function)#Examples|example]], below. </li>
<li><var>X509CrlToXmlDoc</var> is a complete implementation of the PKCS standards for CRLs.  
 
<li><var>X509CrlToXmlDoc</var> is a complete implementation of the PKCS standards for CRLs. </li>
 
<li><var class="product">Janus Web Server</var> is not equipped to use the <var>XmlDoc</var> CRLs automatically; you have to process them yourself. Probably, for efficiency, you want to get the CRL at startup time, then store it somewhere easy to get at (a global <var>[[NamedArraylist class|NamedArraylist]]</var>, for example, or a file, depending on how many certificates are in the list.
<li><var class="product">Janus Web Server</var> is not equipped to use the <var>XmlDoc</var> CRLs automatically; you have to process them yourself. Probably, for efficiency, you want to get the CRL at startup time, then store it somewhere easy to get at (a global <var>[[NamedArraylist class|NamedArraylist]]</var>, for example, or a file, depending on how many certificates are in the list.
<li>Currently, no method is available to produce a DER stream from an <var>XmlDoc</var> nor to validate the signature on a CRL.
<li>Currently, no method is available to produce a DER stream from an <var>XmlDoc</var> nor to validate the signature on a CRL. </li>
</ul>
</ul>


Line 36: Line 33:


The result is shown in part below:
The result is shown in part below:
<p class="code">
<p class="code"><CertificateList>
<CertificateList>
   <tbsCertList>
   <tbsCertList>
       <signature>
       <signature>
Line 86: Line 82:
   ...
   ...
</CertificateList>
</CertificateList>
</p>
</p></li>


<li>If you have a web port from which you can get a CRL, you might do something like this:  
<li>If you have a web port from which you can get a CRL, you might do something like this:  
Line 92: Line 88:
%httpResponse = %httpRequest:[[Get (HttpRequest function)|Get]]
%httpResponse = %httpRequest:[[Get (HttpRequest function)|Get]]
%doc = %httpResponse:X509CrlToXmlDoc </p>
%doc = %httpResponse:X509CrlToXmlDoc </p>
'''Note:''' Janus will not validate a signature on a CRL returned by a <var>Get</var>.  
<p class="note">'''Note:''' Janus will not validate a signature on a CRL returned by a <var>Get</var>. </p></li>
</ol>
</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>
<ul>
<li><var>String</var> class: <var>[[DerToXmlDoc_(String_function)|DerToXmlDoc]]</var>, <var>[[X509CertificateToXmlDoc_(String_function)|X509CertificateToXmlDoc]]</var>, and <var>[[RSAPrivateKeyToXmlDoc _(String_function)|RSAPrivateKeyToXmlDoc]]</var>
<li><var>[[ClientCertificate (System function)|ClientCertificate]]</var> </li>
<li><var>System</var> class: <var>[[ClientCertificate (System function)|ClientCertificate]]</var>  
<li><var>[[GeneratedPrivateKey (System function)|GeneratedPrivateKey]]</var> </li>
<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>
<p>
<var>Socket</var> methods: </p>
<ul>
<li><var>[[Certificate (Socket function)|Certificate]]</var> </li>
</ul>
Background information:
<ul>
<li>[http://en.wikipedia.org/wiki/Abstract_Syntax_Notation_One "Abstract Syntax Notation One"]
<li>[http://luca.ntop.org/Teaching/Appunti/asn1.html "A Layman's Guide to a Subset of ASN.1, BER, and DER"]
</ul>
{{Template:String:X509CrlToXmlDoc footer}}
{{Template:String:X509CrlToXmlDoc footer}}

Latest revision as of 15:09, 6 September 2018

Convert BER encoded X.509 CRL 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 list (CRLs), and more. X509CrlToXmlDoc converts a string (Longstring) that contains a CRL 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:X509CrlToXmlDoc 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 CRL (Certificate Revocation List).

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.
  • X509CrlToXmlDoc is very similar to DerToXmlDoc, except that X509CrlToXmlDoc understands the semantics of the CRL tags, so it provides more meaningful XML element names. Contrast the DerToXmlDoc example with the X509CrlToXmlDoc example, below.
  • X509CrlToXmlDoc is a complete implementation of the PKCS standards for CRLs.
  • Janus Web Server is not equipped to use the XmlDoc CRLs automatically; you have to process them yourself. Probably, for efficiency, you want to get the CRL at startup time, then store it somewhere easy to get at (a global NamedArraylist, for example, or a file, depending on how many certificates are in the list.
  • Currently, no method is available to produce a DER stream from an XmlDoc nor to validate the signature on a CRL.

Examples

  1. The PemToString example loads a Longstring with the contents of the base64 encoded CRL (Certificate Revocation List). If that Longstring is %ls below, the following statement converts that string to the XmlDoc whose contents are printed thereafter:

    %ls:x509CrlToXmlDoc:print

    The result is shown in part below:

    <CertificateList> <tbsCertList> <signature> <algorithm name="md5WithRSAEncryption"> 1.2.840.113549.1.1.4 </algorithm> <parameters/> </signature> <issuer> <RelativeDistinguishedName> <countryName>AU</countryName> </RelativeDistinguishedName> <RelativeDistinguishedName> <stateOrProvinceName type="PrintableString"> QLD </stateOrProvinceName> </RelativeDistinguishedName> ... </issuer> <thisUpdate type="UTCTime"> 20010115162657.000Z </thisUpdate> <nextUpdate type="UTCTime"> 20010214162657.000Z </nextUpdate> <revokedCertificates> <revokedCertificate> <userCertificate>1</userCertificate> <revocationDate type="UTCTime"> 19951009233205.000Z </revocationDate> </revokedCertificate> <revokedCertificate> <userCertificate>3</userCertificate> <revocationDate type="UTCTime"> 19951201010000.000Z </revocationDate> </revokedCertificate> <revokedCertificate> <userCertificate>4660</userCertificate> <revocationDate type="UTCTime"> 20010115161947.000Z </revocationDate> </revokedCertificate> ... </revokedCertificates> </tbsCertList> ... </CertificateList>

  2. If you have a web port from which you can get a CRL, you might do something like this:

    %httprequest:url = %crlUrl %httpResponse = %httpRequest:Get %doc = %httpResponse:X509CrlToXmlDoc

    Note: Janus will not validate a signature on a CRL returned by a Get.

See also

String methods:

Stringlist methods:

System methods:

Socket methods:

Background information: