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 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 (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.