Key Management

Automatic Key Store

#Key Management

Plugin: nevisadmin-plugin-nevisproxy

Sets up a key store managed by nevisAdmin 4.

In classic deployment the private key is generated during deployment by running a command on the target host.

nevisAdmin then downloads the CSR and issues a certificate, which is deployed to the target host.

In Kubernetes deployment a custom resource definition (CRD) is generated and sent to the Nevis Operator running in the cluster.

Set the inventory variable __nevisadmin_pki_automatic_allowed_mode to restrict the allowed modes:

• any (default) - assignment of key management patterns is optional.
• explicit - assign patterns where-ever a key store or trust store is required.

This example illustrates how the key store looks on the target system:

[root@nevis /]# ls -l /var/opt/keys/own/<name>/
total 40
-rw-r----- 1 root nvbgroup 1103 Dec  1 07:05 ca-chain.pem
-rw-r----- 1 root nvbgroup 1013 Dec  1 07:05 cert.pem
-rw-r----- 1 root nvbgroup  887 Dec  1 07:05 csr.pem
-rwxr-x--- 1 root nvbgroup   40 Dec  1 07:05 keypass
-rw-r----- 1 root nvbgroup 1675 Dec  1 07:05 key_pkcs1.pem
-rw-r----- 1 root nvbgroup 1704 Dec  1 07:05 key.pem
-rw-r----- 1 root nvbgroup  451 Dec  1 07:05 key_pub.pem
-rw-r----- 1 root nvbgroup 2053 Dec  1 07:05 keystore.jks
-rw-r----- 1 root nvbgroup 2309 Dec  1 07:05 keystore.p12
-rw-r----- 1 root nvbgroup 2688 Dec  1 07:05 keystore.pem

Owner(s)

Select an instance pattern which defines the target hosts of this Automatic Key Store. This setting is required only when this pattern is assigned to an Automatic Trust Store.

Automatic Trust Store

#Key Management

Plugin: nevisadmin-plugin-nevisproxy

Sets up a trust store managed by nevisAdmin 4.

In classic deployment the certificates of trusted key stores are deployed to the target host.

In Kubernetes deployment a custom resource definition (CRD) is generated instead and sent to the Nevis Operator running in the cluster.

Set the inventory variable __nevisadmin_pki_automatic_allowed_mode to restrict the allowed modes:

• any (default) - assignment of key management patterns is optional.
• explicit - assign patterns where-ever a key store or trust store is required.

This example illustrates how the trust store looks on the target system:

[root@nevis /]# ls -l /var/opt/keys/trust/<name>/
total 16
-rwxr-x--- 1 root nvbgroup   16 Dec  1 07:05 keypass
-rw-r----- 1 root nvbgroup 1656 Dec  1 07:05 truststore.jks
-rw-r----- 1 root nvbgroup 2042 Dec  1 07:05 truststore.p12
-rw-r----- 1 root nvbgroup 2116 Dec  1 07:05 truststore.pem

Trusted Key Store

Assign one or multiple Automatic Key Store patterns to establish a trust relation.

Additional Trusted Cert(s)

Upload additional trusted certificates in PEM format.

The content of all files will be concatenated and added to the truststore.* files generated by this pattern.

You can make this a variable and upload the files in the inventory using the Attach files function.

Certbot Key Store

#Key Management #Experimental

Plugin: nevisadmin-plugin-nevisproxy

Sets up a key store that uses certbot to request a certificate from Let's Encrypt via the ACME protocol.

This pattern can only be used in classic deployment and requires that certbot is installed on the deployment host.

The pattern was tested in combination with nevisAppliance as Frontend Key Store in the Virtual Host pattern.

The pattern is experimental and provided as a proof of concept so that you can try it out.

If you need additional settings or want to use the pattern in another place, you may request a pattern improvement by raising a feature request with Nevis.

