Signature key material

Whenever tokens or other messages must be signed such that the receiver of the message can verify that a specific nevisAuth instance issued it, private keys must be configured. An AuthState or service (e.g., TokenAssembler) can reference the KeyObject element configuration.

Java KeyStore (JKS)

For example, the TokenAssembler usually uses the DefaultSigner to sign the SecToken:

<KeyStore name="DefaultKeyStore">
    <KeyObject name="DefaultSigner"
        certificate="/var/opt/keybox/nevis/authSigner_keystore.jks?alias=authSigner"
        privateKey="/var/opt/keybox/nevis/authSigner_keystore.jks?alias=authSigner"
        passPhrase="neviscred://authSignerPW"
    />
</KeyStore>

Since we need access to the private key, which is usually encrypted with a password, we need to specify the privateKey and passphrase attributes for the KeyObject element.

Whenever we are using a JKS keystore, it is possible to reference exactly one certificate or private key using the alias syntax. For example, if the authSigner_keystore.jks contains multiple certificates or private keys, the alias will specify which certificate or private key should be fetched.

PKCS11 (HSM, 64-bit)

nevisAuth supports hardware security modules (HSMs) as key material storage through the SunPKCS11 security provider.

Configuration Parameters (esauth4.xml)

HSM example configuration

<KeyStore id="DefaultKeyStore">
    <KeyObject name="DefaultSigner"
        certificate="pkcs11://?alias=<alias>?provider=SunPKCS11-<name>"
        privateKey="pkcs11://?alias=<alias>?provider=SunPKCS11-<name>"
        passPhrase="neviscred://<neviscred-alias>"
    />
</KeyStore>

The <alias> string in the example above has to be replaced with the alias of the according certificate/private key in the HSM. It is highly recommended using the same alias for a certificate and for its private key.

SunPKCS11 Parameters (pkcs11.cfg)

The configuration of the SunPKCS11 security provider is stored in the following file: /var/opt/nevisauth/<instance>/conf/pkcs11.cfg

name = HsmName
library = /usr/safenet/lunaclient/lib/libCryptoki2_64.so
slot = 1

• name: Unique identifier for scenarios where multiple HSMs are used
• library: The vendor-specific HSM library (64-bit).
• slot: The slot number on the HSM.

In our example, the according KeyObject identifier in the esauth4.xml would look as follows (assuming the HSM contains a certificate and a private key with alias TokenSigner): pkcs11://?alias=TokenSigner?provider=SunPKCS11-HsmName

info

For some HSMs, it is required to force the login for KeyStoreType. In such a case, the following line needs to be added to the vmargs.conf file: -Dch.nevis.esauth.security.provider.pkcs11.forcelogin=true

Java Security Provider Parameters (esauth4.security)

It might happen that the SunPKCS11 security provider is not activated in a nevisAuth instance. In such a case the SunPKCS11 security provider needs to be added to the /var/opt/nevisauth/<instance>/conf/esauth4.security file:

security.provider.10=sun.security.pkcs11.SunPKCS11 /var/opt/nevisauth/<instname>/conf/pkcs11.cfg

Securosys HSM

nevisAuth supports the Securosys hardware security modules (HSMs). Securosys recommends using the JCE integration instead of PKCS11. This is why we recommend setting up nevisAuth as described below (instead of the general PKCS11 configuration above) to use keys stored in a Securosys HSM .

Configuration Parameters (esauth4.xml)

If you want to employ Securosys, configure nevisAuth to use SHA256withRSA to sign the SecTokens. This is required because Securosys does not support nevisAuths algorithm SHA1withRSA (it is not secure enough).

esauth4.xml

<TokenAssembler name="DefaultTokenAssembler">
    <Selector default="true"/>
    <TokenSpec version="CSSO-1.0" ttl="28800" useGmt="true" algorithm="SHA256withRSA">
        <field src="session" key="ch.nevis.session.sessid"    as="sessid"/>
        <field src="session" key="ch.nevis.session.userid"    as="userid"/>
        <field src="session" key="ch.nevis.session.authlevel" as="authLevel"/>
        <field src="session" key="ch.nevis.session.esauthid"  as="esauthid"/>
        <field src="session" key="ch.nevis.session.entryid"   as="entryid"/>
        <field src="session" key="ch.nevis.session.loginid"   as="loginId"/>
        <field src="session" key="ch.nevis.session.domain"    as="domain"/>
        <field src="session" key="ch.nevis.session.secroles"  as="roles" />
    </TokenSpec>
    <Signer key="SecurosysSigner"/>
</TokenAssembler>

Define the key to be used:

<KeyStore name="DefaultKeyStore">
    <KeyObject id="SecurosysSigner"
        certificate="Primus:?alias=<alias>?provider=SecurosysPrimusXSeries"
        privateKey="Primus:?alias=<alias>?provider=SecurosysPrimusXSeries"/>
</KeyStore>

The <alias> string in the example above has to be replaced with the alias of the according certificate/private key in the Securosys HSM. It is highly recommended using the same alias for the certificate and its private key.

Java Security Provider Parameters (esauth4.security)

The Securosys security provider (named Primus) needs to be specified in the file /var/opt/nevisauth/<instance>/conf/esauth4.security:

security.provider.11=com.securosys.primus.jce.PrimusProvider

Java Virtual Machine Arguments (env.conf)

The Primus security provider is configured with Java Virtual Machine arguments. This includes providing the hostname of the server containing the key material, the JCE port and the credentials required by nevisAuth to manage the key material. These parameters must be added to the JAVA_OPTS in the file /var/opt/nevisauth/<instance>/conf/env.conf:

# Securosys configuration
-Dcom.securosys.primus.jce.credentials.host=<Primus host name>
-Dcom.securosys.primus.jce.credentials.port=<Primus JCE port>
-Dcom.securosys.primus.jce.credentials.user=<Primus username>
-Dcom.securosys.primus.jce.credentials.password=<Primus password>

Include the Securosys JCE library in the classpath of nevisAuth

1. Download the primusX.jar file from Securosys.
2. Copy the primusX.jar file into your nevisAuth instance's library directory /var/opt/nevisauth/<instance>/lib/. Ensure that /var/opt/nevisauth/<instance>/lib/ is on your instance's classpath (as it is per default).