Oracle Cloud Infrastructure Documentation

Configuring JCE

Use the information in the following topics to configure the Dedicated Key Management JCE provider.

Setting the Environment Variable for the JCE Provider

Set the following environment variable to use the JCE Provider:

LD_LIBRARY_PATH: This variable must include the path to the directory that contains the ocidkmsjca.so file. Using this variable lets JCE find the native java libraries required to communicate with the HSM. For standard installations, the directory is /opt/oci/hsm/lib.

Add the JCE Provider to Java Security

You must add the JCE provider to the Java security configuration for your system using either of the methods described in this section.

To edit the Java Security file

In the JAVA_HOME, add the OCI Dedicated KMS security provider to the end of the list of security providers. The provider entry is the following:

security.provider.<list-number>=com.oracle.dkms.jce.provider.DedicatedKmsProvider

  1. Open the java.security file in a editor. For example, run this command to open the file in the VIM editor:

    $ vim /usr/lib/jvm/java-11-openjdk/conf/security/java.security

  2. Add the entry to the end of the list of security providers in the file. In the following example, the entry is added as security.provider.13:

    $ vim /usr/lib/jvm/java-11-openjdk/conf/security/java.security
security.provider.1=SUN
security.provider.2=SunRsaSign
security.provider.3=SunEC
security.provider.4=SunJSSE
security.provider.5=SunJCE
security.provider.6=SunJGSS
security.provider.7=SunSASL
security.provider.8=XMLDSig
security.provider.9=SunPCSC
security.provider.10=JdkLDAP
security.provider.11=JdkSASL
security.provider.12=SunPKCS11
security.provider.13=com.oracle.dkms.jce.provider.DedicatedKmsProvider
To dynamically load the JCE provider in Java applications

Use the addProvider method in the Security Java class to add the JCE Provider, as follows:

DedicatedKmsProvider provider =  new DedicatedKmsProvider();
Security.addProvider(provider);

See addProvider in the Java documentation for more information.

Authentication

Users are authenticated for login to the HSM by credentials that are retrieved from several sources in a specific order of priority. If valid credentials are found in any source, the login is completed. If no valid credentials are found, the login fails.

Credential Sources and Priority Order

Login credentials are provided by following mechanisms:

  1. CallbackHandler: If this is provided, it retrieves credentials dynamically. For example:

    public class CustomCallbackHandler implements CallbackHandler {
    private final String username;
    private final char[] password;
 
    public CustomCallbackHandler(String username, char[] password) {
        this.username = username;
        this.password = password;
    }
 
    @Override
    public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException {
        for (Callback callback : callbacks) {
            if (callback instanceof NameCallback) {
                ((NameCallback) callback).setName(username);
            } else if (callback instanceof PasswordCallback) {
                ((PasswordCallback) callback).setPassword(password);
            } else {
                throw new UnsupportedCallbackException(callback, "Unsupported callback type");
            }
        }
    }
}            

DedicatedKmsProvider provider = new DedicatedKmsProvider();
Security.addProvider(provider);
CustomCallbackHandler handler = new CustomCallbackHandler(crypto_user, cupassword.toCharArray());
provider.login(null, handler);

  2. HsmCredentials.properties file: The application checks for a properties file named HsmCredentials.properties in the classpath. If the file exists and contains valid credentials, they're used for authentication. This file must contain the following:

    • HSM_USER = crypto_user
    • HSM_PASSWORD = cupassword

  3. Java system properties: If the credentials aren't found in the properties file, the Java System properties are checked. The HSM_USER, and HSM_PASSWORD values are expected to be set as system properties. You can set these using -D flags when running java applications. For example

    -DHSM_USER=crypto_user 
-DHSM_PASSWORD=cupassword

  4. Operating System environment variables (lowest priority): If the credentials aren't found in Java system properties,they can be retrieved from environment variables, if the environment variables are set. Set HSM_USER, and HSM_PASSWORD values as environment variables, then export them as shown in the following example:

    export HSM_USER=crypto_user 
export HSM_PASSWORD=cupassword