Web Services client authentication

The Web Services REST API can be accessed only via HTTPS. By default, all endpoints of the REST API require client authentication. The health endpoint can be configured to not require client authentication - see WSOP Health Endpoint for more information. Clients are identified and authorized via the client TLS certificate supplied with an HTTPS request.

Third-party solutions exist to aid creation and management of client TLS certificates. Alternatively, OpenSSL, which is shipped with most distributions, and also distributed as part of nShield Security World Software, is able to create and manage certificates.

Entrust strongly recommends that a specific root certificate and client certificate hierarchy are created specifically for WSOP.

Entrust strongly advises against using WSOP client authentication certificates in regular web browsers, since this may enable a Cross Site Request Forgery attack.

TLS certificates must contain Subject Alternative Name extension fields.

Client identification

Clients in WSOP are uniquely identified by the Subject and Issuer fields of the provided Web Services client TLS certificate. This means that two different TLS certificates that have identical values for Subject and Issuer would appear as the same client to the WSOP service.

To enforce client segregation, you must make sure that each distinct client certificate has a unique combination of Subject and Issuer. If this is not the case, a client that is not authorized to access keys in a protection domain will be able to access the keys, if they share the same identity as the authorizing client (as defined by the Subject and Issuer in their Web Services client TLS certificate).

Configure client authentication

Client authentication is configured by editing the external_tls section of the corecrypto configuration file located at /opt/nfast/webservices/corecrypto/conf/config.yaml.

Mutual authentication

It is necessary for your REST clients to have individual certificates with an established chain of trust to the client root certificate to be able to authenticate with Web Services Option Pack.

To configure this chain of trust, set ca_certificate_file to the path of the certificate file for the Certificate Authority that issues the Web Services client certificates. For example, after installation this is set to:

ca_certificate_file: /opt/nfast/webservices/corecrypto/tls/external/corecrypto-external-ca-cert.pem

Enable and disable client authentication

Client authentication is enabled by default.

It is possible to disable client authentication (for example, for initial commissioning or testing purposes), and permit any client to perform operations using your Security World keys. This is achieved by changing the configuration file and restarting the Web Services Option Pack server.

Disabling client authentication permits the use of your Security World keys by any REST client that is able to access the machine that is hosting your Web Services Option Pack installation. While the key material is protected by the HSM, the use of the keys is not.

Client authentication should not be disabled in a production environment.

To disable client authentication, set client_auth_enabled: false

To enable client authentication, set client_auth_enabled: true

Client certificate revocation

Configure the CRL directory

To enable the revocation of client certificates you must configure a directory to store the revocations.

This is done by editing the value of crl_directory in the external_tls section of the configuration file /opt/nfast/webservices/corecrypto/conf/config.yaml.

For example:

crl_directory: /opt/nfast/webservices/corecrypto/tls/external/crls

If the crl_directory is not configured in the config file, then no revocation checking will happen.

Note that corecrypto consults its config.yaml only on start-up. Therefore, for any updates to the configuration file to take effect, the WSOP server must be restarted.

CRLs for WSOP client certificates

A CRL file in the CRL directory will be loaded only if it has extension .crl or .pem, and it must be PEM-encoded. It must be signed by the private key of the root certificate for the revoked client TLS certificates. Thus corecrypto consults the same root certificate to check the validity of client TLS certificates and of a CRL revoking those client certificates. If the directory contains multiple CRL files, a client certificate is treated as revoked if it is listed in one or more valid CRL files. You do not need to restart the service after changing or adding to the contents of the CRL directory. The software will automatically use the new set of files.

General notes on CRLs

A Certificate Revocation List (CLR) file is signed by a trusted CRL issuer, typically the CA for the revoked certificates. The file either lists identifiers of the revoked certificates, or denotes that none have been revoked. The file also holds other data, such as the time the CRL was updated.

Tools such as OpenSSL may be used to maintain this list and create CRLs.

The specification for CRLs is in RFC-5280: https://tools.ietf.org/html/rfc5280#section-5.