Previous Next JavaScript must be enabled to correctly display this content

## 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:

1. 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 $KVHOST -harange 5010,5020 \
       -store-security configure -pwdmgr pwdfile -capacity 1

2. 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:

3. 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.

4. 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 the data store. 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.

5. Start `runadmin` in security mode on the data store server host ($KVHOST). To do this, use the following command:

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

6. Use the `configure -name` command to specify the name of the data store that you want to configure:

       kv-> configure -name mystore
       Store configured: mystore

   After naming the data store, you can create at least one zone.

       kv-> plan deploy-zone -name zone_name -rf 1 -type primary -wait

   Every data store 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.

7. 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-> execute 'CREATE USER root IDENTIFIED BY \"password\" ADMIN
       Statement completed successfully

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

8. 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.

9. 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.txt
       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
       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:

1. Shut down the KVStore instance:

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

2. Run the `securityconfig` utility to set up the basic store configuration with security:

       java -Xmx64m -Xms64m \
       -jar KVHOME/lib/kvstore.jar securityconfig

3. 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:

4. 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.

5. 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.

6. 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 &

7. 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.

8. 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-> execute 'CREATE USER root IDENTIFIED BY \"password\" ADMIN
       Statement completed successfully

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

9. 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.

10. 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
        oracle.kv.ssl.hostnameVerifier=dnmatch(CN\=NoSQL)

    For more information, see User Login.