Guidelines for Configuring External Certificates for a new Installation

Follow these steps to configure a new store to use external certificates:

Note:

This procedure assumes you already have a Java keystore and truststore setup. For more information see Java KeyStore Preparation.

1. Collect the distinguished name from the verbose information of the external certificate. In this example, it is the value of the owner field.

   keytool -list -v -keystore store.keys alias shared
   Certificate chain length: 3
   Certificate[1]:
   Owner: CN=myhost, OU=TeamA, O=MyCompany, L=Unknown, ST=California, 
   C=US
   Issuer: CN=intermediate CA, OU=CA, O=MyCompany, ST=California, 
   C=US 

2. Prepare dnmatch expression using a distinguished name. Oracle NoSQL Database verifies identities of server and client while establishing SSL connection between the server components. The verification is performed by checking if principal names on each side match the specified dnmatch expressions, which uses regular expressions as specified by java.util.regex.Pattern. The principal names represent the identities, which are specified by the subject name attribute of the certificate, represented as a distinguished name in RFC 1779 format, using the exact order, capitalization, and spaces of the attribute value. RFC 1779 defines well-known attributes for distinguished names, including CN, L, ST O, OU, C and STREET. If the distinguished name of the external certificate contains non-standard attributes, for example, EMAILADDRESS, then the expression used for dnmatch must replace these attribute names with an OID that is valid in RFC 1779 form, or use special constructs of regular expression to skip checking these attributes. The format for a dnmatch expression is:

   dnmatch(regular expression)

   In above example, the dnmatch expression is:

   dnmatch(CN=myhost, OU=TeamA, O=MyCompany, L=Unknown, 
   ST=California, C=US)

   If you are using a wild card to match a certificate with a non-standard distinguished name attribute, the dnmatch expression needs to match the attribute name in its OID format properly. For example, if the distinguished name is:

   EMAILADDRESS=[e-mail], CN=myhost, OU=TeamA, O=MyCompany, 
   L=Unknown, ST=California, C=US

   Then wild card should represent the entire EMAILADDRESS attribute name:

   dnmatch(.*=[e-mail], CN=myhost, OU=TeamA, O=MyCompany, 
   L=Unknown, ST=California, C=US)

3. Run makebootconfig to setup the secure store. Also specify the keystore password and dnmatch expressions in the security parameters. The keystore password "password" must use the same password as the Java Keystore of the external certificates. See:

   java -Xmx64m -Xms64m -jar <KVHOME>/lib/kvstore.jar makebootconfig \
   -root KVROOT -host node01 -port 5000 -harange 5010,5020 -admin 5001 \
   -store-security configure \
   -pwdmgr wallet -kspwd password \
   -security-param client:serverIdentityAllowed="dnmatch
   (CN=myhost, OU=TeamA, O=MyCompany, L=Unknown, ST=California, C=US)" \
   -security-param internal:serverIdentityAllowed="dnmatch
   (CN=myhost, OU=TeamA, O=MyCompany, L=Unknown, ST=California, C=US)" \
   -security-param internal:clientIdentityAllowed="dnmatch
   (CN=myhost, OU=TeamA, O=MyCompany, L=Unknown, ST=California, C=US)" \
   -security-param ha:serverIdentityAllowed="dnmatch
   (CN=myhost, OU=TeamA, O=MyCompany, L=Unknown, ST=California, C=US)" \
   -security-param ha:clientIdentityAllowed="dnmatch
   (CN=myhost, OU=TeamA, O=MyCompany, L=Unknown, ST=California, C=US)"
   

   By default the keystore entry is stored under an alias "shared" and the truststore entry is stored under an alias "mykey". If you are using customized aliases for keystore and truststore, then additional flags need to be specified in the makebootconfig command.

   For example if your customized keystore alias is "currentKey" and the certificate is stored in the truststore under the "currentCert" alias, the following additional parameters have to be included in the makebootconfig command.

   -security-param "client:serverKeyAlias=currentKey"
   -security-param "ha:serverKeyAlias=currentKey"
   -security-param "internal:clientKeyAlias=currentKey"
   -security-param "internal:serverKeyAlias=currentKey"
   -security-param "keystoreSigPrivateKeyAlias=currentKey"
   -security-param "truststoreSigPublicKeyAlias=currentCert"

   The modified makebootconfig command with these additional flags is given below.

   java -Xmx64m -Xms64m -jar <KVHOME>/lib/kvstore.jar makebootconfig \
   -root KVROOT -host node01 -port 5000 -harange 5010,5020 -admin 5001 \
   -store-security configure \
   -pwdmgr wallet -kspwd password \
   -security-param client:serverIdentityAllowed="dnmatch
   (CN=myhost, OU=TeamA, O=MyCompany, L=Unknown, ST=California, C=US)" \
   -security-param internal:serverIdentityAllowed="dnmatch
   (CN=myhost, OU=TeamA, O=MyCompany, L=Unknown, ST=California, C=US)" \
   -security-param internal:clientIdentityAllowed="dnmatch
   (CN=myhost, OU=TeamA, O=MyCompany, L=Unknown, ST=California, C=US)" \
   -security-param ha:serverIdentityAllowed="dnmatch
   (CN=myhost, OU=TeamA, O=MyCompany, L=Unknown, ST=California, C=US)" \
   -security-param ha:clientIdentityAllowed="dnmatch
   (CN=myhost, OU=TeamA, O=MyCompany, L=Unknown, ST=California, C=US)"
   -security-param "client:serverKeyAlias=currentKey" \
   -security-param "ha:serverKeyAlias=currentKey" \
   -security-param "internal:clientKeyAlias=currentKey" \
   -security-param "internal:serverKeyAlias=currentKey" \
   -security-param "keystoreSigPrivateKeyAlias=currentKey" \
   -security-param "truststoreSigPublicKeyAlias=currentCert"

4. The makebootconfig command automatically generates keystore, server, and client truststore files using self-signed certificates. To use external certificates instead, you need to replace the keystore and truststore files with your own on each server that will host a Storage Node. For example:

   copy store.keys store.trust client.trust KVROOT/security/ 

5. Use the securityconfig tool to verify installation. For example:

   security-> config verify -secdir KVROOT/security
   Security configuration verification passed.

   Note:

   For older releases (prior 4.1), you needed to verify the configuration manually. In that case, the distinguished name of the certificate must match the content inside of dnmatch in security.xml. Also, the user-generated keystore password must be the same as the one stored in the wallet (store.wallet) or the password file (store.pwd). Finally, the truststore (store.trust) must contain the CA certificates and the one used for Oracle NoSQL Database.

6. Finally, deliver the client.trust or import the CA certificates into the client truststore.