Configuring Security with Securityconfig

Creating the security configuration

You can use the config create command to create the security configuration:

config create
-root <secroot> [ -secdir <security dir> ]
[-pwdmgr { pwdfile | wallet <class-name>} ]
[-kspwd <server key and trust store password>]
[-kstype <key and trust store type>]
[-ctspwd <client.trust password>]
[-external-auth {kerberos}]
  [-krb-conf <kerberos configuration>]
  [-kadmin-path <kadmin utility path>]
  [-instance-name <database instance name>]
  [-admin-principal <kerberos admin principal name>]
  [-kadmin-keytab <keytab file>]
  [-kadmin-ccache <credential cache file>]
  [-princ-conf-param <param=value>]*
  [-param [client:|ha:|internal:|]<param>=<value>]*

where:

-root <secroot>

Specifies the directory in which the security configuration will be created. It is not required that this directory be a full KVROOT, but the directory must exist.
-kspwd <server key and trust store password>

Specifies the password used to create keystore and truststore needed by NoSQL Database Server.
-kstype <key and trust store type>

Specifies the store type of keystore and truststore. It must be either JKS or PKCS12.
-ctspwd <client.trust password>

Specifies the password to create PKCS12 password-protected truststore used by client applications to connect NoSQL Database Server.
-external-auth {kerberos} Specifies Kerberos as an external authentication service. This option is only available in the Oracle NoSQL Database EE version. If no keytab or credential cache has been specified on the command line, an interactive version of the securityconfig utility will run.

Using this flag allows Oracle NoSQL Database to generate the security files needed for Kerberos authentication, based on a standard configuration. Although not recommended, it is possible to use a non-standard configuration. To do this, see Manually Registering Oracle NoSQL Database Service Principal.

This flag is only permitted when the value of the -store-security flag is specified as configure or enable.

To remove Kerberos authentication from a running store, set the value of the userExternalAuth security.xml parameter to NONE.

where -external-auth can have the following flags:
- -admin-principal <kerberos admin principal name>
  
  Specifies the principal used to login to the Kerberos admin interface. This is required while using kadmin keytab or password to connect to the admin interface.
- -kadmin-ccache <credential cache file>
  
  Specifies the complete path name to the Kerberos credentials cache file that should contain a service ticket for the kadmin/ADMINHOST. ADMINHOST is the fully-qualified hostname of the admin server or kadmin/admin service.
  
  If not specified, the user is prompted to enter the password for principal while logging to the Kerberos admin interface. This flag cannot be specified in conjunction with the -kadmin-keytab flag.
- -kadmin-keytab <keytab file>
  
  Specifies the location of a Kerberos keytab file that stores Kerberos admin user principals and encrypted keys. The security configuration tool will use the specified keytab file to login to the Kerberos admin interface.
  
  The default location of the keytab file is specified by the Kerberos configuration file. If the keytab is not specified there, then the system looks for the file user.home/krb5.keytab.
  
  You need to specify the -admin-principal flag when using keytab to login to the Kerberos admin, otherwise the correct admin principal will not be recognized. This flag cannot be specified in conjunction with the -kadmin-ccache flag.
- -kadmin-path <kadmin utility path>
  
  Indicates the absolute path of the Kerberos kadmin utility. The default value is /usr/kerberos/sbin/kadmin.
- -krb-conf <kerberos configuration>
  
  Specifies the location of the Kerberos configuration file that contains the default realm and KDC information. If not specified, the default value is /etc/krb5.conf.
- -princ-conf-param <param=value>*
  
  A repeatable argument that allows configuration defaults to be overridden.
  
  Use the krbPrincValidity parameter to specify the expiration date of the Oracle NoSQL Database Kerberos service principal.
  
  Use the krbPrincPwdExpire parameter to specify the password expiration date of the Oracle NoSQL Database Kerberos service principal.
  
  Use the krbKeysalt parameter to specify the keysalt list used to generate the keytab file.
-secdir <security dir>

Specifies the name of the directory within KVROOT that will hold the security configuration. This must be specified as a name relative to the specified secroot. If not specified, the default value is "security".
-pwdmgr [ pwdfile | wallet ]

