ClientCertificate (XmlDoc function)

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 XmlDocconstructor.
AttributeNames= bool	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.
AttributeValues= bool	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.

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 SSLCLCERT 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.

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

XmlDoc class XmlNode class XmlNodelist class	List of XmlDoc methods List of XmlNode methods List of XmlNodelist methods List of XmlDoc API methods	XmlDoc methods syntax XmlNode methods syntax XmlNodelist methods syntax
Notation conventions for methods

• 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).