Single Node Secure Deployment

The following examples describe how to add security to a new or an existing Oracle NoSQL Database single host deployment.

Adding Security to a New Installation

To install Oracle NoSQL Database securely:

Run the makebootconfig utility with the -store-security option to set up the basic store configuration with security:

java -Xmx64m -Xms64m \
-jar KVHOME/lib/kvstore.jar makebootconfig \
-root KVROOT -port 5000 \
-host node01 -harange 5010,5020 \
-store-security configure -pwdmgr pwdfile -capacity 1

In this example, -store-security configure is used, so the security configuration utility is run as part of the makebootconfig process and you are prompted for a password to use for your keystore file:
```
Enter a password for the Java KeyStore: 
```
Enter a password for your store and then reenter it for verification. In this case, the password file is used, and the securityconfig tool will automatically generate the following security related files:
```
Enter a password for the Java KeyStore: ***********
Re-enter the KeyStore password for verification: ***********
Created files:
security/client.trust
security/client.security
security/store.keys
security/store.trust
security/store.passwd
security/security.xml 
```
Note:

In a multi-host store environment, the security directory and all files contained in it should be copied to each server that will host a Storage Node.
Start the Storage Node Agent (SNA):

Note:

Before starting the SNA, set the environment variable MALLOC_ARENA_MAX to 1. Setting MALLOC_ARENA_MAX to 1 ensures that the memory usage is restricted to the specified heap size.
```
nohup java -Xmx64m -Xms64m \
-jar KVHOME/lib/kvstore.jar start -root KVROOT&
```
When a newly created store with a secure configuration is first started, there are no user definitions available against which to authenticate access. In order to reduce risk of unauthorized access, an admin will only allow you to connect to it from the host on which it is running. This security measure is not a complete safeguard against unauthorized access. It is important that you do not provide local access to machines running KVStore. In addition, you should perform steps 5, 6 and 7 soon after this step in order to minimize the time period in which the admin might be accessible without full authentication. For more information on maintaining a secure store see Guidelines for Securing the Configuration.

Start runadmin in security mode on the KVStore server host (node01). To do this, use the following command:

java -Xmx64m -Xms64m \
-jar KVHOME/lib/kvstore.jar \
runadmin -port 5000 -host node01 \
-security KVROOT/security/client.security
Logged in admin as anonymous

Use the configure -name command to specify the name of the KVStore that you want to configure:
```
kv-> configure -name mystore
Store configured: mystore 
```
After naming the KVStore, you can create at least one zone.
```
kv-> plan deploy-zone -name zone_name -rf 1 -type primary -wait
```
Every KVStore has an administration database. You must deploy the Storage Node first and then deploy an Administration process on the same node to continue configuring the database.
When you deploy the node, provide the zone ID, the node's network name, and its registry port number.
```
kv-> plan deploy-sn -znname zone_name -host hostname -port 5000 -wait
```
Having deployed the node, create the Admin process on the node that you just deployed, using the deploy-admin command. This command requires the Storage Node ID and an optional plan name.

Note:
Note: You can obtain the Storage Node ID using the show topology command. See show topology for more details.
```
kv-> plan deploy-admin -sn sn1 -wait
```
The final step in your configuration process is to create Replication Nodes on every node in your store. You do this using the topology create and plan deploy-topology commands.
```
kv-> topology create -name storeTopo -pool AllStorageNodes -partitions 150
kv-> plan deploy-topology -name storeTopo -wait
```
Your store is fully installed and configured.
Create an admin user. The password should comply with the security policies described in Password Complexity Policies. In this case, user root is defined:
```
kv-> plan create-user -name root -admin -wait
Enter the new password: ********
Re-enter the new password: ********
Executed plan 6, waiting for completion...
Plan 6 ended successfully  
```
For more information on user creation and administration, see User Management.

Create a new password file to store the credentials needed to allow clients to login as the admin user (root):

java -Xmx64m -Xms64m \
-jar KVHOME/lib/kvstore.jar securityconfig \
pwdfile create -file KVROOT/security/login.passwd
java -Xmx64m -Xms64m \
-jar KVHOME/lib/kvstore.jar securityconfig pwdfile secret \
-file KVROOT/security/login.passwd -set -alias root
Enter the secret value to store: ********
Re-enter the secret value for verification: ********
Secret created

Note:

The password must match the one set for the admin in the previous step.

For more information on user creation and administration, see User Management.

At this point, it is possible to connect to the store as the root user. To login, you can use either the -username <user> runadmin argument or specify the "oracle.kv.auth.username" property in the security file.

In this example, a security file (mylogin.txt) is used. To login, use the following command:
```
java -Xmx64m -Xms64m \
-jar KVHOME/lib/kvstore.jar runadmin -port 5000 \
-host localhost -security mylogin
Logged in admin as root 
```
The file mylogin.txt should be a copy of the client.security file with additional properties settings for authentication. The file would then contain content like this:
```
oracle.kv.auth.username=root
oracle.kv.auth.pwdfile.file=KVROOT/security/login.passwd
oracle.kv.transport=ssl
oracle.kv.ssl.trustStore=KVROOT/security/client.trust
oracle.kv.ssl.protocols=TLSv1.2,TLSv1.1,TLSv1
oracle.kv.ssl.hostnameVerifier=dnmatch(CN\=NoSQL) 
```
Note that the hostname verifier provides a way for Oracle NoSQL Database clients to specify the name that they expect the Oracle NoSQL Database server hosts to use during SSL handshake (when they attempt to connect server using SSL/TLS).