Indicates the password manager mechanism used to hold passwords that are needed for accessing keystores, etc.

where -pwdmgr can have the following options:
- -pwdmgr pwdfile
  
  Indicates that the password store is a read-protected clear-text password file. This is the only available option for Oracle NoSQL Database CE deployments. You can specify an alternate implementation. For more information on pwdfile manipulation, see Password store file.
- -pwdmgr wallet
  
  Specifies Oracle Wallet as the password storage mechanism. This option is only available in the Oracle NoSQL Database EE version. For more information on Oracle wallet manipulation, see Oracle Wallet.
-param [client:|ha:|internal:|]<param>=<value>]

A repeatable argument that allows configuration defaults to be overridden. The value may be either a simple parameter, such as "truststore", or a qualified parameter such as "client:serverKeyAlias". If specified in qualified form, the qualifier (for example, "client") names a transport within the security configuration, and the assignment is specific to that transport. If in simple form, it applies to either the securityParams structure or to all transports within the file, depending on the type of parameter.

For more information on configuring security with securityconfig, see Performing a Secure Oracle NoSQL Database Installation.

For more information on configuring Kerberos with securityconfig, see Kerberos Authentication Service.

Adding the security configuration

You can use the config add-security command to add the security configuration you created earlier:

config add-security
-root <kvroot> [-secdir <security dir>]
[-config <config.xml>]

Note:

When running this command, the securityconfig tool will verify the existence of the referenced files and will update the specified bootstrap configuration file to refer to the security configuration. This process is normally done with the KVStore instance stopped, and must be performed on each Storage Node of the store.

where:

-root <kvroot>

A KVStore root directory must be provided as an argument.
-secdir <security dir>

Specifies the name of the directory within the KVROOT that holds the security configuration. This must be specified as a name relative to the KVROOT. If not specified, the default value is "security".
-config <config.xml>

Specifies the bootstrap configuration file that is to be updated. This must be specified as a name relative to the KVROOT. If not specified, the default value is "config.xml".

When using Kerberos as an external authentication service, you can use the config add-kerberos command to add the security configuration you created earlier:

config add-kerberos -root <secroot> [-secdir <security dir>]
[-krb-conf <Kerberos configuration>]
[-kadmin-path <kadmin utility path>]
[-instance-name <database instance name>]
[-admin-principal <kerberos admin principal name>]
[-kadmin-keytab <keytab file> ]
[-kadmin-ccache <credential cache file>]
[-princ-conf-param <param=value>]*
[-param <param=value>]*

Verifying the security configuration

You can use the config verify command to verify the consistency and correctness of a security configuration:

config verify -secdir <security dir>

where:

-secdir <securitydir>

Specifies the name of the directory within the KVROOT that holds the security configuration. This must be specified as a name relative to the KVROOT. If not specified, the default value is "security".

For example:

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

Updating the security configuration

You can use the config update command to update the security parameters of a security configuration:

config update -secdir <security dir> [-kstype <keystore type>] [-ctspwd <client.trust password>] [-param <param=value>]*

where:

-secdir <securitydir>

Specifies the name of the directory within the KVROOT that holds the security configuration. This must be specified as a name relative to the KVROOT. If not specified, the default value is "security".
-kstype <keystore type>

Specify the store type to update. Only PKCS12 is allowed. This command updates the keystore (store.keys) and truststore (store.trust) used by NoSQL Database Server to PKCS12 password-protected store. If the Java used to run this command supports password-less truststore, utilities create the truststore used by client applications (client.trust) as a PKCS12 password-less store. If not, utilities fall back to create a JKS store instead if no password specified using -ctspwd <client.trust password>.
-ctspwd <client.trust password>

When updating JKS keystore and truststore in a security configuration to PKCS12, you can use this flag to specify the password to create PKCS12 password-protected truststore used by client applications (client.trust).
-param <param=value*>

List of security parameters to update.

For example:

security-> config update -secdir security -kstype PKCS12 -param clientAuthRequired=false
Configuration updated.

Showing the security configuration

