ClientCertificate (System function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
m (add <var>s)
 
(17 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Template:System:ClientCertificate subtitle}}
{{Template:System:ClientCertificate subtitle}}
The <var>ClientCertificate</var> function returns to a Janus server a longstring that contains the binary content of a client SSL certificate.        
The <var>ClientCertificate</var> function returns to a Janus server a <var>[[Longstrings|Longstring]]</var> that contains the binary content of a client SSL certificate.  
                                                                                
                                                                                
RequestCertificate=True indicates that if the port definition does not have   
SSLCLCERT or SLCLCERTR (client certificate requested at connection time),     
a certificate is requested from the client at the time of the method call.   
                                                                             
If no client certificate is present (possibly because the port is not using   
SSL), the ClientCertificate method returns a null string.                     
==Syntax==
==Syntax==
{{Template:System:ClientCertificate syntax}}
{{Template:System:ClientCertificate syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%string</th>
<tr><th>%string</th>
<td>This Longstring contains the binary content of the SSL certificate presented by this server's client.</td></tr>
<td>This <var>Longstring</var> contains a copy of the binary, ASN.1 encoded, content of the SSL certificate presented by this server's client. If no client certificate is provided (possibly because the port is not using SSL, or the certificate was already provided), <var class="term">%string</var> is a null string.  </td></tr>
<tr><th><var>%(System)</var></th>
 
<td>The class name in parentheses denotes a [[Notation conventions for methods#Shared methods and constructors|shared]] method. <var>String</var> can also be invoked via a <var>System</var> object variable, which may be <var>null</var>.</td></tr>
<tr><th><var class="nobr">%(System)</var></th>
<td>The class name in parentheses denotes a [[Notation conventions for methods#Shared methods|shared]] method. <var>ClientCertificate</var> can also be invoked via a <var>System</var> object variable, which may be <var>null</var>.</td></tr>
 
<tr><th><var>RequestCertificate</var></th>
<tr><th><var>RequestCertificate</var></th>
<td>This [[Notation conventions for methods#Named parameters|name required]] argument is a <var>[[Enumerations#Using Boolean enumerations|Boolean]]</var> enumeration. The argument defaults to <var>False</var>, which results .
<td>This [[Notation conventions for methods#Named parameters|name required]] argument is a <var>[[Enumerations#Using Boolean enumerations|Boolean]]</var> enumeration. If <var>True</var>, a certificate is requested from the client at the time of the method call. If <var>False</var>, no certificate is requested.
</td></tr>
</table>


==Usage notes==
==Usage notes==
<ul>
<ul>
<li>This method can be used only on a Janus Web Server, Janus Telnet Server, or Janus Sockets  
<li>This method can be used only on a <var class="product">Janus Web Server</var>, <var class="product">Janus Telnet Server</var>, or <var class="product">Janus Sockets</var> Server thread. If used on any other kind of thread, it throws a  
Server thread. If used on any other kind of thread, it throws a              
<var>[[NotJanusConnection class|NotJanusConnection]]</var> exception.
NotJanusConnection exception.  
 
<li>Specifying <code>RequestCertificate=True</code> only has an effect on a Janus <var>[[SSL]]</var> port whose definition does ''not'' include <var>[[SSLCLCERT and SSLCLCERTR|SSLCLCERT]]</var> or <var>[[SSLCLCERT and SSLCLCERTR|SSLCLCERTR]]</var>. These parameters request a client certificate at connection-establishment time, and a client certificate
may only be requested once for an SSL session (whether or not the request successfully gets a certificate in return).
</ul>
</ul>
NotJanusConnection is a new exception class that has        
 
no members other than the New constructor.
==Examples==
Probably the best way to examine the contents of the client certificate is by using the <var>[[X509CertificateToXmlDoc (String function)|X509CertificateToXmlDoc]]</var> <var>String</var> method to convert the <var>Longstring</var> containing the client certificate to an <var>XmlDoc</var>, as in the following:
<p class="code">%doc  is object xmlDoc
%ls  is longstring
%doc  is object xmlDoc
%node is object xmlNode
...
%ls = %(system):clientCertificate
if %ls:length then
  %doc = %ls:x509CertificateToXmlDoc
  %node = %doc:selectSingleNode('/Certificate/tbsCertificate/subject')
  if %node:value('RelativeDistinguishedName/commonName') ne "myBuddy.com" then
      $web_done(403, "Forbidden")
       stop
  end if
end if
</p>


==See also==
==See also==
<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>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>[[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>Socket</var> methods: </p>
<ul>
<li><var>[[Certificate (Socket function)|Certificate]]</var> </li>
</ul>
<p><var>HttpRequest</var> methods: </p>
<ul>
<li><var>[[Get (HttpRequest function)|Get]]</var>, <var>[[Post (HttpRequest function)|Post]]</var>, and <var>[[Send (HttpRequest function)|Send]]</var> </li>
</ul>
<p>
Background information: </p>
<ul>
<li>[https://en.wikipedia.org/wiki/RSA_(cryptosystem) RSA (cryptosystem)]</li>
</ul>
{{Template:System:ClientCertificate footer}}
{{Template:System:ClientCertificate footer}}

Latest revision as of 21:39, 1 September 2016

Get client certificate (System class)

[Introduced in Sirius Mods 8.0]

The ClientCertificate function returns to a Janus server a Longstring that contains the binary content of a client SSL certificate.

Syntax

%string = %(System):ClientCertificate[( [RequestCertificate= boolean])] Throws NotJanusConnection

Syntax terms

%string This Longstring contains a copy of the binary, ASN.1 encoded, content of the SSL certificate presented by this server's client. If no client certificate is provided (possibly because the port is not using SSL, or the certificate was already provided), %string is a null string.
%(System) The class name in parentheses denotes a shared method. ClientCertificate can also be invoked via a System object variable, which may be null.
RequestCertificate This name required argument is a Boolean enumeration. If True, a certificate is requested from the client at the time of the method call. If False, no certificate is requested.

Usage notes

  • This method can be used only on a Janus Web Server, Janus Telnet Server, or Janus Sockets Server thread. If used on any other kind of thread, it throws a NotJanusConnection exception.
  • Specifying RequestCertificate=True only has an effect on a Janus SSL port whose definition does not include SSLCLCERT or SSLCLCERTR. These parameters request a client certificate at connection-establishment time, and a client certificate may only be requested once for an SSL session (whether or not the request successfully gets a certificate in return).

Examples

Probably the best way to examine the contents of the client certificate is by using the X509CertificateToXmlDoc String method to convert the Longstring containing the client certificate to an XmlDoc, as in the following:

%doc is object xmlDoc %ls is longstring %doc is object xmlDoc %node is object xmlNode ... %ls = %(system):clientCertificate if %ls:length then %doc = %ls:x509CertificateToXmlDoc %node = %doc:selectSingleNode('/Certificate/tbsCertificate/subject') if %node:value('RelativeDistinguishedName/commonName') ne "myBuddy.com" then $web_done(403, "Forbidden") stop end if end if

See also

System methods:

Stringlist methods:

String methods:

Socket methods:

HttpRequest methods:

Background information:

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=ClientCertificate_(System_function)&oldid=93923"