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