PemToString (Stringlist function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
m (→‎See also: add method to list)
 
(31 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{Template:Stringlist:PemToString subtitle}}
{{Template:Stringlist:PemToString subtitle}}
 
The PEM (Privacy Enhanced Mail) protocol uses base64 encoding for binary data that needs to be transferred and stored as text.
The PEM (Privacy Enhanced Mail) protocol is for securing email.


==Syntax==
==Syntax==
{{Template:Stringlist:PemToString syntax}}
{{Template:Stringlist:PemToString syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%string</th><td>string</td></tr>
<tr><th>%string</th>
<td>A <var>Longstring</var> or <var>String</var> to contain the decoded binary data in the method object, <var class="term">sl</var>.</td></tr>
 
<tr><th>sl</th>
<tr><th>sl</th>
<td>Stringlist object</td></tr>
<td>A <var>Stringlist</var> object that contains base64 encoded data.</td></tr>
 
<tr><th>label</th>
<tr><th>label</th>
<td>string</td></tr>
<td>The string that identifies the base64 encoded data you want to convert. Examples include <code>X509 CERTIFICATE</code>, <code>X509 CRL</code>, <code>RSA PRIVATE KEY</code>. X509 certificate, private key, and CRL data will be contained within the text markers <code>-----BEGIN <i>label</i>-----</code> and <code>-----END <i>label</i>-----</code>.
<p>
This is a required, case-sensitive, value. If it does not match the first and last items of a block of data within <var class="term">sl</var>, no data is returned to <var class="term">%string</var>. </p></td></tr>
 
<tr><th><var>Occurrence</var></th>
<tr><th><var>Occurrence</var></th>
<td>The occurrence number of the requested tag.</td></tr>
<td>The occurrence number within <var class="term">sl</var> of data labeled with <var class="term">label</var>.</td></tr>
</table>
</table>
===Exceptions===
<var>PemToString</var> can throw the following [[Exceptions|exception]]:
<dl>
<dt><var>[[InvalidPemData class|InvalidPemData]]</var>
<dd>If the method encounters non-PEM-conforming data, properties of the exception object may indicate the line and position of the error.
</dl>


==Usage notes==
==Usage notes==
<ul>
<li><var>PemToString</var> converts the labeled and structured X509 base64 data you identify. To convert individual base64 strings, you can use the <var>[[StringToBase64 (String function)|StringToBase64 ]]</var> method.
</ul>
==Examples==
==Examples==
The following request loads <var>Longstring</var> <code>%ls</code> with the contents of the base-64 encoded CRL (Certificate Revocation List) contained in <var>Stringlist</var> <code>%sl</code>:<p class="code">   b                                                                
The following request loads <var>Longstring</var> <code>%ls</code> with the contents of the base64 encoded CRL (Certificate Revocation List) contained in <var>Stringlist</var> <code>%sl</code>:
                                                                     
<p class="code">b  
    %ls    is longstring                                            
%ls    is longstring            
    %sl    is object stringlist                                      
%sl    is object stringlist          
                                                                     
 
    text to %sl = new raw                                            
[[Text and Html statements#toOption|text to]] %sl = new raw  
      -----BEGIN X509 CRL-----                                      
  -----BEGIN X509 CRL-----  
      MIIBODCB4zANBgkqhkiG9w0BAQQFADBgMQswCQYDVQQGEwJBVTEMMAoGA1UECBMD
  MIIBODCB4zANBgkqhkiG9w0BAQQFADBgMQswCQYDVQQGEwJBVTEMMAoGA1UECBMD
      UUxEMRkwFwYDVQQKExBNaW5jb20gUHR5LiBMdGQuMQswCQYDVQQLEwJDUzEbMBkG
  UUxEMRkwFwYDVQQKExBNaW5jb20gUHR5LiBMdGQuMQswCQYDVQQLEwJDUzEbMBkG
      A1UEAxMSU1NMZWF5IGRlbW8gc2VydmVyFw0wMTAxMTUxNjI2NTdaFw0wMTAyMTQx
  A1UEAxMSU1NMZWF5IGRlbW8gc2VydmVyFw0wMTAxMTUxNjI2NTdaFw0wMTAyMTQx
      NjI2NTdaMFIwEgIBARcNOTUxMDA5MjMzMjA1WjASAgEDFw05NTEyMDEwMTAwMDBa
  NjI2NTdaMFIwEgIBARcNOTUxMDA5MjMzMjA1WjASAgEDFw05NTEyMDEwMTAwMDBa
      MBMCAhI0Fw0wMTAxMTUxNjE5NDdaMBMCAhI1Fw0wMTAxMTUxNjIzNDZaMA0GCSqG
  MBMCAhI0Fw0wMTAxMTUxNjE5NDdaMBMCAhI1Fw0wMTAxMTUxNjIzNDZaMA0GCSqG
      SIb3DQEBBAUAA0EAHPjQ3M93QOj8Ufi+jZM7Y78TfAzG4jJn/E6MYBPFVQFYo/Gp
  SIb3DQEBBAUAA0EAHPjQ3M93QOj8Ufi+jZM7Y78TfAzG4jJn/E6MYBPFVQFYo/Gp
      UZexfjSVo5CIyySOtYscz8oO7avwBxTiMpDEQg==                         
  UZexfjSVo5CIyySOtYscz8oO7avwBxTiMpDEQg==                         
      -----END X509 CRL-----                                        
  -----END X509 CRL-----      
    end text                                                          
end text  
                                                                     
 
    %ls = %sl:pemToString('X509 CRL')                                   
%ls = %sl:pemToString('X509 CRL')                                   
                                                                     
end  
    end                                                              
 
</p>
</p>


==See also==
==See also==
<p>
<var>Stringlist</var> methods: </p>
{{Template:Stringlist crypto methods}}
<p>
<var>String</var> methods:</p>
<ul>
<li><var>[[CertificateRequest (String function)|CertificateRequest]]</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>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>
<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:Stringlist:PemToString footer}}
{{Template:Stringlist:PemToString footer}}

Latest revision as of 15:16, 6 September 2018

Extract base64 encoded PEM data to string (Stringlist class)

[Introduced in Sirius Mods 8.0]

The PEM (Privacy Enhanced Mail) protocol uses base64 encoding for binary data that needs to be transferred and stored as text.

Syntax

%string = sl:PemToString( label, [Occurrence= number]) Throws InvalidPemData

Syntax terms

%string A Longstring or String to contain the decoded binary data in the method object, sl.
sl A Stringlist object that contains base64 encoded data.
label The string that identifies the base64 encoded data you want to convert. Examples include X509 CERTIFICATE, X509 CRL, RSA PRIVATE KEY. X509 certificate, private key, and CRL data will be contained within the text markers -----BEGIN label----- and -----END label-----.

This is a required, case-sensitive, value. If it does not match the first and last items of a block of data within sl, no data is returned to %string.

Occurrence The occurrence number within sl of data labeled with label.

Exceptions

PemToString can throw the following exception:

InvalidPemData
If the method encounters non-PEM-conforming data, properties of the exception object may indicate the line and position of the error.

Usage notes

  • PemToString converts the labeled and structured X509 base64 data you identify. To convert individual base64 strings, you can use the StringToBase64 method.

Examples

The following request loads Longstring %ls with the contents of the base64 encoded CRL (Certificate Revocation List) contained in Stringlist %sl:

b %ls is longstring %sl is object stringlist text to %sl = new raw -----BEGIN X509 CRL----- MIIBODCB4zANBgkqhkiG9w0BAQQFADBgMQswCQYDVQQGEwJBVTEMMAoGA1UECBMD UUxEMRkwFwYDVQQKExBNaW5jb20gUHR5LiBMdGQuMQswCQYDVQQLEwJDUzEbMBkG A1UEAxMSU1NMZWF5IGRlbW8gc2VydmVyFw0wMTAxMTUxNjI2NTdaFw0wMTAyMTQx NjI2NTdaMFIwEgIBARcNOTUxMDA5MjMzMjA1WjASAgEDFw05NTEyMDEwMTAwMDBa MBMCAhI0Fw0wMTAxMTUxNjE5NDdaMBMCAhI1Fw0wMTAxMTUxNjIzNDZaMA0GCSqG SIb3DQEBBAUAA0EAHPjQ3M93QOj8Ufi+jZM7Y78TfAzG4jJn/E6MYBPFVQFYo/Gp UZexfjSVo5CIyySOtYscz8oO7avwBxTiMpDEQg== -----END X509 CRL----- end text %ls = %sl:pemToString('X509 CRL') end

See also

Stringlist methods:

String methods:

System methods:

Socket methods:

Background information: