Configuring SAFMQ X509 Authentication
Overview
SAFMQ utilizes OpenSSL to provide SSL services. OpenSSL provides SAFMQ two of the three legs of the digital security triad, authentication and confidentiality. Specifically, SAFMQ relies on OpenSSL's API to authenticate the validity of X509 certificates (authentication) and encrypt the data stream (confidentiality). The third leg authorization, is performed by SAFMQ using either password authentication/authorization, or passwordless X509 identity authorization.
Confidentiality/encryption occurs automatically, however, authentication must be configured. A standard OpenSSL installation includes a default OpenSSL configuration. The default configuration specifies a Certificate Authority repository, which lists all trusted X509 certificate Issuers. In most cases this default configuration will suffice. Some organizations find it useful to issue their own certificates, skipping the use of a third-party Certificate Authority issuer. In this case, administrators will need to either add the trusted certificate of the in-house authority to the default OpenSSL CA repository or create a custom repository for use with SAFMQ. Both options are typical, and your organization's best practices should be evaluated to determine which best fits your needs. SAFMQ may be configured to use a single file containing a list of trusted certificates, a directory of trusted certificates, or both.
SAFMQ's authorization occurs via X509 identity mapping. From SAFMQ's point of view, an X509 identity is the pair of Subject Distinguished Name and Issuer Distinguished Name found in an X509 certificate presented by a client to the SAFMQ server. SAFMQ contains a database of X509 identities associated with SAFMQ user names. If an X509 certificate is presented, and the identity from that certificate is mapped to a user, SAFMQ authorizes the connection using the user name's security context (user's permissions combined with permissions from each group the user is associated with). One thing to note: if a user name is sent in combination with an X509 digital certificate, it must match the mapping in the X509 identity database. Otherwise, a valid password must also be sent.
Certificate Authority File
SAFMQ can utilize OpenSSL's file based Certificate Authority. This feature lists multiple trusted certificates, in PEM format, in a single text file.
From OpenSSL's manual on CA locations (man SSL_CTX_load_verity_locations):
If CAfile is not NULL, it points to a file of CA certificates in PEM format. The file can contain several CA certificates identified by
-----BEGIN CERTIFICATE----- ... (CA certificate in base64 encoding) ... -----END CERTIFICATE-----sequences. Before, between, and after the certificates text is allowed which can be used e.g. for descriptions of the certificates.
The CAfile is processed on execution of the SSL_CTX_load_verify_locations() function.
This is to say that the Certificate Authority File is loaded only once upon SAFMQ's startup sequence. Any changes to this file will not be recognized until the SAFMQ server is restarted. Trusted certificates found in the CA File are cached for the lifetime of the SAFMQ server's process. Higher performance can be found by placing certificates in this file, but runtime configurability is sacrificed.
A Certificate Authority File may be specified by the "ssl_ca" property in the safmq.conf configuration file.
Certificate Authority Directory
SAFMQ can utilize OpenSSL's directory based Certificate Authority. Individual certificates reside in individual files. The files are read dynamically by the OpenSSL API when a certificate is presented. For performance reasons, the files are named by a hash of the certificate's Subject Distinguished Name. This allows OpenSSL to create a hash on the Issuer DN of the supplied certificate, and open the file containing the trusted certificate directly, instead of reading every certificate file in the directory.
From OpenSSL's manual on CA locations (man SSL_CTX_load_verity_locations):
If CApath is not NULL, it points to a directory containing CA certificates in PEM format. The files each contain one CA certificate. The files are looked up by the CA subject name hash value, which must hence be available. If more than one CA certificate with the same name hash value exist, the extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search is performed in the ordering of the extension number, regardless of other properties of the certificates. Use the c_rehash utility to create the necessary links.
The certificates in CApath are only looked up when required, e.g. when building the certificate chain or when actually performing the verification of a peer certificate.
When looking up CA certificates, the OpenSSL library will first search the certificates in CAfile, then those in CApath. Certificate matching is done based on the subject name, the key identifier (if present), and the serial number as taken from the certificate to be verified. If these data do not match, the next certificate will be tried. If a first certificate matching the parameters is found, the verification process will be performed; no other certificates for the same parameters will be searched in case of failure.
An example of how to generate a hash name:
$ openssl x509 -hash -noout -in sample_cert.pem e9907475To properly integrate with SAFMQ's use of OpenSSL, the sample_cert.pem should be copied to SAFMQ's CA Directory with the name "e9907475.0". The sample_cert.pem certificate contains the Subject DN: C=US, ST=Nebraska, L=Omaha, O=SAFMQ, CN=Matthew Battey/emailAddress=mattbattey@users.sourceforge.net
A Certificate Authority Directory may be specified by the "ssl_ca_dir" property in the safmq.conf configuration file.
Table of Contents Hierarchy of classes