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 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, |
| 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":
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.