Key Management

Automatic Key Store

#Key Management

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

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.

nevisAuth KeyObject

#Authentication #Key Management

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.

PEM Key Store

#Key Management

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

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.