JANUS ADDCA: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
m (link repair)
 
(10 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:JANUS ADDCA}}
{{DISPLAYTITLE:JANUS ADDCA}}
<span class="pageSubtitle"><section begin="desc" />Add Certifying Authority to a port<section end="desc" /></span>
<span class="pageSubtitle">Add Certifying Authority to a port</span>


For ports supporting encrypted communications, this command adds a "trusted" certifying authority's certificate (encrypted public key) to the port.  
For ports supporting encrypted communications, this command adds a "trusted" certifying authority's certificate (encrypted public key) to the port.  
Line 6: Line 6:
"Added" certificates are used for authentication (decryption) of incoming certificates, that is, to verify that a certificate presented to the port bears the authentic signature of the certifying authority. Such an incoming certificate may be a server certificate sent in reply to a <var>CLSOCK</var> port, or it may be a client certificate sent in reply to a <var>SRVSOCK</var>, <var>WEBSERV</var>, <var>SDS</var> or <var>OPENSERV</var> port.  
"Added" certificates are used for authentication (decryption) of incoming certificates, that is, to verify that a certificate presented to the port bears the authentic signature of the certifying authority. Such an incoming certificate may be a server certificate sent in reply to a <var>CLSOCK</var> port, or it may be a client certificate sent in reply to a <var>SRVSOCK</var>, <var>WEBSERV</var>, <var>SDS</var> or <var>OPENSERV</var> port.  


''[[Janus Network Security]]'' accepts only incoming certificates that are "signed" by a trusted certifying authority (often abbreviated as CA). Applications can place further restrictions on acceptable certificates but cannot relax this restriction.  
<var class="product">[[Janus Network Security]] accepts only incoming certificates that are "signed" by a trusted certifying authority (often abbreviated as CA). Applications can place further restrictions on acceptable certificates but cannot relax this restriction.  