The certbot command will open a service on port 80 as the CA (Let's Encrypt) has to do a callback to validate the DNS name. The alternative mode (DNS01) is not supported.

This pattern generates the required command and also ensures that the nevisProxy instance is restarted, once the new key material is available.

Certbot will register a job that will renew the certificate before expiry.

Admin Email

Enter an email address.

The email will be handed over to the certbot command and can be used by the CA for urgent renewal and security notices.

If not configured, then an email will be determined based on primary domain of the Virtual Host.

That email will be noreply@<domain>.

nevisAuth KeyObject

#Authentication #Key Management

Plugin: nevisadmin-plugin-nevisauth

Generates a KeyObject element for nevisAuth.

A KeyObject element can be used as key store or trust store.

These elements are used in various cases and are typically referenced by an AuthState.

The structure of KeyObject elements is explained in the Certificate validation section of the technical documentation of nevisAuth.

Assign this pattern to a Generic Authentication Step to add the KeyObject to your nevisAuth configuration.

The sanitized name of the Generic Authentication Step is used as name of the KeyStore parent element.

KeyObject ID

Set the attribute id of the KeyObject element.

The id must be unique within the nevisAuth instance. If not set the sanitized name of this pattern will be used.

KeyStore Name

Define the name of the parent KeyStore element.

You can enter the name of a KeyStore element generated by another pattern, or enter a new name.

If not configured, the name of the KeyStore depends on where this nevisAuth KeyObject pattern is assigned:

• Generic Authentication Realm: sanitized name of the realm pattern.
• Generic Authentication Step: sanitized name of the step pattern.
• nevisAuth Instance: the name AddonKeyStore.

Note that the nevisAuth configuration always contains a KeyStore element with name DefaultKeyStore. This KeyStore is typically used as a container for signer key material.

Type

Select key store when a private key is needed. Select trust store for providing trusted certificate (e.g. for signature validation).

Key Store

Reference a key store provider pattern or leave empty to let nevisAdmin establish a key store. This reference property is considered when type key store is selected.

Trust Store

Reference a trust store provider pattern or leave empty to let nevisAdmin establish a trust store. This reference property is considered when type trust store is selected.

Revocation

Define the revocation attribute of the KeyObject.

You can enter a path or URL of the certificate revocation list or the URL to the OCSP service.

See Generic key material configuration attributes for examples.

Custom Properties

Add property child elements to the KeyObject element.

nevisKeybox Store

#Key Management

Plugin: nevisadmin-plugin-nevisproxy

Apply the pattern to use existing key material from nevisKeybox. You can assign the pattern where-ever a key store or trust store is required.

The nevisKeybox instance is to be named default.

The pattern does not deploy any key material. This is the intended behavior and not a limitation.

To deploy a private key and certificate you may use PEM Key Store instead, for deploying trusted certificates use PEM Trust Store instead.

Slot

A Slot is a directory of a nevisKeybox instance.

By default, nevisKeybox is located at /var/opt/neviskeybox/default/. If missing please run the following command on the affected target server(s):

neviskeybox handover

A Slot may contain:

• an arbitrary number of key stores (identified by label)
• up to 1 trust store.

Label

Setting the Label is required if this pattern is used as a key store provider.

This pattern relies on the standard nevisKeybox mechanism for retrieving the passphrase of the private key.

Run the following commands on all target server(s) to ensure the passphrase can be retrieved:

neviskeybox passwd -slot <slot> -label <label> -keep

neviskeybox access -slot <slot> -label <label> -group nvbgroup

The last command will generate a shell script /var/opt/neviskeybox/default/<slot>/<label>_keypass which can be invoked by NEVIS components to retrieve the passphrase.

Due to a limitation in some NEVIS components keypass files which contain base64 encoded passphrases are not supported yet. Replace any of the following content with a simple echo returning the passphrase directly.

echo "cGFzc3dvcmQ=" | openssl base64 -d

nevisKeybox may also be integrated with nevisCred to store the passphrase in a secure place. In this case the shell script will not contain the passphrase but a call of nevisCred.

Validation

Allows to the validation in case the nevisKeybox is deployed by this project (e.g. using Generic Deployment).

PEM Key Store

#Key Management

Plugin: nevisadmin-plugin-nevisproxy

Sets up a key store.

Private key and certificate must be uploaded in PEM format. If the key is encrypted, Private Key Passphrase must be set.

For performance reasons, some issues are reported during deployment only.

The store will be deployed to /var/opt/keys/own/<name>.

Some files are generated and contain entropy (e.g. generation timestamp). To avoid fake changes on subsequent deployments, these files are cached in the nevisAdmin 4 database.

The cache has an expiration of 6 months and will also be invalidated when you change the uploaded key.pem, cert.pem, or the Key Store Passphrase.

Key Store Content

Upload your key material in PEM format.

File name	Description	Required
key.pem	private key	yes
cert.pem	own certificate	yes
ca-chain.pem	CA chain	when providing a HTTPS endpoint

Examples

How to produce the required files depends on your setup. The following examples use openssl.

Generate a private key:

openssl genrsa -des3 -out key.pem 2048

Generate a certificate signing request (CSR):

openssl req -new -key key.pem -out example.csr -subj "/C=CH/O=Example Company/CN=example.com"

If this key store is used to provide a HTTPs endpoint, the common name (CN) should contain the domain.

You can now use the CSR to request a certificate from your CA. For testing a self-signed certificate is often sufficient:

openssl x509 -signkey key.pem -in example.csr -req -days 365 -out cert.pem

Hardening

We recommend using a variable so that you can use secrets to protect the content. This example references 2 nevisAdmin 4 secrets storing private key and own certificate:

  my-variable:

    - inv-res-secret://f370a14a36db9f29763e8dc1#key.pem
    - inv-res-secret://147cc54a5629fadac761ec01#cert.pem

When deploying to Kubernetes, the key material may be stored in a Kubernetes secret instead. nevisAdmin 4 does not retrieve Kubernetes secrets during generation and thus all key store files must be provided. This example uses a Kubernetes secret my-secret:

  my-variable:

    - k8s-secret-file://my-secret:key.pem/
    - k8s-secret-file://my-secret:cert.pem/
    - k8s-secret-file://my-secret:ca-chain.pem/
    - k8s-secret-file://my-secret:keystore.pem/
    - k8s-secret-file://my-secret:keystore.jks/
    - k8s-secret-file://my-secret:keystore.p12/
    - k8s-secret-file://my-secret:keypass/

The additional keystore.* files contain private key, own certificate, and the CA chain. You can use the Java keytool and openssl to produce these files.

The keypass file must be a script which is executable by nvbgroup and prints the passphrase for keystore.* and key.pem to stdout.

nevisAdmin 4 does not notice when the content of the Kubernetes secret changes. Manual interaction (terminating pods) is required in that case.

Private Key Passphrase

Enter the passphrase of the private key.

The passphrase will be used to decrypt the uploaded private key, if it is encrypted.

As the passphrase is considered sensitive information it should not be published with the project. It is therefore required to use a variable and define the value in the inventory (as a secret).

The default value of the variable is not relevant as the key is not loaded during background validation.

Key Store Passphrase

Enter a passphrase.

The passphrase will be used to protect sensitive keystore files (key.pem, keystore.pem, keystore.jks, and keystore.p12) on the target hosts.

If you do not enter any passphrase a passphrase will be generated.

As the passphrase is considered sensitive information it should not be published with the project. It is therefore required to use a variable and set the value in the inventory (as a secret).

Custom Directory Name

Enter a name for the key store directory which is used instead of the pattern name.

This configuration may be used to prevent key stores overwriting each other and is only required in complex setups with multiple projects or inventories.

Custom Root Directory Name

Set to deploy the key store underneath a base directory. The key store will be established at:

/var/opt/keys/own/<base>/<name>

This configuration may be used to prevent key stores overwriting each other and is only required in complex setups with multiple projects or inventories.

PEM Trust Store

#Key Management

Plugin: nevisadmin-plugin-nevisproxy

Set up a trust store.

The trust store is deployed to /var/opt/keys/trust/<name>.

The trust store will contain the following files:

• truststore.pem
• truststore.jks - JKS format
• truststore.p12 - PKCS12 format
• keypass - used by Java-based components to retrieve the password to access the JKS or PKCS12 files

All truststore.* files contain the same certificates.

The JKS and PKCS12 files are created during the first generation, and then stored in a cache backed by the nevisAdmin 4 database.

Kubernetes PEM-only mode

In Kubernetes deployments, you may provide one or more k8s-secret-file:// references to .pem certificate files instead of the complete 4-file set (truststore.pem, truststore.jks, truststore.p12, keypass). In this mode, a NevisTrustStore CRD is generated and the Nevis Operator assembles the full trust store from the supplied PEM certificates. Only .pem files are accepted; providing a non-PEM file in this mode results in a validation error.

Trusted Cert(s)

Upload trusted certificate(s) in PEM format.

If you set a variable, the variable should be a list of secret file references in the inventory. Example:

  my-variable:

    - inv-res-secret://147cc54a5629fadac761ec01#some-cert.pem
    - inv-res-secret://147cc54a5629fadac761ec01#some-other-cert.pem

Upload files for this variable by clicking Attach files in the drop-down on the inventory screen.

If you are deploying to Kubernetes you may store the trust store content in a Kubernetes secret. You can pick any name for the Kubernetes secret but the keys must be as in the following example:

  my-variable:

    - k8s-secret-file://dummy-truststore:truststore.pem/
    - k8s-secret-file://dummy-truststore:truststore.jks/
    - k8s-secret-file://dummy-truststore:truststore.p12/
    - k8s-secret-file://dummy-truststore:keypass/

Note that nevisAdmin 4 does not notice when the content of the Kubernetes secret changes. Manual interaction (terminating pods) is required in that case.

Custom Directory Name

Enter a name for the trust store directory which is used instead of the pattern name.

This configuration may be used to prevent trust stores overwriting each other and is only required in complex setups with multiple projects or inventories.

Custom Root Directory Name

Set to deploy the trust store underneath a base directory. The trust store will be established at:

/var/opt/keys/trust/<base>/<name>

This configuration may be used to prevent trust stores overwriting each other and is only required in complex setups with multiple projects or inventories.

Securosys Key Store

#Key Management

Plugin: nevisadmin-plugin-nevisproxy

Sets up a Securosys HSM based key store.

The necessary configuration files are deployed into '/etc/primus', while the library itself is shipped with the image.

Certificate with private key is required.

If the certificate does not contain the private key, set the private key separately.

If the private key is encrypted, the passphrase has to be set.

The configuration files are not validated by nevisAdmin 4.

Certificates object label

The certificate objects label on the HSM.

Private Keys object label

The key objects label on the HSM.

Securosys PIN

The PIN for accessing the materials on the HSM.

You must set it as a variable for security reasons.

Securosys configuration files

The configuration files for accessing the HSM.

This two are mandatory: 'primus.cfg' must contain the configuration settings for connecting to the HSM, and '.secrets.cfg' must contain the credentials to access the materials on HSM.

This one is mandatory for classic setup: 'openssl.cnf' contains the information for the the OpenSSL provider. In K8S setup the 'openssl.cnf' is already provided by the nevisProxy docker image.

Keep in mind that the files are not validated, first set up a working configuration, and use the already validated files here.