ClientCertificate (XmlDoc function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
m (→‎Example: minoir formatting)
 
(13 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Template:XmlDoc:ClientCertificate subtitle}}
{{Template:XmlDoc:ClientCertificate subtitle}}


This shared method produces an XmlDoc object that contains
This shared method produces an <var>XmlDoc</var> object that contains
detailed information from a client certificate received by a Janus web server,
detailed information from a client certificate received by a <var class="product">Janus Web Server</var>,
server socket, or Telnet server.
server socket, or <var>Telnet</var> server.
The XmlDoc includes details
The <var>XmlDoc</var> includes details about the client and about the certificate's signer.
about the client and about the certificate's signer.


The ClientCertificate method is new as of version 7.5 of the ''Sirius Mods''.
The <var>ClientCertificate</var> method is new as of version 7.5 of the <var class="product">Sirius Mods</var>.


==Syntax==
==Syntax==
Line 18: Line 17:


<tr><th nowrap="true"><var>[%(XmlDoc):]</var></th>
<tr><th nowrap="true"><var>[%(XmlDoc):]</var></th>
<td>The optional class name in parentheses denotes a [[Notation conventions for methods#Shared methods|virtual constructor]] method. See [[#Usage notes|"Usage notes"]], below, for more information about invoking an <var>XmlDoc</var>constructor.</td></tr>
<td>The optional class name in parentheses denotes a [[Notation conventions for methods#Shared methods|virtual constructor]] method. See [[#Usage notes|Usage notes]], below, for more information about invoking an <var>XmlDoc</var> virtual constructor.</td></tr>


<tr><th nowrap>AttributeNames= bool</th>
<tr><th nowrap><var>AttributeValues</var></th>
<td>This [[Notation conventions for methods#Named parameters|name required]] argument is a <var>[[Boolean enumeration|Boolean]]</var> value that indicates whether certificate detail names are to be displayed within their XML document elements as the element name or as the value of a "name" attribute.
<td>This [[Notation conventions for methods#Named parameters|name required]] argument (<tt>AttributeValues</tt>) is a <var>[[Boolean enumeration|Boolean]]</var> value that indicates whether certificate detail values are to be displayed as text or as value attributes within their XML document elements.
<p>
 
For example, for the certificate detail named "locality": </p>
For example, <code><serialNumber>016437FF8A</serialNumber></code>  is text format,
and  <code><serialNumber value="016437FF8A"/></code>  is attribute-value format.
 
The default value is <var>False</var>, which produces text format.</td></tr>
 
<tr><th><var>AttributeNames</var></th>
<td>This name required argument is a <var>Boolean</var> value that indicates whether certificate detail names are to be displayed within their XML document elements as the element name or as the value of a "name" attribute.
 
For example, for the certificate detail named "locality":  
<ul>
<ul>
<li>Element-name format is:
<li>Element-name format is:
<p class="code">
<p class="code"><locality>Cambridge</locality>
    <locality>Cambridge</locality>
</p>
</p>
<li>Name-attribute format is:
<li>Name-attribute format is:
<p class="code">
<p class="code"><info name="locality">
    <info name="locality">
  Cambridge
      Cambridge
</info>
    </info>
</p>
</p>
</ul>
</ul>
<p>
<p>
The default value is <tt>False</tt>, which produces element-name format.</p></td></tr>
The default value is <var>False</var>, which produces element-name format.</p></td></tr>
 
<tr><th>AttributeValues= bool</th>
<td>This name required argument (<tt>AttributeValues</tt>) is a boolean value
that indicates whether certificate detail values
are to be displayed as text or as value attributes within
their XML document elements.
 
For example,  <tt><serialNumber>016437FF8A</serialNumber></tt>  is text format,
and  <tt><serialNumber value="016437FF8A"/></tt>  is attribute-value format.
 
The default value is <tt>False</tt>, which produces text format.</td></tr>
</table>
</table>


Line 59: Line 53:


%doc = %doc:ClientCertificate
%doc = %doc:ClientCertificate
</p>
</p></li>
<li>The XmlDoc object produced by the ClientCertificate method is Null if:
 
<li>The <var>XmlDoc</var> object produced by the <var>ClientCertificate</var> method is <var>Null</var> if:
<ul>
<ul>
<li>The method is invoked in a scenario where there is no client certificate.
<li>The method is invoked in a scenario where there is no client certificate.</li>
<li>The method is invoked when you are not logged in on a Janus server port.
<li>The method is invoked when you are not logged in on a Janus server port.</li>
<li>The Janus port is not defined to use SSL.
<li>The Janus port is not defined to use SSL.</li>
<li>The client did not provide a certificate.
<li>The client did not provide a certificate.</li>
</ul>
</ul></li>
 
<li>If your site is using client certificate authentication,
<li>If your site is using client certificate authentication,
the information returned by this method is most useful in the server port's
the information returned by this method is most useful in the server port's
JANUS DEFINE NEWSESCMD processing.
<var>JANUS DEFINE NEWSESCMD</var> processing.
The information method can be used anywhere:
The information method can be used anywhere:
no information in the client certificate is considered "secure."
no information in the client certificate is considered "secure." </li>
<li>As of ''Sirius Mods'' 7.7,
 
if a Janus SSL server program issues the ClientCertificate method, the returned
<li>As of <var class="product">Sirius Mods</var> 7.7,
XmlDoc will be Null if
if a Janus SSL server program issues the <var>ClientCertificate</var> method, the returned
the server port definition includes the SSLCLCERT or SSLCLCERTR parameter.
<var>XmlDoc</var> will be <var>Null</var> if
Those JANUS DEFINE parameters cause a request for a client certificate in the
the server port definition includes the <var>[[SSLCLCERT and SSLCLCERTR|SSLCERT]]</var> or <var>[[SSLCLCERT and SSLCLCERTR|SSLCLCERTR]]</var> parameter.
Those <var>[[JANUS DEFINE]]</var> parameters cause a request for a client certificate in the
initial server-client handshake that establishes the SSL connection.
initial server-client handshake that establishes the SSL connection.
The ClientCertificate method call in this case would be a second request
The <var>ClientCertificate</var> method call in this case would be a second request for a certificate,
for a certificate,
and a client certificate may only be requested once for an SSL session
and a client certificate may only be requested once for an SSL session
(whether or not the request successfully gets a certificate in return).
(whether or not the request successfully gets a certificate in return).
 
<p>
If neither of those JANUS DEFINE parameters are present,
If neither of those <var>JANUS DEFINE</var> parameters are present,
a server's ClientCertificate method call will cause an SSL
a server's <var>ClientCertificate</var> method call will cause an SSL
renegotiation (that is, a new handshake) that requests a digital certificate
renegotiation (that is, a new handshake) that requests a digital certificate
from the client.
from the client.
This allows a port to require a client certificate for
This allows a port to require a client certificate for
some content, but not for other content.
some content, but not for other content.</p>
 
<p>
In the renegotiation, the server requests a certificate, but does '''not'''
In the renegotiation, the server requests a certificate, but does '''not'''
insist that the client present one.
insist that the client present one.
The returned XmlDoc from the method call may therefore still be Null
The returned <var>XmlDoc</var> from the method call may therefore still be <var>Null</var>
because no certificate was provided.
because no certificate was provided.</p>
 
<p>
If another function or method causes a renegotiation by requesting
If another function or method causes a renegotiation by requesting
a client certificate, a subsequent ClientCertificate call will
a client certificate, a subsequent <var>ClientCertificate</var> call will '''not''' cause another
'''not''' cause another
request for a client certificate, whether or not a client certificate
request for a client certificate, whether or not a client certificate
was returned for the initial renegotiation.
was returned for the initial renegotiation.
This is because:
This is because:</p>
<ul>
<ul>
<li>There is no reason a client would not return a certificate on an initial
<li>There is no reason a client would not return a certificate on an initial
renegotiation, but return a certificate on a later renegotiation.
renegotiation, but return a certificate on a later renegotiation. </li>
<li>There is no reason a client would return a certificate on an initial
 
renegotiation, then
<li>There is no reason a client would return a certificate on an initial renegotiation, then
return a different client certificate on a subsequent SSL renegotiation.
return a different client certificate on a subsequent SSL renegotiation. </li>
</ul>
</ul></li>
 
<li>The <var>ClientCertificate</var> method provides much of the functionality of functions
in <var class="product">[[Janus Web Server]]</var> (<var>[[$Web_Cert_Info]]</var> and <var>[[$Web_Cert_Levels]]</var>) and <var class="product">[[Janus Sockets]]</var> (<var>[[$Sock_Cert_Info]]</var> and <var>[[$Sock_Cert_Levels]]</var>). </li>
</ul>
</ul>
===Example===
===Example===
The following request prints the contents of a client certificate:
The following request prints the contents of a client certificate:
<pre>
<p class="code">Begin
    Begin
%doc Object XmlDoc
    %doc Object XmlDoc
%doc = ClientCertificate
    %doc = ClientCertificate
%doc:Print
    %doc:Print
End
    End
</p>
</pre>


A sample result follows:
A sample result follows:
<pre>
<p class="output"><subject>
    <subject>
  <commonName>USER</commonName>
       <commonName>USER</commonName>
  <organizationalUnit>Local Services</organizationalUnit>
       <organizationalUnit>Local Services</organizationalUnit>
  <locality>Cambridge</locality>
  <state>MA</state>
  <country>US</country>
  <validityDate>20090125050000</validityDate>
  <validityTime>20090125050000</validityTime>
  <expirationDate>20100125050000</expirationDate>
  <expirationTime>20100125050000</expirationTime>
  <serialNumber>016437FF8A</serialNumber>
  <privateKeyLength>1024</privateKeyLength>
  <md5hash>7291D676CF47AF9578C94EEF029FA7BF</md5hash>
  <shaHash>8C969F3CCD1997082924EFD386B144917EF07F24</shaHash>
  <permanentKeyLength>1024</permanentKeyLength>
  <temporaryKeyLength>0</temporaryKeyLength>
  <issuer>
       <commonName>sis.sirius-software.com</commonName>
       <organizationalUnit>Local-Systems</organizationalUnit>
       <locality>Cambridge</locality>
       <locality>Cambridge</locality>
       <state>MA</state>
       <state>Massachusetts</state>
       <country>US</country>
       <country>USA</country>
       <validityDate>20090125050000</validityDate>
       <validityDate>20081210123238</validityDate>
       <validityTime>20090125050000</validityTime>
       <validityTime>20081210123238</validityTime>
       <expirationDate>20100125050000</expirationDate>
       <expirationDate>20110907123238</expirationDate>
       <expirationTime>20100125050000</expirationTime>
       <expirationTime>20110907123238</expirationTime>
       <serialNumber>016437FF8A</serialNumber>
       <serialNumber>0160B99097</serialNumber>
       <privateKeyLength>1024</privateKeyLength>
       <privateKeyLength>512</privateKeyLength>
       <md5hash>7291D676CF47AF9578C94EEF029FA7BF</md5hash>
       <md5hash>681A76D6208C594D5BB08E816324E92B</md5hash>
       <shaHash>8C969F3CCD1997082924EFD386B144917EF07F24</shaHash>
       <shaHash>513085FC5F652EDAC8759C4921842FF8B38ABEA2</shaHash>
       <permanentKeyLength>1024</permanentKeyLength>
       <permanentKeyLength>512</permanentKeyLength>
       <temporaryKeyLength>0</temporaryKeyLength>
       <temporaryKeyLength>0</temporaryKeyLength>
       <issuer>
       <issuer>
           <commonName>sis.sirius-software.com</commonName>
           <commonName>sis.sirius-software.com</commonName>
           <organizationalUnit>Local-Systems</organizationalUnit>
           <organizationalUnit>Local&hyph.Systems</organizationalUnit>
           <locality>Cambridge</locality>
           <locality>Cambridge</locality>
           <state>Massachusetts</state>
           <state>Massachusetts</state>
Line 154: Line 166:
           <permanentKeyLength>512</permanentKeyLength>
           <permanentKeyLength>512</permanentKeyLength>
           <temporaryKeyLength>0</temporaryKeyLength>
           <temporaryKeyLength>0</temporaryKeyLength>
          <issuer>
            <commonName>sis.sirius-software.com</commonName>
            <organizationalUnit>Local&hyph.Systems</organizationalUnit>
            <locality>Cambridge</locality>
            <state>Massachusetts</state>
            <country>USA</country>
            <validityDate>20081210123238</validityDate>
            <validityTime>20081210123238</validityTime>
            <expirationDate>20110907123238</expirationDate>
            <expirationTime>20110907123238</expirationTime>
            <serialNumber>0160B99097</serialNumber>
            <privateKeyLength>512</privateKeyLength>
            <md5hash>681A76D6208C594D5BB08E816324E92B</md5hash>
            <shaHash>513085FC5F652EDAC8759C4921842FF8B38ABEA2</shaHash>
            <permanentKeyLength>512</permanentKeyLength>
            <temporaryKeyLength>0</temporaryKeyLength>
          </issuer>
       </issuer>
       </issuer>
     </subject>
     </issuer>
</pre>
</subject>
</p>


===Request-Cancellation Errors (for set method)===
===Request-Cancellation Errors (for set method)===
<ul>
<ul>
<li>ClientCertificate has no request cancellation errors.
<li><var>ClientCertificate</var> has no request cancellation errors.
</ul>
</ul>


Line 183: Line 179:
==See also==
==See also==
{{Template:XmlDoc:ClientCertificate footer}}
{{Template:XmlDoc:ClientCertificate footer}}
<ul>
<li>The ClientCertificate method provides much of the functionality of functions
in [[Janus Web Server]] ($Web_Cert_Info and $Web_Cert_Levels) and [[Janus Sockets]]
($Sock_Cert_Info and $Sock_Cert_Levels).
</ul>

Latest revision as of 18:48, 25 May 2016

Create XmlDoc with client certificate details (XmlDoc class)


This shared method produces an XmlDoc object that contains detailed information from a client certificate received by a Janus Web Server, server socket, or Telnet server. The XmlDoc includes details about the client and about the certificate's signer.

The ClientCertificate method is new as of version 7.5 of the Sirius Mods.

Syntax

%doc = [%(XmlDoc):]ClientCertificate[( [AttributeValues= boolean], - [AttributeNames= boolean])]

Syntax terms

%doc An XmlDoc, which will contain the client certificate information.
[%(XmlDoc):] The optional class name in parentheses denotes a virtual constructor method. See Usage notes, below, for more information about invoking an XmlDoc virtual constructor.
AttributeValues This name required argument (AttributeValues) is a Boolean value that indicates whether certificate detail values are to be displayed as text or as value attributes within their XML document elements.

For example, <serialNumber>016437FF8A</serialNumber> is text format, and <serialNumber value="016437FF8A"/> is attribute-value format.

The default value is False, which produces text format.
AttributeNames This name required argument is a Boolean value that indicates whether certificate detail names are to be displayed within their XML document elements as the element name or as the value of a "name" attribute.

For example, for the certificate detail named "locality":

  • Element-name format is:

    <locality>Cambridge</locality>

  • Name-attribute format is:

    <info name="locality"> Cambridge </info>

The default value is False, which produces element-name format.

Usage notes

  • ClientCertificate is a virtual constructor and as such can be called with no method object, with an explicit class name, or with an object variable, even if that object is null:

    %doc = ClientCertificate %doc = %(XmlDoc):ClientCertificate %doc = %doc:ClientCertificate

  • The XmlDoc object produced by the ClientCertificate method is Null if:
    • The method is invoked in a scenario where there is no client certificate.
    • The method is invoked when you are not logged in on a Janus server port.
    • The Janus port is not defined to use SSL.
    • The client did not provide a certificate.
  • If your site is using client certificate authentication, the information returned by this method is most useful in the server port's JANUS DEFINE NEWSESCMD processing. The information method can be used anywhere: no information in the client certificate is considered "secure."
  • As of Sirius Mods 7.7, if a Janus SSL server program issues the ClientCertificate method, the returned XmlDoc will be Null if the server port definition includes the SSLCERT or SSLCLCERTR parameter. Those JANUS DEFINE parameters cause a request for a client certificate in the initial server-client handshake that establishes the SSL connection. The ClientCertificate method call in this case would be a second request for a certificate, and a client certificate may only be requested once for an SSL session (whether or not the request successfully gets a certificate in return).

    If neither of those JANUS DEFINE parameters are present, a server's ClientCertificate method call will cause an SSL renegotiation (that is, a new handshake) that requests a digital certificate from the client. This allows a port to require a client certificate for some content, but not for other content.

    In the renegotiation, the server requests a certificate, but does not insist that the client present one. The returned XmlDoc from the method call may therefore still be Null because no certificate was provided.

    If another function or method causes a renegotiation by requesting a client certificate, a subsequent ClientCertificate call will not cause another request for a client certificate, whether or not a client certificate was returned for the initial renegotiation. This is because:

    • There is no reason a client would not return a certificate on an initial renegotiation, but return a certificate on a later renegotiation.
    • There is no reason a client would return a certificate on an initial renegotiation, then return a different client certificate on a subsequent SSL renegotiation.
  • The ClientCertificate method provides much of the functionality of functions in Janus Web Server ($Web_Cert_Info and $Web_Cert_Levels) and Janus Sockets ($Sock_Cert_Info and $Sock_Cert_Levels).

Example

The following request prints the contents of a client certificate:

Begin %doc Object XmlDoc %doc = ClientCertificate %doc:Print End

A sample result follows:

<subject> <commonName>USER</commonName> <organizationalUnit>Local Services</organizationalUnit> <locality>Cambridge</locality> <state>MA</state> <country>US</country> <validityDate>20090125050000</validityDate> <validityTime>20090125050000</validityTime> <expirationDate>20100125050000</expirationDate> <expirationTime>20100125050000</expirationTime> <serialNumber>016437FF8A</serialNumber> <privateKeyLength>1024</privateKeyLength> <md5hash>7291D676CF47AF9578C94EEF029FA7BF</md5hash> <shaHash>8C969F3CCD1997082924EFD386B144917EF07F24</shaHash> <permanentKeyLength>1024</permanentKeyLength> <temporaryKeyLength>0</temporaryKeyLength> <issuer> <commonName>sis.sirius-software.com</commonName> <organizationalUnit>Local-Systems</organizationalUnit> <locality>Cambridge</locality> <state>Massachusetts</state> <country>USA</country> <validityDate>20081210123238</validityDate> <validityTime>20081210123238</validityTime> <expirationDate>20110907123238</expirationDate> <expirationTime>20110907123238</expirationTime> <serialNumber>0160B99097</serialNumber> <privateKeyLength>512</privateKeyLength> <md5hash>681A76D6208C594D5BB08E816324E92B</md5hash> <shaHash>513085FC5F652EDAC8759C4921842FF8B38ABEA2</shaHash> <permanentKeyLength>512</permanentKeyLength> <temporaryKeyLength>0</temporaryKeyLength> <issuer> <commonName>sis.sirius-software.com</commonName> <organizationalUnit>Local&hyph.Systems</organizationalUnit> <locality>Cambridge</locality> <state>Massachusetts</state> <country>USA</country> <validityDate>20081210123238</validityDate> <validityTime>20081210123238</validityTime> <expirationDate>20110907123238</expirationDate> <expirationTime>20110907123238</expirationTime> <serialNumber>0160B99097</serialNumber> <privateKeyLength>512</privateKeyLength> <md5hash>681A76D6208C594D5BB08E816324E92B</md5hash> <shaHash>513085FC5F652EDAC8759C4921842FF8B38ABEA2</shaHash> <permanentKeyLength>512</permanentKeyLength> <temporaryKeyLength>0</temporaryKeyLength> </issuer> </issuer> </subject>

Request-Cancellation Errors (for set method)

  • ClientCertificate has no request cancellation errors.


See also

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