Configuring Datacom Rest or Business API to use SAF keyrings instead of keystore

Products

• Datacom
• Datacom/DB
• Datacom/AD

Issue/Introduction

Setting up the Datacom Systems Rest or Business API to use a SAF keyring instead of a keystore and the following error is received:

DATACOM (com.broadcom.restapi.sdk.security.auth.sdk.SdkTokenProvider:97) ERROR Cannot load keystore
'safkeyring://userid/Keyring' because `unknown protocol: safkeyring`. The service is not able to start.

Resolution

Below is the format of the server.ssl section in the application.yml to use SAF keyrings with different Java versions.

Java 8

ssl:                                        
    keyAlias: certificate_label  
    keyStore: safkeyring:////keyring_owner_userid/keyring_name  
    keyPassword: password                   
    keyStoreType: JCERACFKS                 
    keyStorePassword: password              
    trustStore: safkeyring:////keyring_owner_userid/keyring_name
    trustStoreType: JCERACFKS               
    trustStorePassword: password   
    protocol: TLSv1.2

Update the following:
certificate_label - the label of the certificate.
keyring_owner_userid/keyring_name - the owner and name of the SAF keyring containing the TLS certificates 
TLSv1.2 - specify the TLS protocol version

Note: for SAF keyrings, use `password` as the password. Do not change this.

To use SAF keyrings in Java 8 the java.protocol.handler.pkgs system property also needs to be set.
In the REST API JCL update the STDENV input and add the line below before the export of IBM_JAVA_OPTIONS:

IJO="$IJO -Djava.protocol.handler.pkgs=com.ibm.crypto.provider"
export IBM_JAVA_OPTIONS="${IJO}" 

 

Java 11

ssl:                                        
    keyAlias: certificate_label  
    keyStore: safkeyringjce:////keyring_owner_userid/keyring_name  
    keyPassword: password                   
    keyStoreType: JCERACFKS                 
    keyStorePassword: password              
    trustStore: safkeyringjce:////keyring_owner_userid/keyring_name
    trustStoreType: JCERACFKS               
    trustStorePassword: password   
    protocol: TLSv1.2

Update the following:
certificate_label - the label of the certificate.
keyring_owner_userid/keyring_name - the owner and name of the SAF keyring containing the TLS certificates 
TLSv1.2 - specify the TLS protocol version

Note: for SAF keyrings, use `password` as the password. Do not change this.

There is no need to set the java.protocol.handler.pkgs system property with Java 11.

Additional Information

See documentation section Install the Datacom Systems REST API.