Verifying a client certificate - Revision history

JAL: add M204PROC info

2017-06-08T19:28:53Z

add M204PROC info

← Older revision		Revision as of 19:28, 8 June 2017
Line 84:		Line 84:
	Servers under <var class="product">SirMods</var> version 7.7 or higher may also take		Servers under <var class="product">SirMods</var> version 7.7 or higher may also take
	advantage of the <var class="product">SOUL</var> ADDCA utility to add one or more of the standard		advantage of the <var class="product">SOUL</var> ADDCA utility to add one or more of the standard
	CA root certificates that are pre-loaded to the <code>SIRIUS</code> ~~procedure~~ file.		CA root certificates that are pre-loaded to the <var class="product">RKTools</var> <code>SIRIUS</code> (prior to version 7.7) or <code>M204PROC</code> file (as of RKTools 7.7).

	==<b id="cfgcli"></b>Configure the server to request a certificate from the client==		==<b id="cfgcli"></b>Configure the server to request a certificate from the client==
Line 131:		Line 131:
	<ul>		<ul>
	<li>At least one certificate from a certifying authority must be in place on the server.		<li>At least one certificate from a certifying authority must be in place on the server.
	This is accomplished by the ADDCA rules. </li>		This is accomplished by the <var>JANUS ADDCA</var> rules. </li>

	<li>The <var>START</var> command must be followed by the password for the server's private key (discussed earlier		<li>The <var>START</var> command must be followed by the password for the server's private key (discussed earlier

JAL: typo

2016-10-25T23:09:00Z

typo

← Older revision		Revision as of 23:09, 25 October 2016
Line 60:		Line 60:
	</p>		</p>

	For a browser client,		For a browser client, how you install the client certificate you get from a CA, and where you store the private key you generated, is browser-specific.
	how you install the client certificate you get from a CA, and where you
	store the private key you generated, is browser-specific.
	This document leaves those details to the user.		This document leaves those details to the user.
	If the client to be authenticated is a Janus <var>CLSOCK</var> client, the details of		If the client to be authenticated is a Janus <var>CLSOCK</var> client, the details of certificate acquisition parallel
	certificate acquisition parallel		those for a Janus server, as described in the [[Installing and configuring Janus Network Security]] and [[Implementing a server certificate]] pages.
	those for a Janus server, as described in [[Installing and configuring Janus Network Security]]
	[[Implementing a server certificate]] pages.

	==<b id="getserv"></b>Obtain and load root certificates for the server==		==<b id="getserv"></b>Obtain and load root certificates for the server==

JAL: remove comment

2016-10-25T22:38:51Z

remove comment

← Older revision		Revision as of 22:38, 25 October 2016
Line 1:		Line 1:
	~~<!--Page automatically generated by CMSTOWIK EXEC and will be~~		<var class="product">Janus Network Security</var> also supports client certificate verification, which lets you restrict server port access to only those clients that
	automatically replaced -- any manual edits will be lost.		present an appropriate client certificate during an initial or a renegotiated SSL "handshake."
	~~You've been warned. .. (Page built by JAL at the SIRIUS VM; file: FUNPGNEW SYSUT2) -->~~
	~~<!-- Page name: Verifying a client certificate-->~~
	<var class="product">Janus Network Security</var> also supports client certificate verification, which lets
	you restrict server port access to only those clients that
	present an appropriate client certificate during an
	initial or a renegotiated SSL "handshake."
	The client's certificate and public identity must be valid and must have been		The client's certificate and public identity must be valid and must have been
	issued by a Certificate Authority (CA) whose root certificate has been		issued by a Certificate Authority (CA) whose root certificate has been
	explicitly added to the server's list of trusted CAs.		explicitly added to the server's list of trusted CAs.

	This page describes steps that supplement the		This page describes steps that supplement the steps described in [[Implementing a server certificate]] for setting up a Janus SSL server.
	steps described in [[Implementing a server certificate]]
	for setting up a Janus SSL server.

	To add client certificate verification to a Janus SSL server:		To add client certificate verification to a Janus SSL server:

Admin: 1 revision: Janus Network Security pages

2016-05-31T21:47:21Z

1 revision: Janus Network Security pages

← Older revision	Revision as of 21:47, 31 May 2016
(No difference)

JAL at 20:45, 31 May 2016

2016-05-31T20:45:28Z

New page

<var class="product">Janus Network Security</var> also supports client certificate verification, which lets
you restrict server port access to only those clients that
present an appropriate client certificate during an
initial or a renegotiated SSL "handshake."
The client's certificate and public identity must be valid and must have been
issued by a Certificate Authority (CA) whose root certificate has been
explicitly added to the server's list of trusted CAs.

This page describes steps that supplement the
steps described in [[Implementing a server certificate]]
for setting up a Janus SSL server.

To add client certificate verification to a Janus SSL server:
<ol>
<li>Require (or arrange for) clients to obtain and install a CA-signed client certificate. </li>

<li>Obtain root certificates for the server from CAs that provide the client certificates. </li>

<li>Configure the Janus SSL server to request or require the client certificate. </li>

<li>Add a CA root certificate to the Janus Server port. </li>

<li>Optionally, specify an error handler to launch when a required client
certificate is not presented. </li>
</ol>
This page describes these steps in greater detail.


For information about methods and $functions that retrieve the information
contained in a client certificate received by a Janus port, see the following:
<ul>
<li><var>[[ClientCertificate (System function)|ClientCertificate]]</var> and related methods </li>

<li>The <var>[[$Web_Cert_Info]]</var> and <var>[[$Web_Cert_Levels]]</var> functions </li>

<li>The Socket class methods <var>[[CertInfo (Socket function)|CertInfo]]</var> and
<var>[[CertLevels (Socket function)|CertLevels]]</var> and their $function counterparts
<var>[[$Sock_Cert_Info]]</var> and <var>[[$Sock_Cert_Levels]]</var> </li>
</ul>

==Obtain and install the client certificate==
Client browsers come with a set of pre-installed root certificates from multiple
certifying authorities which they use to authenticate server certificates.
The pre-installed certificates do not establish the browser user's
identity, however, if a server requests client verification.
For client verification purposes, browser clients must apply for, obtain,
and install a CA-signed certificate that ties the identity of the browser user
(the subject of the certificate) to the particular public key in the certificate.

Client certificates are created much like SSL server certificates.
You begin by requesting a certificate from a CA.
You can use the CA's web site to generate a certificate request, or
you can generate a certificate request using a tool like the Janus SSL CMA,
which is described in [[Implementing a server certificate#newcert|Using the Certificate Management Application]].

The certificate request contains the private key that does both of these:
<ul>
<li>Determines the public key embedded in the certificate that the CA ultimately returns </li>

<li>Participates in the CA's digital signature of the returned certificate </li>
</ul>
Note: <var class="product">Janus Network Security</var> servers that request client verification
accept only incoming certificates that are signed by a trusted CA.


For a browser client,
how you install the client certificate you get from a CA, and where you
store the private key you generated, is browser-specific.
This document leaves those details to the user.
If the client to be authenticated is a Janus <var>CLSOCK</var> client, the details of
certificate acquisition parallel
those for a Janus server, as described in [[Installing and configuring Janus Network Security]]
[[Implementing a server certificate]] pages.

==Obtain and load root certificates for the server==
The client to be authenticated
must present to the server a certificate that is signed by
a certifying authority whose certificate is recognized by the server port.
The server recognizes only those CAs whose root certificates it has already
obtained, stored locally,
and added to the port using the <var>[[JANUS ADDCA]]</var> command.
This command must reference the CA's certificate,
which is typically loaded into a <var class="product">Model 204</var> procedure inside the region (see
the code in [[#xmpcli|Example: SSL port requires client certificate]]).

One way to get a CA root certificate for the server might be to
locate the certificate in your browser's store, then export it, and
upload it to your Online.

Depending on your application, you may need to add certificates from multiple CAs.

Servers under <var class="product">SirMods</var> version 7.7 or higher may also take
advantage of the <var class="product">SOUL</var> ADDCA utility to add one or more of the standard
CA root certificates that are pre-loaded to the <code>SIRIUS</code> procedure file.

==Configure the server to request a certificate from the client==
Your application must indicate to the client that it wants to
examine the client's certificate.
You can do so in either or both of the following ways:
<ul>
<li>You can configure the Janus port to request or require the client certificate. </li>

<li>You can request a client certificate (after the SSL connection is established)
by calling one of the methods or functions that query such a certificate for information.
These methods and functions are listed in [[#certmet|this page's introduction]]. </li>
</ul>

The certificate request occurs during a connection handshake
or during a handshake renegotiation, and the request is made only once.
If you use both the port definition and the method/function calls,
the port definition makes the request.

If you decide to use the port definition to request a certificate,
specify either of the following <var>JANUS DEFINE</var> command parameters:
<ul>
<li>The <var>[[SSLCLCERT and SSLCLCERTR (JANUS DEFINE parameters)|SSLCLCERT]]</var> parameter
causes the port to request a certificate from the client, but processing continues if
no certificate is presented. </li>

<li>The <var>[[SSLCLCERT and SSLCLCERTR (JANUS DEFINE parameters)|SSLCLCERTR]]</var> parameter
requires a client certificate, and processing terminates if no certificate is provided. </li>
</ul>
Note: If <var>SSLCLCERTR</var> is specified on the port definition, you can also specify
an exception handler routine that will perform error processing if no
client certificate is presented.
You call the handler by creating an <var>SSLNOCERTERR</var>
rule on a <var>JANUS WEB ON</var>, <var>JANUS WEB TYPE</var>, or <var>JANUS WEB REDIRECT</var> command (see [[#xmpcli|Example: SSLport requires client certificate]]).


==Example: SSL port requires client certificate==
The following code defines an SSL server port that requires its clients to
present a certificate.
An exception handler is called if no client certificate is presented.

The <var>SSLCLCERTR</var> parameter of <var>JANUS DEFINE</var> causes the port to require the client certificate.
The exception handler is invoked via the <var>ON</var> rule with the <var>SSLNOCERTERR</var>.

This port definition also requires the following:
<ul>
<li>At least one certificate from a certifying authority must be in place on the server.
This is accomplished by the ADDCA rules. </li>

<li>The <var>START</var> command must be followed by the password for the server's private key (discussed earlier
in [[Implementing a server certificate#encpkey|Encrypting the private key]]). </li>
</ul>
<nowiki>JANUS DRAIN CLCERTWEB
JANUS DELETE CLCERTWEB

* Port using SSL security with the session cookie (web port)

JANUS DEFINE CLCERTWEB 9733 WEBSERV 10 TRACE 1 UPCASE -
OBSIZE 10240 RBSIZE 10240 IBSIZE 4096 HTTPVERSION 1.1 -
SSL JANSSL TM2008.PKEY SSLCACHE 100 SSLBSIZE 32767 -
OPEN FILE MYPROC MAXTEMP 9000 TIMEOUT 180 -
NOAUDTERM COMPRESS 0 KEEPALIVE 60 SSLCLCERTR

* Certifying Authority certificates to authenticate clients

JANUS ADDCA CLCERTWEB MYPROC SECURESE.CERT
JANUS ADDCA CLCERTWEB MYPROC THAWTE.CERT
JANUS ADDCA CLCERTWEB MYPROC VERIJUNK.CERT

JANUS WEB CLCERTWEB DISALLOW *
JANUS WEB CLCERTWEB ALLOW * USER *

JANUS WEB CLCERTWEB ON SSLNOCERTERR OPEN FILE MYPROC -
CMD 'INCLUDE MISSING_CERTIFICATE_ERROR'

JANUS START CLCERTWEB </nowiki>
sslpwdrequiredbyport


==See also==
{{Template:Janus Network Security topic list}}

[[Category: Janus Network Security]]