Quickstart

This guide explains how to download and install the Primus JCE Provider. Once installed, it shows how to exchange the setup password for the permanent secret.

Prerequisites

This guide assumes that:

• You have access to an HSM (cluster).
• You know the connectivity details for your HSM (host IP address/domain, JCE port).
• Your HSM administrator (Security Officer) has given you a user name/partition name and a corresponding setup password.
• [CloudHSM only] You know your proxy user name and proxy password.

warning

The setup password expires! In CloudHSM, it expires after 7 days. Therefore, make sure to exchange the setup password for a permanent secret. The steps are explained below.

Option 1: From Maven Repository

For easy integration with your build system, you can add the Securosys Maven Repository to your Gradle or Maven build configuration.

info

The Artifactory credentials that are needed to access the repository are available in the Downloads section.

Gradle Configuration

In your root build.gradle, declare the repository:

allprojects {
    repositories {
        mavenCentral()

        maven {
            url "https://securosys.jfrog.io/artifactory/jce-maven"
            credentials {
                username = project.findProperty("com.securosys.artifactory_user") ?: System.getenv("SECUROSYS_ARTIFACTORY_USER")
                password = project.findProperty("com.securosys.artifactory_password") ?: System.getenv("SECUROSYS_ARTIFACTORY_PASSWORD")
            }
            // https://docs.gradle.org/current/userguide/filtering_repository_content.html
            content {
                includeGroup "com.securosys"
            }
        }
    }
}

Put the access credentials into your ~/.gradle/gradle.properties file (on Windows: C:\Users\<USERNAME>\.gradle\gradle.properties):

com.securosys.artifactory_user=support.reader.jce
com.securosys.artifactory_password=password-get-from-support-portal

In your project's build.gradle, add the Primus JCE Provider as a dependency:

dependencies {
    implementation "com.securosys:primus-jce:2.5.4"
}

Check that Gradle can find the dependencies:

./gradlew clean install

Maven Configuration

In your project's pom.xml, define the repository and the dependency:

<project>

  <repositories>
    <repository>
      <id>com.securosys</id>
      <url>https://securosys.jfrog.io/artifactory/jce-maven</url>
    </repository>
  </repositories>

  <dependencies>
    <dependency>
      <groupId>com.securosys</groupId>
      <artifactId>primus-jce</artifactId>
      <version>2.5.4</version>
    </dependency>
  </dependencies>

</project>

In your ~/.m2/settings.xml file, define the Artifactory credentials:

<settings>
  <servers>
    <server>
      <id>com.securosys</id>
      <username>support.reader.jce</username>
      <password>password-get-from-support-portal</password>
    </server>
  </servers>
</settings>

Check that Maven can find the dependencies:

mvn clean install -U

Option 2: Install JAR Manually

Alternatively, you can download the Primus JCE Provider and manually integrate it into your Java environment.

Download & Extract Files

Download the release bundle. Then extract the ZIP file:

export JCE_PROV_VERSION=v2.x.y
mkdir "primus-jce-${JCE_PROV_VERSION}"
unzip "PrimusAPI_JCE-X-${JCE_PROV_VERSION}.zip" -d "primus-jce-${JCE_PROV_VERSION}"

The release bundle contains:

File	Description
primusX-java8.jar	The JCE provider compiled with Java 8. Recommended.
primusX-java11.jar	The JCE provider compiled with Java 11. Needs minimum Java 11 to run, which some company policies require.
releasenotes.txt	The release notes for this provider version.

The primusX-*.jar is the JCE provider library. It needs to be in your class path whenever you want to access the Primus JCE Provider functions. This is the file that you "link" your custom Java code against.

Put JAR into System-Wide Location

Optionally, you can put the primusX.jar into a system-wide location, where applications can access it:

sudo cp "primus-jce-${JCE_PROV_VERSION}/primusX-java8.jar" "/usr/share/java/primusX.jar"

Configure Your IDE

You can configure your IDE to discover the primusX.jar. This will allow your IDE to provide you with features like auto-completion.

For VS Code, put the following content in .vscode/settings.json:

{
    "java.project.referencedLibraries": [
        "/usr/share/java/primusX.jar"
    ]
}

Log In to the HSM

The Primus JCE Provider uses a (username, password) combination to authenticate to the HSM and to establish a secure channel:

PrimusConfiguration.setHsmHost(host, port, user);

// When using CloudHSM
PrimusConfiguration.setProxyCredentials(proxyUser, proxyPassword);

// Establish a session with the HSM
PrimusLogin.login(user, password);

// Close the session
PrimusLogin.logout();

The user is your partition name. The password is either the initial setup password or the permanent user secret.

Fetch the Permanent Secret

The setup password is created by the HSM administrator (Security Officer) and is used to onboard a new application (HSM user). Because the setup password expires, it must be exchanged for the permanent user secret. The time frame of expiry depends on the HSM setting. In CloudHSM, the setup password expires after 7 days.

// Log in with the setup password
PrimusLogin.login(user, password);

// Fetch the permanent user secret
char[] userSecret = PrimusLogin.getUserSecretChars();

// Optionally, blind the permanent user secret
char[] blindedUserSecret = PrimusBlinding.blindChars(userSecret, PrimusBlinding.BlindingAlgorithm.AES);

// Securely store the (blinded) permanent user secret, and use it for future logins.

This means that:

1. A human operator should configure your Java application with a setup password.
2. Your Java application should log in to the HSM once and fetch the permanent user secret.
3. Your Java application should locally (and securely) store the permanent secret.
4. Your Java application should use the permanent secret for all future logins to the HSM.

For more details, see these code samples:

• CloudHSM: CloudsHsmSample.java
• On-premise Primus HSM: UserSecretSample.java

Alternatively, you can manually fetch the permanent secret using the GetUserSecret sub-command of the Primus Tools CLI application (the proxy user and proxy password are only needed for CloudHSM):

java -jar primus-tools.jar GetUserSecret -host a-api.cloudshsm.com -port 2300 -user <PARTITION_NAME> -password <SETUP_PW> -primusproxyuser <PROXY_USER> -primusproxypassword <PROXY_PASSWORD>

warning

1. The setup password expires! If you have lost your permanent secret, contact your HSM administrator to request a new setup password.
2. The login to the HSM is protected against brute force attacks. After too many wrong attempts the login is locked for some time.

Next Steps

The JCE provider setup is now complete.

Continue by exploring the following the code samples, which show how to use the Primus JCE Provider for various use cases:

• Login and password blinding sample
• Create a key, sign a payload, and verify the signature
• Use Key Attributes (Flags) to set properties of a key.
• All Samples