JANUS ADDCA

<section begin="desc" />Add Certifying Authority to a port<section end="desc" />

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 User Language ADDCA utility, available as of Version 7.7 of the Sirius Mods, lets you add multiple certificates from the UL/SPF SIRIUS file, as described in JANUS ADDCA.

Syntax

<section begin="syntax" /> JANUS ADDCA portname filename procname <section end="syntax" />

JANUS ADDCA command syntax

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 DELCA (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 (JANUS DISPLAYCA). To view the number of received certificates signed by each trusted CA, use the JANUS STATUSCA command (JANUS STATCA or STATUSCA).

For more information about certificates and certifying authorities, see the Janus Network Security Reference Manual.

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, Sirius pre-loads a set of standard certifying authorities' certificates to the SIRIUS 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 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 User Language 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 via INCLUDE:

IN SIRIUS INCLUDE ADDCA portname certificate

User Language ADDCA utility syntax

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

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 WEBBY * CLSOCK 10 OPEN FILE SIRIUS IN SIRIUS INCLUDE ADDCA MYSSLPORT *America*

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

See: Janus command list