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.
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
-
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
-
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
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:
-
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);
-
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
-
Java system properties: If the credentials aren't found in the properties file, the Java System properties are checked. The
HSM_USER
, andHSM_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
-
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
, andHSM_PASSWORD
values as environment variables, then export them as shown in the following example:export HSM_USER=crypto_user export HSM_PASSWORD=cupassword