CertInfo (Socket function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
m (add 7.7 maximum length)
 
(16 intermediate revisions by 4 users not shown)
Line 1: Line 1:
<span class="pageSubtitle"><section begin=dpl_desc/><section end=dpl_desc/></span>
{{Template:Socket:CertInfo subtitle}}
[[Category:Socket methods|CertInfo function]]
<p>
<var>CertInfo</var> is a member of the <var>[[Socket class|Socket]]</var> class.
</p>


This method retrieves the value of an entity for one of the
This method retrieves the value of an entity for one of the
levels of the SSL certificate provided on a socket by the remote partner.
levels of the SSL certificate provided on a socket by the remote partner.
The <var>CertInfo</var> function has an effect similar to
The <var>CertInfo</var> function has an effect similar to
its equivalent $function, <var>[[$Sock_cert_info]]</var>.
its equivalent $function, <var>[[$Sock_Cert_Info]]</var>.
 
==Syntax==
==Syntax==
<p class="syntax">%ci = %socko:CertInfo(entity, [level])
{{Template:Socket:CertInfo syntax}}
</p>
 
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table>
<tr><th>%ci</th>
<tr><th>%string</th>
<td>Return string, which contains the value of the requested entity at the requested level of the certificate supplied by the remote partner. If no such certificate was provided, the null string is returned.
<td>Return string, which contains the value of the requested entity at the requested level of the certificate supplied by the remote partner. If no such certificate was provided, the null string is returned.
</td></tr>
</td></tr>
<tr><th>%socko</th>
 
<tr><th>socket</th>
<td>A variable or an expression that is a reference to a socket object.
<td>A variable or an expression that is a reference to a socket object.
</td></tr>
</td></tr>
<tr><th>entity</th>
 
<td>The name of the requested entity, the options for which are listed below.
<tr><th>string</th>
</td></tr>
<td>The name of the requested entity, the options for which are listed below. </td></tr>
<tr><th>level</th>
 
<tr><th>number</th>
<td>The certificate level at which to obtain the entity. 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.
<td>The certificate level at which to obtain the entity. 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 argument is optional; the default value is 1.
This argument is optional; the default value is 1.
For more information about certificate levels, see the [http://www.sirius-software/maint/download/jansslr.pdf Janus Network Security Reference Manual].
For more information about certificate levels, see the <var>[[CertLevels (Socket function)|CertLevels]]</var> function and see <var class="product">[[Janus Network Security]]</var>.
 
</td></tr>
</td></tr></table>
</table>


==Certificate entities==
The following entities can be requested with <var>CertInfo</var>:
The following entities can be requested with <var>CertInfo</var>:
<table>
<table class="thJustBold">
<tr><th>COMMONNAME
<tr><th>COMMONNAME
</th><td>Any name used to identify the client. Could be a first name/last name, an ID number, or even a userid.
</th><td>Any name used to identify the client. Could be a first name/last name, an ID number, or even a userid. <var>COMMONNAME</var> can be abbreviated <var>CN</var>, <var>CNAME</var>, or <var>COMMONN</var>.
<var>COMMONNAME</var> can be abbreviated <var>CN</var>, <var>CNAME</var>, or <var>COMMONN</var>.
</td></tr>
</td></tr>
<tr><th>ORGANIZATIONALUNIT
<tr><th>ORGANIZATIONALUNIT
</th><td>The department or section of the organization to which the user belongs. For example, "Physics Department,"
</th><td>The department or section of the organization to which the user belongs. For example, "Physics Department," "Accounts receivable," or "Web doods." <var>ORGANIZATIONALUNIT</var> can be abbreviated <var>ORGU</var>, <var>ORGANIZATIONALU</var>, or <var>ORGUNIT</var>.
"Accounts receivable," or "Web doods." <var>ORGANIZATIONALUNIT</var> can be abbreviated <var>ORGU</var>,
<var>ORGANIZATIONALU</var>, or <var>ORGUNIT</var>.
</td></tr>
</td></tr>
<tr><th>ORGANIZATION
<tr><th>ORGANIZATION
</th><td>The company, government agency, school, or other organization to which the client belongs. For example, "Hard
</th><td>The company, government agency, school, or other organization to which the client belongs. For example, "Hard Knocks University," "Effete Recordings," or "bagsofconcrete.com". <var>ORGANIZATION</var> can be abbreviated <var>ORG</var>.
Knocks University," "Effete Recordings," or "bagsofconcrete.com". <var>ORGANIZATION</var> can be abbreviated
<var>ORG</var>.
</td></tr>
</td></tr>
<tr><th>LOCALITY
<tr><th>LOCALITY
</th><td>The city, town, or village in which the subject resides or works. <var>LOCALITY</var> can be abbreviated
</th><td>The city, town, or village in which the subject resides or works. <var>LOCALITY</var> can be abbreviated <var>LOC</var>.
<var>LOC</var>.
</td></tr>
</td></tr>
<tr><th>STATE
 
</th><td>The state, province, or other intermediate governmental unit in which the subject resides or works.
<tr><th>STATE</th>
<td>The state, province, or other intermediate governmental unit in which the subject resides or works.
<var>PROVINCE</var> is a synonym for <var>STATE</var>.
<var>PROVINCE</var> is a synonym for <var>STATE</var>.
</td></tr>
</td></tr>
<tr><th>COUNTRY
 
</th><td>The country or nation in which the subject resides or works.
<tr><th>COUNTRY</th>
<td>The country or nation in which the subject resides or works.
</td></tr>
</td></tr>
<tr><th>VALIDITYDATE
 
</th><td>The date on which the subject's or signer's certificate became valid. <var class="product">Janus Network
<tr><th>VALIDITYDATE</th>
<td>The date on which the subject's or signer's certificate became valid. <var class="product">Janus Network
Security</var> will not accept a client certificate where the subject's or signer's certificate is not yet valid, so
Security</var> 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.
use of this field is largely informational.
Line 66: Line 66:
<var>VALIDTIME</var>, or <var>VTIME</var>. </p>
<var>VALIDTIME</var>, or <var>VTIME</var>. </p>
</td></tr>
</td></tr>
<tr><th>EXPIRATIONDATE
<tr><th>EXPIRATIONDATE
</th><td>The date on which the subject's or signer's certificate becomes invalid. <var class="product">Janus Network
</th><td>The date on which the subject's or signer's certificate becomes invalid. <var class="product">Janus Network Security</var> 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.
Security</var> 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.
<p>
<p>
<var>EXPIRATIONDATE</var> can be abbreviated <var>EXPIRYDATE</var>, <var>EXPDATE</var>, or <var>EDATE</var>, or it can
<var>EXPIRATIONDATE</var> can be abbreviated <var>EXPIRYDATE</var>, <var>EXPDATE</var>, or <var>EDATE</var>, or it can
be requested as <var>EXPIRATIONTIME</var>, <var>EXPIRYTIME</var>, <var>EXPTIME</var>, or <var>ETIME</var>. </p>
be requested as <var>EXPIRATIONTIME</var>, <var>EXPIRYTIME</var>, <var>EXPTIME</var>, or <var>ETIME</var>. </p>
</td></tr>
</td></tr>
<tr><th>SERIALNUMBER
<tr><th>SERIALNUMBER
</th><td>The serial number of the subject's certificate as assigned by the signer. Certifying authorities should
</th><td>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.
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.
<p>
<p>
SERIALNUMBER is returned as a hexadecimal string with an even number of hexadecimal digits. Since the signer's
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.</p>
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.</p>
<p>
<p>
While <var>SERIALNUMBER</var> doesn't have any particular significance from an application level, it can be used as an
While <var>SERIALNUMBER</var> 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. <var>SERIALNUMBER</var> can be abbreviated <var>SERIALNUM</var>, <var>SERNUMBER</var>, <var>SERNUM</var>, <var>SERIAL</var> or <var>SER</var>. </p>
extra piece of identifying information for a client certificate. <var>SERIALNUMBER</var> can be abbreviated
<var>SERIALNUM</var>, <var>SERNUMBER</var>, <var>SERNUM</var>, <var>SERIAL</var> or <var>SER</var>. </p>
</td></tr>
</td></tr>
<tr><th>PRIVATEKEYLENGTH
 
</th><td>The length of the private key used by the signer or the client. Private key
<tr><th>PRIVATEKEYLENGTH</th>
lengths are usually expressed in terms of number of bits, so
<td>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 <var>PRIVATEKEYLENGTH</var> returns a decimal number string, such as <code>512</code> or <code>1024</code>.
<var>PRIVATEKEYLENGTH</var> returns a decimal number string, such as <code>512</code> or <code>1024</code>.
<p>
<p>
This value could be used to determine a "level of trustworthiness" of a client certificate, where a 512-bit
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. <var class="product">Janus Network Security</var> 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.</p>
certificate is considered somewhat weak (though probably strong enough for all but the most extreme security
requirements), and a 1024-bit certificate is considered strong. <var class="product">Janus Network Security</var> will
not accept certificates that indicate private keys shorter than 512 bits or longer than 2048 bits. Generally, client
certificates use either a 512-bit or a 1024-bit key.</p>
<p>
<p>
<var>PRIVATEKEYLENGTH</var> can be abbreviated <var>PRIVATEKEYL</var>, <var>PKEYLENGTH</var>, or <var>PKEYL</var>. <p>
<var>PRIVATEKEYLENGTH</var> can be abbreviated <var>PRIVATEKEYL</var>, <var>PKEYLENGTH</var>, or <var>PKEYL</var>. </p>
</td></tr>
</td></tr>
<tr><th>TEMPORARYKEYLENGTH
 
</th><td>The length of the temporary or "ephemeral" private key. Since SSL client certificate support does not cover
<tr><th>TEMPORARYKEYLENGTH</th>
ephemeral private keys, and in fact, such support would be largely meaningless anyway, <var>TEMPORARYKEYLENGTH</var>
<td>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, <var>TEMPORARYKEYLENGTH</var> always returns a 0. It is simply included here for compatibility with the equivalent <var class="product">Janus Sockets</var> function (<var>[[$Sock_Cert_Info]]</var>) or <var>Socket</var> object method (<var>[[CertInfo (Socket function)|CertInfo]]</var>).
always returns a 0. It is simply included here for compatibility with the equivalent <var class="product">Janus
Sockets</var> function (<var>[[$Sock_Cert_Info]]</var>) or <var>Socket</var> object method (<var>[[CertInfo (Socket
function)|CertInfo]]</var>).
<p>
<p>
<var>TEMPORARYKEYLENGTH</var> can be abbreviated <var>TEMPORARYKEYL</var>, <var>TEMPKEYLENGTH</var> or
<var>TEMPORARYKEYLENGTH</var> can be abbreviated <var>TEMPORARYKEYL</var>, <var>TEMPKEYLENGTH</var> or <var>TEMPKEYL</var>.  </p>
<var>TEMPKEYL</var>.  </p>
</td></tr>
</td></tr>
<tr><th>PERMANENTKEYLENGTH
 
</th><td>The length of the permanent private key. Since SSL client certificate support does not cover ephemeral
<tr><th>PERMANENTKEYLENGTH</th>
private keys, and in fact, such support would be largely meaningless anyway, <var>PERMANENTKEYLENGTH</var> always
<td>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, <var>PERMANENTKEYLENGTH</var> always returns a the same value as <var>PRIVATEKEYLENGTH</var>. It is simply included here for compatibility with the equivalent <var class="product">Janus Sockets</var> function (<var>[[$Sock_Cert_Info]]</var>) or <var>Socket</var> object method (<var>[[CertInfo (Socket function)|CertInfo]]</var>).
returns a the same value as <var>PRIVATEKEYLENGTH</var>. It is simply included here for compatibility with the
equivalent <var class="product">Janus Sockets</var> function (<var>[[$Sock_Cert_Info</var>) or <var>Socket</var>
object method (<var>[[CertInfo (Socket function)|CertInfo]]</var>).
<p>
<p>
<var>PERMANENTKEYLENGTH</var> can be abbreviated <var>PERMANENTKEYL</var>, <var>PERMKEYLENGTH</var>, or
<var>PERMANENTKEYLENGTH</var> can be abbreviated <var>PERMANENTKEYL</var>, <var>PERMKEYLENGTH</var>, or <var>PERMKEYL</var>. </p>
<var>PERMKEYL</var>. </p>
</td></tr>
</td></tr>
<tr><th>MD5HASH
 
</th><td>The MD5 hash or "digest" of the subject or issuer certificate. The MD5 hash of a certificate is shown by some
<tr><th>MD5HASH</th>
browsers when displaying certificate information. An MD5 hash is always a 16-byte value, so <var>MD5HASH</var> always
<td>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 <var>MD5HASH</var> always returns a 32-character hexadecimal string.
returns a 32-character hexadecimal string.
<p>
<p>
Since it is basically impossible for any two different certificates to have the same MD5 hash, the MD5HASH value can
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. </p>
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. </p>
<p>
<p>
<var>MD5HASH</var> can be abbreviated <var>MD5</var>. </p>
<var>MD5HASH</var> can be abbreviated <var>MD5</var>. </p>
</td></tr>
</td></tr>
<tr><th>SHAHASH
<tr><th>SHAHASH
</th><td>The SHA hash or "digest" of the subject or issuer certificate. The SHA hash of a certificate is shown by some
</th><td>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 <var>SHAHASH</var> always returns a 40-character hexadecimal string.
browsers when displaying certificate information. An SHA hash is always a 20-byte value, so <var>SHAHASH</var> always
returns a 40-character hexadecimal string.
<p>
<p>
Since it is basically impossible for any two different certificates to have the same SHA hash, the <var>SHAHASH</var>
Since it is basically impossible for any two different certificates to have the same SHA hash, the <var>SHAHASH</var>
Line 143: Line 118:
<p>
<p>
<var>SHAHASH</var> can be abbreviated <var>SHA</var>. </p>
<var>SHAHASH</var> can be abbreviated <var>SHA</var>. </p>
</td></tr></table>
</td></tr>
</table>


==Usage notes==
==Usage notes==
<ul>
<ul>
<li><var>CertInfo</var> returns the null string if the socket is not open
<li><var>CertInfo</var> returns the null string if the socket is not open
and <code>ONRESET CONTINUE</code> is in effect for the socket.
and <code>ONRESET CONTINUE</code> is in effect for the socket.</li>
 
<div id="reneg"></div>
<div id="reneg"></div>
<li>As of <var class="product">Sirius Mods</var> 7.7,
<li>If a Janus SSL server program issues the <var>CertInfo</var> or <var>CertLevels</var> method,
if a Janus SSL server program issues the <code>CertInfo or </code>CertLevels method,
the returned string will be null if
the returned string will be null if
the server port definition includes the <var>[[SSLCLCERT]]</var> or <var>[[SSLCLCERTR]]</var> parameter.
the server port definition includes the <var>[[SSLCLCERT and SSLCLCERTR|SSLCLCERT]]</var> or <var>[[SSLCLCERT and SSLCLCERTR|SSLCLCERTR]]</var> parameter.
Those <var>[[JANUS DEFINE]]</var> parameters cause a request for a client certificate in the
Those <var>[[JANUS DEFINE]]</var> parameters cause a request for a client certificate in the
initial server-client handshake that establishes the SSL connection.
initial server-client handshake that establishes the SSL connection.
Line 160: Line 136:
and a client certificate may only be requested once for an SSL session
and a client certificate may only be requested once for an SSL session
(whether or not the request successfully gets a certificate in return).
(whether or not the request successfully gets a certificate in return).
 
<p>
If neither of those <var>JANUS DEFINE</var> parameters is specified,
If neither of those <var>JANUS DEFINE</var> parameters is specified,
a server's <var>CertInfo</var> or <var>CertLevels</var> method call will cause an SSL
a server's <var>CertInfo</var> or <var>CertLevels</var> method call will cause an SSL
renegotiation (that is, a new handshake) that requests a digital certificate
renegotiation (that is, a new handshake) that requests a digital certificate from the client.
from the client.
This allows a port to require a client certificate for
This allows a port to require a client certificate for
some content, but not for other content.
some content, but not for other content. </p>
 
<p>
In the renegotiation, the server requests a certificate, but does '''not'''
In the renegotiation, the server requests a certificate, but does '''not''' insist that the client present one.
insist that the client present one.
The returned string from the method call may therefore still be null
The returned string from the method call may therefore still be null
because no certificate was provided.
because no certificate was provided. </p>
 
<p>
If another function or method causes a renegotiation by requesting
If another function or method causes a renegotiation by requesting
a client certificate, a subsequent <var>CertInfo</var> or <var>CertLevels</var> call
a client certificate, a subsequent <var>CertInfo</var> or <var>CertLevels</var> call
will '''not''' cause another request for a client certificate, whether or not a client certificate
will '''not''' cause another request for a client certificate, whether or not a client certificate was returned for the initial renegotiation.
was returned for the initial renegotiation.
This is because: </p>
This is because:
<ul>
<ul>
<li>There is no reason a client would not return a certificate on an initial
<li>There is no reason a client would not return a certificate on an initial
renegotiation, but return a certificate on a later renegotiation.
renegotiation, but return a certificate on a later renegotiation.</li>
 
<li>There is no reason a client would return a certificate on an initial
<li>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.
renegotiation, then return a different client certificate on a subsequent SSL renegotiation.</li>
</ul>
</ul></li>
</ul>
</ul>


==Example==
==Example==
The following statement returns the name of the organization at level 1
The following statement returns the name of the organization at level 1
of the certificate received from the remote partner using the
of the certificate received from the remote partner using the
Line 193: Line 166:
<p class="code">%org = %sok:Certinfo('ORGANIZATION', 1)
<p class="code">%org = %sok:Certinfo('ORGANIZATION', 1)
</p>
</p>
==See also==
<ul>
<li>The <var>[[ClientCertificate (XmlDoc function)|ClientCertificate]]</var> <var>XmlDoc</var> method and the <var>[[AppendCertificateRequestInfo (Stringlist function)|AppendCertificateRequestInfo]]</var> <var>Stringlist</var> method can both obtain and store certificate information similar to <var>CertInfo</var>. </li>
</ul>
{{Template:Socket:CertInfo footer}}

Latest revision as of 22:53, 29 August 2016

Retrieve a value from the SSL certificate (Socket class)


This method retrieves the value of an entity for one of the levels of the SSL certificate provided on a socket by the remote partner. The CertInfo function has an effect similar to its equivalent $function, $Sock_Cert_Info.

Syntax

%string = socket:CertInfo( string, [number])

Syntax terms

%string Return string, which contains the value of the requested entity at the requested level of the certificate supplied by the remote partner. If no such certificate was provided, the null string is returned.
socket A variable or an expression that is a reference to a socket object.
string The name of the requested entity, the options for which are listed below.
number The certificate level at which to obtain the entity. 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 argument is optional; the default value is 1. For more information about certificate levels, see the CertLevels function and see Janus Network Security.

Certificate entities

The following entities can be requested with CertInfo:

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 512 or 1024.

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.

Usage notes

  • CertInfo returns the null string if the socket is not open and ONRESET CONTINUE is in effect for the socket.
  • If a Janus SSL server program issues the CertInfo or CertLevels method, 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 CertInfo or CertLevels 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 is specified, a server's CertInfo or CertLevels 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 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 CertInfo or CertLevels 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 statement returns the name of the organization at level 1 of the certificate received from the remote partner using the %sok socket:

%org = %sok:Certinfo('ORGANIZATION', 1)

See also