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.

If the WSOP server is not configured to operate behind an API Gateway, clients are identified and authorized via the client TLS certificate supplied with an HTTPS request.

If the WSOP server is configured to operate behind an API Gateway, clients can be identified and authorized via the client TLS certificate or the JSON Web Token (JWT) supplied with an HTTPS request. In both authorization methods, the client’s TLS connection is terminated in the API Gateway. The issuer and subject fields are extracted by the API Gateway and passed on to the WSOP server as part of the request.

Third-party solutions exist to aid creation and management of client identity information. Alternatively (and only when using client TLS certificates), OpenSSL is able to create and manage certificates. It is shipped with most distributions, and also distributed as part of nShield Security World Software.

If using client certificates, Entrust strongly recommends that a root certificate and client certificate hierarchy are created specifically for WSOP.

Entrust strongly advises against using WSOP client authentication certificates or tokens 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 issuer and subject fields. These are provided either from the Web Services client TLS certificate or an API Gateway.

Virtual Partitioning

To enforce virtual partioning of clients, each distinct client must have a unique combination of issuer and subject fields. 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 provided issuer and subject fields.

See Virtual Partitioning for more information.

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

If using client certificates, 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.

If not using an API Gateway, to disable client authentication, set client_auth_enabled: false To enable it, set client_auth_enabled: true

If using an API Gateway, client authentication is determined by the gateway’s settings. In this context, client_auth_enabled instead controls whether authentication of the gateway to WSOP is enabled and its setting is deployment dependent.

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 its extension is .crl, .pem, or .der and it is signed by the private key of the root certificate for the revoked client TLS certificates. The CRL sign extension must be enabled for the signing CA. corecrypto checks the validity of the CRL that is revoking the client certificates by consulting the root certificate that was used for validating the client TLS 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 (CRL) 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.