$Web_Cert_Info

Retrieve client certificate information

$Web_Cert_Info retrieves information about the client or certificate signer from a received client certificate. The OO equivalent of this function is the X509CertificateToXmlDoc (String function), which provides certificate information in a more structured format. Use of the X509 methods is strongly recommended over the $function approach.

Syntax

%info = $Web_Cert_Info( item, [level] )

%info	A string containing the information associated with the requested item. For a non-SSL connection or a connection in which the client certificate is optional (SSLCLCERT, not SSLCLCERTR, is set on the JANUS DEFINE): if the client chooses not to send a certificate, $Web_Cert_Info returns a null. Also, if a certificate is received and the requested piece of information is not in the requested level, a null is returned.
item	The name of the certificate item to return. These items are described in detail in Client certificate items, below.
level	The certificate level from which the information is to be returned. Level 0 corresponds to the client or the "subject" of the certificate; level 1 to the "signer" of the certificate; level 2 to the "signer" of the level 1 signer's certificate; and so on. This is an optional parameter, and it defaults to 0.

Usage notes

• Janus Network Security accepts only client certificates that are signed by a trusted Certifying Authority (CA), whose signing certificate has been added to the port via the JANUS ADDCA command. Therefore, a $Web_Cert_Info call for level 1 (the signer) is guaranteed to return information already in a trusted CA certificate.
• If a Janus SSL server program issues $Web_Cert_Info or $Web_Cert_Levels, the returned string 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 $Web_Cert_Info or $Web_Cert_Levels 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 specified, a server's $Web_Cert_Info or $Web_Cert_Levels 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 string 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 $Web_Cert_Info or $Web_Cert_Levels 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.

Client certificate items

The following items can be requested with $Web_Cert_Info:

COMMONNAME	Any name used to identify the client. Could be a first name/last name, an ID number, or even a userid. COMMONNAME can be abbreviated CN, CNAME, or COMMONN.
ORGANIZATIONALUNIT	The department or section of the organization to which the user belongs. For example, "Physics Department," "Accounts receivable," or "Web doods." ORGANIZATIONALUNIT can be abbreviated ORGU, ORGANIZATIONALU, or ORGUNIT.
ORGANIZATION	The company, government agency, school, or other organization to which the client belongs. For example, "Hard Knocks University," "Effete Recordings," or "bagsofconcrete.com." ORGANIZATION can be abbreviated ORG.
LOCALITY	The city, town, or village in which the subject resides or works. LOCALITY can be abbreviated LOC.
STATE	The state, province, or other intermediate governmental unit in which the subject resides or works. PROVINCE is a synonym for STATE.
COUNTRY	The country or nation in which the subject resides or works.
VALIDITYDATE	The date on which the subject's or signer's certificate became valid. Janus Network Security will not accept a client certificate where the subject's or signer's certificate is not yet valid, so use of this field is largely informational. VALIDITYDATE is returned as a date string in YYYYMMDDHHMISS format. VALIDITYDATE can be abbreviated VALIDDATE or VDATE, or it can be requested as VALIDITYTIME, VALIDTIME, or VTIME.
EXPIRATIONDATE	The date on which the subject's or signer's certificate becomes invalid. Janus Network Security will not accept a client certificate where the subject's or signer's certificate is no longer valid, so use of this field is largely informational, though it might prove useful in providing a warning to a user whose certificate is going to expire soon. EXPIRATIONDATE can be abbreviated EXPIRYDATE, EXPDATE, or EDATE, or it can be requested as EXPIRATIONTIME, EXPIRYTIME, EXPTIME, or ETIME.
SERIALNUMBER	The serial number of the subject's certificate as assigned by the signer. Certifying authorities should assign a unique serial number to each certificate they sign. The assigned serial number could be a number that goes up by one for each certificate signed by a certifying authority, or it could be a number derived from the date and time, for example. SERIALNUMBER is returned as a hexadecimal string with an even number of hexadecimal digits. Since the signer's certificate is generally "self-signed," it often does not have a serial number, that is, the level 1 serial number is usually returned as a null. While SERIALNUMBER doesn't have any particular significance from an application level, it can be used as an extra piece of identifying information for a client certificate. SERIALNUMBER can be abbreviated SERIALNUM, SERNUMBER, SERNUM, SERIAL or SER.
PRIVATEKEYLENGTH	The length of the private key used by the signer or the client. Private key lengths are usually expressed in terms of number of bits, so PRIVATEKEYLENGTH returns a decimal number string, such as "1024" or "2048". This value could be used to determine a "level of trustworthiness" of a client certificate, where a 1024-bit certificate is considered somewhat weak (though probably strong enough for all but the most extreme security requirements), and a 2048-bit certificate is considered strong. Janus Network Security will not accept certificates that indicate private keys shorter than 512 bits or longer than 4096 (as of version 7.7 of Model 204; formerly 2048 bits). Generally, client certificates use either a 1024-bit or a 2048-bit key. PRIVATEKEYLENGTH can be abbreviated PRIVATEKEYL, PKEYLENGTH, or PKEYL.
TEMPORARYKEYLENGTH	The length of the temporary or "ephemeral" private key. Since SSL client certificate support does not cover ephemeral private keys, and in fact, such support would be largely meaningless anyway, TEMPORARYKEYLENGTH always returns a 0. It is simply included here for compatibility with the equivalent Janus Sockets function ($Sock_Cert_Info) or Socket object method (CertInfo). TEMPORARYKEYLENGTH can be abbreviated TEMPORARYKEYL, TEMPKEYLENGTH or TEMPKEYL.
PERMANENTKEYLENGTH	The length of the permanent private key. Since SSL client certificate support does not cover ephemeral private keys, and in fact, such support would be largely meaningless anyway, PERMANENTKEYLENGTH always returns a the same value as PRIVATEKEYLENGTH. It is simply included here for compatibility with the equivalent Janus Sockets function ($Sock_Cert_Info) or Socket object method (CertInfo). PERMANENTKEYLENGTH can be abbreviated PERMANENTKEYL, PERMKEYLENGTH, or PERMKEYL.
MD5HASH	The MD5 hash or "digest" of the subject or issuer certificate. The MD5 hash of a certificate is shown by some browsers when displaying certificate information. An MD5 hash is always a 16-byte value, so MD5HASH always returns a 32-character hexadecimal string. Since it is basically impossible for any two different certificates to have the same MD5 hash, the MD5HASH value can be used in and of itself as a unique identification of a certificate. That is, if certificate information is stored in a database, the MD5 hash of the certificate can be used a primary unique key to locate the certificate. MD5HASH can be abbreviated MD5.
SHAHASH	The SHA hash or "digest" of the subject or issuer certificate. The SHA hash of a certificate is shown by some browsers when displaying certificate information. An SHA hash is always a 20-byte value, so SHAHASH always returns a 40-character hexadecimal string. Since it is basically impossible for any two different certificates to have the same SHA hash, the SHAHASH value can be used in and of itself as a unique identification of a certificate. That is, if certificate information is stored in a database, the SHA hash of the certificate can be used a primary unique key to locate the certificate. SHAHASH can be abbreviated SHA.