You can use the config show command to print out all security configuration information.

config show -secdir <security dir>

where:

For example:

security-> config show -secdir security
Security parameters:
certMode=shared
internalAuth=ssl
keystore=store.keys
keystorePasswordAlias=keystore
passwordClass=oracle.kv.impl.security.filestore.FileStoreManager
passwordFile=store.passwd
securityEnabled=true
truststore=store.trust

internal Transport parameters:
clientAllowProtocols=TLSv1.2
clientAuthRequired=true
clientIdentityAllowed=dnmatch(CN=NoSQL)
clientKeyAlias=shared
serverIdentityAllowed=dnmatch(CN=NoSQL)
serverKeyAlias=shared
transportType=ssl

client Transport parameters:
clientAllowProtocols=TLSv1.2
serverIdentityAllowed=dnmatch(CN=NoSQL)
serverKeyAlias=shared
transportType=ssl

ha Transport parameters:
allowProtocols=TLSv1.2
clientAuthRequired=true
clientIdentityAllowed=dnmatch(CN=NoSQL)
serverIdentityAllowed=dnmatch(CN=NoSQL)
serverKeyAlias=shared
transportType=ssl

Keystore:
security/store.keys

Keystore type: JKS
Keystore provider: SUN

Your keystore contains 1 entry

shared, Jun 1, 2016, PrivateKeyEntry,
Certificate fingerprint (SHA1): A6:54:9C:42:13:66:DC:E9:A8:62:DB:
A8:87:FD:DE:23:F7:AD:11:FB

Keystore:
security/store.trust

Keystore type: JKS
Keystore provider: SUN

Your keystore contains 1 entry

mykey, Jun 1, 2016, trustedCertEntry,
Certificate fingerprint (SHA1):A6:54:9C:42:13:66:DC:E9:A8:62:DB:
A8:87:FD:DE:23:F7:AD:11:FB

-secdir <securitydir>

Specifies the name of the directory within the KVROOT that holds the security configuration. This must be specified as a name relative to the KVROOT. If not specified, the default value is "security".

Removing the security configuration

If you want to disable security for some reason in an existing installation, you can use the config remove-security command:

config remove-security -root <kvroot> [-config >config.xml>]

Note:

When running this command, the securityconfig tool will update the specified bootstrap configuration file to refer to the security configuration. This process is normally done with the KVStore instance stopped, and must be performed on each Storage Node of the store.

where:

-root <kvroot>

A KVStore root directory must be provided as an argument.
-config <config.xml>

Specifies the bootstrap configuration file that is to be updated. This must be specified as a name relative to the KVROOT. If not specified, the default value is "config.xml".

For example:

security-> config remove-security -secdir security
Configuration updated.

Merging truststore configuration

If you want to merge truststore entries from one security configuration into another security configuration use the config merge-trust command. This command is helpful when performing security maintenance, particularly when you need to update the SSL key/certificate. See Guidelines for Updating SSL Keys and Certificates

config merge-trust
-root <secroot> [-secdir <security dir>]
-source-root <source secroot> [-source-secdir <source secdir>] [-ctspwd <client.trust password>]

Note:

When running this command, the securityconfig tool will verify the existence of the referenced files and will combine trust entries from the source security configuration into the primary security configuration.

where:

-root <secroot>

Specifies the directory that contains the security configuration that will be updated. It is not required that this directory be a full KVROOT, but the directory must exist and contain an existing security configuration.
-secdir <security dir>

Specifies the name of the directory within the secroot that holds the security configuration. This must be specified as a name relative to the secroot. If not specified, the default value is "security".
-source-root <secroot>

Specifies the directory that contains the security configuration that will provide new trust information. It is not required that this directory be a full KVROOT, but the directory must exist and must contain an existing security configuration.
-source-secdir <security dir>

Specifies the name of the security directory within the source secroot that will provide new trust information. If not specified, the default value is "security".
ctspwd <client.trust password>

When merging truststore entries from a security configuration that uses PKCS12 store, utilities create a PKCS12 password-protected truststore used by client applications (client.trust) if password specified using -ctspwd.