For a secure store using the standard configuration, server hosts will be required to authenticate themselves, and clients will use their SSL truststore to confirm that the server authenticates with a trusted identity. The hostname verifier provides the additional assurance that the server host authenticates using the expected identity, not just any trusted identity.

This additional check is desirable if either the truststore contains multiple certificates or if the certificate it contains is a CA certificate rather than a self-signed or leaf certificate. In both those cases, the truststore can vouch for multiple identities. The host verifier allows the user to specify the specific identity that is expected.

The only hostname verifier currently supported is the dnmatch verifier, which must be specified in the form of dnmatch(distinguished-name), where distinguished name must be the NoSQL DB server certificate's distinguished name. If you are using the default security configuration, then the hostname verifier in the example specifies that the server should authenticate with a certificate whose distinguished name is CN=NoSQL. This is the name used in the server certificates that the system generates by default.

The verification is performed by checking if the distinguished name of server certificate match the specified dnmatch expressions, which uses regular expressions as specified by java.util.regex.Pattern. The distinguished name specified in dnmatch must be 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. 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. See User Login.

Adding Security to an Existing Installation

To add security to an existing Oracle NoSQL Database installation:

Shut down the KVStore instance:

java -Xmx64m -Xms64m \
-jar KVHOME/lib/kvstore.jar stop \
-root KVROOT

Run the securityconfig utility to set up the basic store configuration with security:
```
java -Xmx64m -Xms64m \
-jar KVHOME/lib/kvstore.jar securityconfig
```
Use the config create command with the -pwdmgr option to specify the mechanism used to hold passwords that is needed for accessing the stores. In this case, Oracle Wallet is used. Oracle Wallet is only available in the Oracle NoSQL Database EE version. CE deployments should use the pwdfile option instead.
```
config create -pwdmgr wallet -root KVROOT
Enter a password for the Java KeyStore: 
```
Enter a password for your store and then reenter it for verification. The configuration tool will automatically generate some security related files:
```
Enter a password for the Java KeyStore: ***********
Re-enter the KeyStore password for verification: ***********
Created files:
security/security.xml
security/store.keys
security/store.trust
security/store.wallet/cwallet.sso
security/client.security
security/client.trust  
```
Note:

In a multi-host store environment, the security directory and all files contained in it should be copied to each server that will host a Storage Node.
Use the config add-security command to add the security configuration you just created:
```
security-> config add-security -root KVROOT
-secdir security  -config config.xml
Configuration updated. 
```
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.
Start the Storage Node Agent (SNA):

Note:

Before starting the SNA, set the environment variable MALLOC_ARENA_MAX to 1. Setting MALLOC_ARENA_MAX to 1 ensures that the memory usage is restricted to the specified heap size.
```
nohup java -Xmx64m -Xms64m \
-jar KVHOME/lib/kvstore.jar start -root KVROOT &
```
Start runadmin in security mode on the KVStore server host (node01). To do this, use the following command:
```
java -Xmx64m -Xms64m \
-jar KVHOME/lib/kvstore.jar \
runadmin -port 5000 -host node01 \
-security KVROOT/security/client.security
Logged in admin as anonymous.
```
This command sets SSL as a connection method and names a copy of the generated truststore file (client.security). For more information on SSL properties, see SSL communication properties.
Create an admin user. The password should comply with the security policies described in Password Complexity Policies. In this case, user root is defined:
```
kv-> plan create-user -name root -admin -wait
Enter the new password: ********
Re-enter the new password: ********
Executed plan 8, waiting for completion...
Plan 8 ended successfully 
```
For more information on user creation and administration, see User Management.

Create a new wallet file to store the credentials needed to allow clients to login as the admin user (root):

java -Xmx64m -Xms64m \
-jar KVHOME/lib/kvstore.jar securityconfig \
wallet create -dir KVROOT/security/login.wallet
java -Xmx64m -Xms64m \
-jar KVHOME/lib/kvstore.jar securityconfig wallet secret \
-dir KVROOT/security/login.wallet -set -alias root
Enter the secret value to store: ********
Re-enter the secret value for verification: ********
Secret created

Note:

The password must match the one set for the admin in the previous step.

For more information on user creation and administration, see User Management.

At this point, it is possible to connect to the store as the root user. To login, you can use either the -username <user> runadmin argument or specify the "oracle.kv.auth.username" property in the security file.

In this example, the oracle.kv.security property is used. To login use the following command:
```
java -Xmx64m -Xms64m \
-Doracle.kv.security=mylogin \
-jar KVHOME/lib/kvstore.jar runadmin -port 5000 -host localhost
Logged in admin as root
```
The file mylogin.txt should be a copy of the client.security file with additional properties settings for authentication. The file would then contain content like this:
```
oracle.kv.auth.username=root
oracle.kv.auth.wallet.dir=KVROOT/security/login.wallet
oracle.kv.transport=ssl
oracle.kv.ssl.trustStore=KVROOT/security/client.trust
oracle.kv.ssl.protocols=TLSv1.2,TLSv1.1,TLSv1
oracle.kv.ssl.hostnameVerifier=dnmatch(CN\=NoSQL) 
```
For more information, see User Login.