ClientCertificate (XmlDoc function)

Client certificate details

ClientCertificate is a member of the XmlDoc class.

This shared method is a constructor that 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 (        -
                       [AttributeNames=bool]     -
                       [, AttributeValues=bool] )

Syntax Terms

%doc

An XmlDoc, which will contain the client certificate information.

doc

An XmlDoc object expression.

AttributeNames= bool

This name required argument (AttributeNames) 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

• 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

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