The <var class="product">User Language</var> <code>ADDCA</code> utility, available as of Version 7.7 of the ''[[Sirius Mods]]'', lets you add multiple certificates from the ''[[UL/SPF]]'' <code>SIRIUS</code> file, as described in [[JANUS ADDCA#Adding SIRIUS-file certificates|"Adding SIRIUS-file certificates"]].
The <var class="product">SOUL</var> <var>ADDCA</var> utility lets you add multiple certificates from the [[RKTools]] <code>SIRIUS</code> file, as described in [[JANUS ADDCA#Adding SIRIUS-file certificates|Adding SIRIUS-file certificates]].


==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" /> JANUS ADDCA portname filename procname
<p class="syntax">JANUS ADDCA <span class="term">portname filename procname</span>
<section end="syntax" /></p>
</p>
 


Where each parameter is positional and required:
Where each parameter is positional and required:


<table class="syntaxTable">
<table>
<tr><th>portname</th>
<tr><th>portname</th>
<td>The defined Janus port to which the certificate is to be added. Can include wildcards. Non-SSL ports will not have trusted CA certificates added to them, since it is meaningless to have trusted CAs on a non-SSL port.</td></tr>
<td>The defined Janus port to which the certificate is to be added. Can include wildcards. Non-SSL ports will not have trusted CA certificates added to them, since it is meaningless to have trusted CAs on a non-SSL port.</td></tr>
<tr><th>filename</th>
<tr><th>filename</th>
<td>The name of the file that contains the CA certificate.</td></tr>
<td>The name of the file that contains the CA certificate.</td></tr>
<tr><th>procname</th>
<tr><th>procname</th>
<td>The name of the procedure that contains the base64 encoded CA certificate. This certificate may have been generated by the ''[[Janus Network Security]]'' certificate management application or by some other certificate management application, extracted from a browser's CA database, or downloaded from a certifying authority's web site.
<td>The name of the procedure that contains the base64 encoded CA certificate. This certificate may have been generated by the <var class="product">Janus Network Security</var> certificate management application or by some other certificate management application, extracted from a browser's CA database, or downloaded from a certifying authority's web site.
</td></tr></table>
</td></tr></table>


An example ADDCA command and system response follows:
An example <var>ADDCA</var> command and system response follows:


<p class="code"> JANUS ADDCA J2WEBS JANSSL MYSSL2.CERT
<p class="code">JANUS ADDCA J2WEBS JANSSL MYSSL2.CERT
   
   
  *** MSIR.0642: Added CA 'www.sirius-software.com' from file
  *** MSIR.0642: Added CA 'www.sirius-software.com' from file
Line 64: Line 65:


To view the list of trusted certificates and their contents, use the <var>[[JANUS DISPLAYCA]]</var> command. To view the number of received certificates signed by each trusted CA, use the <var>[[JANUS STATUSCA]]</var> command.  
To view the list of trusted certificates and their contents, use the <var>[[JANUS DISPLAYCA]]</var> command. To view the number of received certificates signed by each trusted CA, use the <var>[[JANUS STATUSCA]]</var> command.  
For more information about certificates and certifying authorities, see the [http://sirius-software.com/maint/download/jansslr.pdf Janus Network Security Reference Manual].


==Adding SIRIUS-file certificates==
==Adding SIRIUS-file certificates==
 
Although a server port is not likely to need to use the <var>JANUS ADDCA</var> command more than once, a client port may want to use it to add multiple certificates. As a convenience especially for a <var>CLSOCK</var> port connecting to an SSL server, Rocket pre-loads a set of standard certifying authorities' certificates to the <code>SIRIUS</code> procedure file. [[Janus Sockets]] SSL client ports need to add the certificate(s) of the CA that signed the certificate of the server or servers to which the client will connect. (Janus does not allow a port to specify exceptions, that is, signed certificates that a port accepts without having the signing CA's certificate.)  
Although a server port is not likely to need to use the <var>JANUS ADDCA</var> command more than once, a client port may want to use it to add multiple certificates. As a convenience especially for a <var>CLSOCK</var> port connecting to an SSL server, Sirius pre-loads a set of standard certifying authorities' certificates to the <code>SIRIUS</code> procedure file (as of ''[[UL/SPF]]'' 7.3). ''[[Janus Sockets]]'' SSL client ports need to add the certificate(s) of the CA that signed the certificate of the server or servers to which the client will connect. (Janus does not allow a port to specify exceptions, that is, signed certificates that a port accepts without having the signing CA's certificate.)  


The <code>SIRIUS</code> file certificates can be added to a port by the <var>JANUS ADDCA</var> command or by the <code>ADDCA</code> utility, described below. Adding this set of certificates equips the client port in much the same way that internet browsers are equipped with multiple CA certificates.  
The <code>SIRIUS</code> file certificates can be added to a port by the <var>JANUS ADDCA</var> command or by the <code>ADDCA</code> utility, described below. Adding this set of certificates equips the client port in much the same way that internet browsers are equipped with multiple CA certificates.  


The certificates are procedures whose names have the prefix <code>CA_</code> so they are easy to scan using a <var>DISPLAY PROCEDURE</var> command or by browsing the procedures in ''[[SirPro]]''. Sirius will periodically review the certificates loaded to <code>SIRIUS</code>, eliminate any that have expired, and load new ones when they are made available by various well-accepted CAs.  
The certificates are procedures whose names have the prefix <code>CA_</code> so they are easy to scan using a <var>DISPLAY PROCEDURE</var> command or by browsing the procedures in [[SirPro]]. Sirius will periodically review the certificates loaded to <code>SIRIUS</code>, eliminate any that have expired, and load new ones when they are made available by various well-accepted CAs.  


The <var class="product">User Language</var> <code>ADDCA</code> utility lets you add some or all of these certificates at once to an SSL port. The utility is invoked at the command level via <code>INCLUDE</code>:  
The <var class="product">SOUL</var> <var>ADDCA</var> utility lets you add some or all of these certificates at once to an SSL port. The utility is invoked at the command level with <code>INCLUDE</code>:  


<p class="code">  
<p class="syntax">IN SIRIUS INCLUDE ADDCA <span class="term">portname certificate</span>
IN SIRIUS INCLUDE ADDCA portname certificate
</p>
<p class="caption">User Language ADDCA utility syntax
</p>
</p>


Where each parameter is positional and required:
Where each parameter is positional and required:


<table class="syntaxTable">
<table>
<tr><th>portname</th>
<tr><th>portname</th>
<td>The defined Janus SSL port to which the certificate is to be added. The name can include wildcards. Non-SSL ports may '''not''' have trusted CA certificates added to them.</td></tr>
<td>The defined Janus SSL port to which the certificate is to be added. The name can include wildcards. Non-SSL ports may '''not''' have trusted CA certificates added to them.</td></tr>
<tr><th>certificate</th>
<tr><th>certificate</th>
<td>The name of the procedure that contains the base64 encoded CA certificate. This parameter may contain wildcards. To load all certificates in the <code>SIRIUS</code> file whose names begin with <code>CA_AOL</code>, you can use: <code>CA_AOL*</code>
<td>The name of the procedure that contains the base64 encoded CA certificate. This parameter may contain wildcards. To load all certificates in the <code>SIRIUS</code> file whose names begin with <code>CA_AOL</code>, you can use: <code>CA_AOL*</code>
Line 97: Line 93:


The utility internally runs a series of <var>ADDCA</var> commands like the following to load to <code>WEBBY</code> each certificate in file <code>SIRIUS</code> that matches the specified pattern:
The utility internally runs a series of <var>ADDCA</var> commands like the following to load to <code>WEBBY</code> each certificate in file <code>SIRIUS</code> that matches the specified pattern:
<p class="code"> JANUS ADDCA WEBBY SIRIUS CA_ThawtePremiumServerCA
<p class="code">JANUS ADDCA WEBBY SIRIUS CA_ThawtePremiumServerCA
JANUS ADDCA WEBBY SIRIUS CA_ThawteServerCA
JANUS ADDCA WEBBY SIRIUS CA_ThawteServerCA
JANUS ADDCA WEBBY SIRIUS CA_ThawteTimestampingCA
JANUS ADDCA WEBBY SIRIUS CA_ThawteTimestampingCA
JANUS ADDCA WEBBY SIRIUS CA_ThawteSGCCA
JANUS ADDCA WEBBY SIRIUS CA_ThawteSGCCA
</p>
</p>
<blockquote> The CA certificates are stored as procedures with mixed-case names, which makes them much easier to scan visually, but a little more difficult to manipulate.  
<p class="note">'''Note:''' The CA certificates are stored as procedures with mixed-case names, which makes them much easier to scan visually, but a little more difficult to manipulate. </p>


For instance, if the above <code>INCLUDE</code> command is used, all the intended certificates are loaded, because the <code>CA_T</code> in uppercase matches the case of the corresponding characters in the certificate names. But if you want a more precise search and the name to be matched by the pattern includes mixed-case characters, the <code>INCLUDE</code> command must be bracketed with a set of <code>*LOWER/*UPPER</code> commands, as in:
For instance, if the above <var>INCLUDE</var> command is used, all the intended certificates are loaded, because the <code>CA_T</code> in uppercase matches the case of the corresponding characters in the certificate names. But if you want a more precise search and the name to be matched by the pattern includes mixed-case characters, the <var>INCLUDE</var> command must be bracketed with a set of <var>*LOWER</var>/<var>*UPPER</var> commands, as in:


<p class="code"> JANUS DEFINE MYSSLPORT * CLSOCK 10
<p class="code">JANUS DEFINE MYSSLPORT * CLSOCK 10
OPEN FILE SIRIUS
OPEN FILE SIRIUS
*LOWER
&#42;LOWER
IN SIRIUS INCLUDE ADDCA MYSSLPORT *America*
IN SIRIUS INCLUDE ADDCA MYSSLPORT *America*
*UPPER
&#42;UPPER
</p>
</p>


The above sequence of commands would load the certificate named <code>CA_AmericaOnlineRootCertificationAuthority1</code> from file <code>SIRIUS</code>.</blockquote>
The above sequence of commands would load the certificate named <code>CA_AmericaOnlineRootCertificationAuthority1</code> from file <code>SIRIUS</code>.
 
==See also==
<ul>
<li>[[List of Janus commands]]
</ul>


See: [[List_of_Janus_commands|Janus command list]]
[[Category:Janus commands|JANUS ADDCA]]
[[Category:Janus commands|JANUS ADDCA]]

Latest revision as of 19:22, 30 August 2016

Add Certifying Authority to a port

For ports supporting encrypted communications, this command adds a "trusted" certifying authority's certificate (encrypted public key) to the port.

"Added" certificates are used for authentication (decryption) of incoming certificates, that is, to verify that a certificate presented to the port bears the authentic signature of the certifying authority. Such an incoming certificate may be a server certificate sent in reply to a CLSOCK port, or it may be a client certificate sent in reply to a SRVSOCK, WEBSERV, SDS or OPENSERV port.

Janus Network Security accepts only incoming certificates that are "signed" by a trusted certifying authority (often abbreviated as CA). Applications can place further restrictions on acceptable certificates but cannot relax this restriction.

The SOUL ADDCA utility lets you add multiple certificates from the RKTools SIRIUS file, as described in Adding SIRIUS-file certificates.

Syntax

JANUS ADDCA portname filename procname

Where each parameter is positional and required:

portname The defined Janus port to which the certificate is to be added. Can include wildcards. Non-SSL ports will not have trusted CA certificates added to them, since it is meaningless to have trusted CAs on a non-SSL port.
filename The name of the file that contains the CA certificate.
procname The name of the procedure that contains the base64 encoded CA certificate. This certificate may have been generated by the Janus Network Security certificate management application or by some other certificate management application, extracted from a browser's CA database, or downloaded from a certifying authority's web site.

An example ADDCA command and system response follows:

JANUS ADDCA J2WEBS JANSSL MYSSL2.CERT *** MSIR.0642: Added CA 'www.sirius-software.com' from file JANSSL, proc MYSSL2.CERT to port J2WEBS


A typical CA certificate would look something like:

-----BEGIN CERTIFICATE----- MIIDLjCCApegAwIBAgIRANJ2Lo0UDD19sqglXa/uDXUwDQYJKoZIhvcNAQECBQAw XzELMAkGA1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMTcwNQYDVQQL Ey5DbGFzcyAxIFB1YmxpYyBQcmltYXJ5IENlcnRpZmljYXRpb24gQXV0aG9yaXR5 MB4XDTk4MDUxMjAwMDAwMFoXDTA4MDUxMjIzNTk1OVowgcwxFzAVBgNVBAoTDlZl cmlTaWduLCBJbmMuMR8wHQYDVQQLExZWZXJpU2lnbiBUcnVzdCBOZXR3b3JrMUYw RAYDVQQLEz13d3cudmVyaXNpZ24uY29tL3JlcG9zaXRvcnkvUlBBIEluY29ycC4g QnkgUmVmLixMSUFCLkxURChjKTk4MUgwRgYDVQQDEz9WZXJpU2lnbiBDbGFzcyAx IENBIEluZGl2aWR1YWwgU3Vic2NyaWJlci1QZXJzb25hIE5vdCBWYWxpZGF0ZWQw gZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBALtaRIoEFrtV/QN6ii2UTxV4NrgN SrJvnFS/vOh3Kp258Gi7ldkxQXB6gUu5SBNWLccI4YRCq8CikqtEXKpC8IIOAukv +8I7u77JJwpdtrA2QjO1blSIT4dKvxna+RXoD4e2HOPMxpqOf2okkuP84GW6p7F+ 78nbN2rISsgJBuSZAgMBAAGjfDB6MBEGCWCGSAGG+EIBAQQEAwIBBjBHBgNVHSAE QDA+MDwGC2CGSAGG+EUBBwEBMC0wKwYIKwYBBQUHAgEWH3d3dy52ZXJpc2lnbi5j b20vcmVwb3NpdG9yeS9SUEEwDwYDVR0TBAgwBgEB/wIBADALBgNVHQ8EBAMCAQYw DQYJKoZIhvcNAQECBQADgYEAiLg3O93alDcAraqf4YEBcR6Sam0v9vGd08pkONwb mAwHhluFFWoPuUmFpJXxF31ntH8tLN2aQp7DPrSOquULBt7yVir6M8e+GddTTMO9 yOMXtaRJQmPswqYXD11YGkk8kFxVo2UgAP0YIOVfgqaxqJLFWGrBjQM868PNBaKQ rm4= -----END CERTIFICATE-----


The procedure and file containing the certificate are only enqueued during JANUS ADDCA processing. Thereafter, the certificate is stored in virtual storage, and the procedure is available to be modified or freed from the Online.

JANUS ADDCA will not add a trusted CA certificate to a port if there is already a trusted CA certificate from the same file name and procedure name added to the port. If a CA certificate in a procedure has been changed, the certificate must be deleted from the port using JANUS DELCA and then added again using ADDCA for the change to affect the port.

To view the list of trusted certificates and their contents, use the JANUS DISPLAYCA command. To view the number of received certificates signed by each trusted CA, use the JANUS STATUSCA command.

Adding SIRIUS-file certificates

Although a server port is not likely to need to use the JANUS ADDCA command more than once, a client port may want to use it to add multiple certificates. As a convenience especially for a CLSOCK port connecting to an SSL server, Rocket pre-loads a set of standard certifying authorities' certificates to the SIRIUS procedure file. Janus Sockets SSL client ports need to add the certificate(s) of the CA that signed the certificate of the server or servers to which the client will connect. (Janus does not allow a port to specify exceptions, that is, signed certificates that a port accepts without having the signing CA's certificate.)

The SIRIUS file certificates can be added to a port by the JANUS ADDCA command or by the ADDCA utility, described below. Adding this set of certificates equips the client port in much the same way that internet browsers are equipped with multiple CA certificates.

The certificates are procedures whose names have the prefix CA_ so they are easy to scan using a DISPLAY PROCEDURE command or by browsing the procedures in SirPro. Sirius will periodically review the certificates loaded to SIRIUS, eliminate any that have expired, and load new ones when they are made available by various well-accepted CAs.

The SOUL ADDCA utility lets you add some or all of these certificates at once to an SSL port. The utility is invoked at the command level with INCLUDE:

IN SIRIUS INCLUDE ADDCA portname certificate

Where each parameter is positional and required:

portname The defined Janus SSL port to which the certificate is to be added. The name can include wildcards. Non-SSL ports may not have trusted CA certificates added to them.
certificate The name of the procedure that contains the base64 encoded CA certificate. This parameter may contain wildcards. To load all certificates in the SIRIUS file whose names begin with CA_AOL, you can use: CA_AOL*

This ADDCA utility invocation loads (at least) the CA_ThawtePremiumServerCA certificate, for example:

IN FILE SIRIUS INCLUDE ADDCA WEBBY CA_T*

The utility internally runs a series of ADDCA commands like the following to load to WEBBY each certificate in file SIRIUS that matches the specified pattern:

JANUS ADDCA WEBBY SIRIUS CA_ThawtePremiumServerCA JANUS ADDCA WEBBY SIRIUS CA_ThawteServerCA JANUS ADDCA WEBBY SIRIUS CA_ThawteTimestampingCA JANUS ADDCA WEBBY SIRIUS CA_ThawteSGCCA

Note: The CA certificates are stored as procedures with mixed-case names, which makes them much easier to scan visually, but a little more difficult to manipulate.

For instance, if the above INCLUDE command is used, all the intended certificates are loaded, because the CA_T in uppercase matches the case of the corresponding characters in the certificate names. But if you want a more precise search and the name to be matched by the pattern includes mixed-case characters, the INCLUDE command must be bracketed with a set of *LOWER/*UPPER commands, as in:

JANUS DEFINE MYSSLPORT * CLSOCK 10 OPEN FILE SIRIUS *LOWER IN SIRIUS INCLUDE ADDCA MYSSLPORT *America* *UPPER

The above sequence of commands would load the certificate named CA_AmericaOnlineRootCertificationAuthority1 from file SIRIUS.

See also