Using the Proxy in a Secure kvstore

Starting up the Proxy

The Oracle NoSQL Database Proxy can be started on a secure kvstore using the following steps.

A secure proxy connection should be bootstrapped. Before you start up the proxy, you need to create a bootstrap user in the secure kvstore for the proxy to bootstrap its security connection. In SQL shell, the following command will create a bootstrap user for the proxy. See Developers Guide for getting started with SQL commands.
```
sql-> CREATE USER <proxy_user> IDENTIFIED BY "<proxy_password>";
```
where,
- proxy_user is the user name.
- proxy_password is the password for the proxy_user.
Note:

The default privilege is sufficient for a bootstrap user. It is not recommended to grant admin privilege or any other additional privileges to the bootstrap user.

Note:

Any user-supplied name can be given for the bootstrap user.
Create a directory ./proxy where the proxy related files can be stored.
Create a login file ./proxy/proxy.login for the bootstrap user with the following information in it.
```
oracle.kv.auth.username=<proxy_user>
oracle.kv.auth.pwdfile.file=proxy.passwd
oracle.kv.transport=ssl
oracle.kv.ssl.trustStore=client.trust
```
where,
- proxy.passwd is the file to store the password value of the proxy_user user.
- client.trust is the certificate trust file obtained from the kvstore deployment.
See Configuring Security with Remote Access to know how to generate the proxy.passwd and client.trust files in kvstore client machine. In this case, the proxy runs as a kvstore client. These files must exist in order for the proxy.login to work properly.
Create a certificate.pem file and key-pkcs8.pem file for the proxy and driver to configure and establish a secure communication. If the Java driver is used, the driver.trust file should also be generated. See Generating Certificate and Private Key for the Oracle NoSQL Database Proxy in the Security Guide.
Use the following command to start up the proxy for a secure kvstore:
```
java -jar lib/httpproxy.jar \ 
-storeName <kvstore_name> \ 
-helperHosts <kvstore_helper_host> \ 
[-hostname <proxy_host>] \ 
[-httpsPort <proxy_https_port>] \ 
-storeSecurityFile proxy/proxy.login \ 
-sslCertificate certificate.pem \ 
-sslPrivateKey key-pkcs8.pem \ 
-sslPrivateKeyPass <privatekey_password> \ 
[-verbose true]
```
where,
- kvstore_name is the kvstore's store name obtained from the kvstore deployment. See ping.
- kvstore_helper_host is the kvstore's helper host:port list obtained from the kvstore deployment. See Obtaining a KVStore Handle in the Java Direct Driver Developer's Guide.
- proxy_host is the hostname of the machine to host the proxy service. If the proxy is to be accessed from machines other than the one on which it is started this should be the hostname of the machine running the proxy. This parameter is optional and defaults to localhost which means that the proxy will only be available from the machine running the proxy.
- proxy_https_port is the port on which the proxy is watching for requests on its host machine. This is an optional parameter and defaults to 443.
  
  Note:
  Use of port 80 may require additional privileges, depending on your machine.
- proxy.login is the security login file generated in the earlier step for accessing the secure kvstore.
- certificate.pem is the certificate file generated in the previous step.
- key-pkcs8.pem is the private key file generated in the previous step.
- privatekey_password is the password for the encrypted key-pkcs8.pem file.
Note:
The proxy start-up only accepts private key file in PKCS#8 format. If your private key is already in PKCS#8 (start with -----BEGIN ENCRYPTED PRIVATE KEY----- or -----BEGIN PRIVATE KEY-----), you don't need any additional conversion. Otherwise, you can use OpenSSL to do the conversion.

Connect to the Proxy using Java Driver

The Oracle NoSQL Database Java Driver contains the jar files that enables an application to communicate with the Oracle NoSQL Database Proxy. You can connect to the proxy using the following steps.

Create a user for the driver which is used by the application to access the kvstore through the proxy.
```
sql-> CREATE USER <driver_user> IDENTIFIED BY "<driver_password>"
    sql-> GRANT READWRITE TO USER <driver_user>
```
where, the driver_user is the username and driver_password is the password for the driver_user user. In this example, the user driver_user is granted readwrite role, which allows the application to perform only read and write operation. See Configuring Authorization in the Security Guide.
Note:
If the user needs to create, drop, or alter tables or indexes, the driver_user should be granted dbadmin role, which allows the application to perform DDL operations.
```
sql-> GRANT DBADMIN TO USER <driver_user>
```
Install the Oracle NoSQL Database Java Driver in the application's classpath and use the following code to connect to the proxy.
```
String endpoint = "https://<proxy_host>:<proxy_https_port>";
StoreAccessTokenProvider atProvider = 
    new StoreAccessTokenProvider("<driver_user>","<driver_password>".toCharArray());
NoSQLHandleConfig config = new NoSQLHandleConfig(endpoint);
config.setAuthorizationProvider(atProvider);
NoSQLHandle handle = NoSQLHandleFactory.createNoSQLHandle(config);
```
where,
- proxy_host is the hostname of the machine to host the proxy service. This should match the proxy host you configured earlier.
- proxy_https_port is the port on which the proxy is watching for requests on its host machine. This should match the proxy https port configured earlier.
- driver_user is the driver username. This should match the user created in the previous step.
- driver_password is the password of the driver user.
Start-up the application program and set the driver.trust file's path to the Java trust store by using the following command. This is required as the proxy is already set up using the certificate.pem and key-pkcs8.pem files.
```
java -Djavax.net.ssl.trustStore=driver.trust \
-javax.net.ssl.trustStorePassword=<password of driver.trust> \
-cp .:lib/nosqldriver.jar application_program
```
The driver.trust contains the certificate.pem or rootCA.crt certificate. If the certificate certificate.pem is in a chain signed by a trusted CA that is listed in JAVA_HOME/jre/lib/security/cacerts, then you don't need to append Java environment parameter -Djavax.net.ssl.trustStore in the Java command.

Connect to the Proxy using Python

The Oracle NoSQL Database Python Driver contains the files that enable a Python application to communicate with the proxy.

See Connect to the Proxy Using Python for more information.

Connect to the Proxy using Go

The Oracle NoSQL Database Go SDK contains the files that enable a Go application to communicate with the proxy.

See Connect to the Proxy using Go for more information.

Connect to the Proxy using Node.js

The Oracle NoSQL Database Node.js SDK contains the files that enable a Node.js application to communicate with the proxy.

See Connect to the Proxy using Node.js for more information.

Connect to the Proxy using .NET

The Oracle NoSQL Database .NET SDK contains the files that enable a .NET application to communicate with the proxy.

See Connect to the Proxy using .NET for more information.

Connect to the Proxy using Spring Data

The Oracle NoSQL Database Spring Data SDK contains the files that enable a Spring Data application to communicate with the proxy.

Install the Java driver in the application's classpath. Use the following code to connect to the proxy.

The configuration Spring bean provides a NosqlDbConfig object. You can use the StoreAccessTokenProvider class with the username and password of the Oracle NoSQL Database cluster. The StoreAccessTokenProvider class configures the Spring Data Framework to connect and authenticate to a secure Oracle NoSQL Database store.


import com.oracle.nosql.spring.data.config.AbstractNosqlConfiguration;
import com.oracle.nosql.spring.data.config.NosqlDbConfig;
import com.oracle.nosql.spring.data.repository.config.EnableNosqlRepositories;
 
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
 
import oracle.nosql.driver.kv.StoreAccessTokenProvider;
 
@Configuration
 
@EnableNosqlRepositories
 
public class AppConfig extends AbstractNosqlConfiguration {
    @Bean
    public NosqlDbConfig nosqlDbConfig() {
        AuthorizationProvider authorizationProvider;
        authorizationProvider = new StoreAccessTokenProvider(user, password);
        return new NosqlDbConfig("http://<proxy_host:proxy_http_port>", authorizationProvider);
    }
}

where,

proxy_host is the hostname of the machine to host the proxy service.
proxy_http_port is the port on which the proxy is watching for requests on its host machine.

Example

Run the Oracle NoSQL Database Java Driver and connect to the proxy using the following steps. In this example, we will deploy a secure one-node Oracle NoSQL Database server on the same host as the proxy. This example will start a proxy instance on the local machine called myhostusing HTTPS port 443. It will connect to a secure Oracle NoSQL Database instance name kvstore that is running on 2 hosts, kvhost1 and kvhost2, both on port 5000. In order to perform the administrative steps required to create users and assign privilege you must have access to an identity with administrative privilege. In this example, the identity with administrative privilges is provided in the file KVROOT/security.

Create a proxy_user user using the following command in the Oracle NoSQL Database SQL shell.

java -jar lib/sql.jar \ 
-helper-hosts kvhost1:5000,kvhost2:5000 -store kvstore \ 
-security kvroot/security/user.security

sql-> CREATE USER proxy_user IDENTIFIED BY "ProxyPass@@123";

exit

Create a directory ./proxy where the proxy related files can be stored.
Create a ./proxy/proxy.passwd file and set the proxy password for user proxy in the proxy.passwd file. In this example, the proxy is in the same machine as kvstore. So, we create the files related to proxy in the ./proxy directory.
```
java -jar lib/kvstore.jar securityconfig pwdfile create -file proxy/proxy.passwd
java -jar lib/kvstore.jar securityconfig pwdfile secret -file proxy/proxy.passwd -set -alias proxy_user -secret "ProxyPass@@123"
```
Copy the client.trust file from kvstore to the /proxy directory for the proxy to use it.
```
cp kvroot/security/client.trust proxy/client.trust
```

Create a login file proxy.login for the bootstrap user in the ./proxy directory with the following information in it.

oracle.kv.auth.username=proxy_user
oracle.kv.auth.pwdfile.file=proxy.passwd
oracle.kv.transport=ssl
oracle.kv.ssl.trustStore=client.trust

Generate a self-signed certificate and a private key.
```
openssl req -x509 -days 365 -newkey rsa:4096 \ 
-keyout key.pem -out certificate.pem \ 
-subj "/C=US/ST=CA/L=San/CN=localhost/emailAddress=localhost@oracle.com"

# The below conversion can be skipped if openssl by default generate PKCS#8 key.
openssl pkcs8 -topk8 \ 
-inform PEM -outform PEM \
-in key.pem -out key-pkcs8.pem
```
Note:
Provide 123456 for all the password prompts.

Note:
Provide the hostname of the machine for the parameter CN if you are not running in localhost.
Note:
The below conversion should be done if your key is encrypted with the PKCS#5 v2.0 algorithm. Otherwise, you might encounter IllegalArgumentException exception that indicates the file does not contain a valid private key due to the unsupported algorithm. The encryption algorithm can be converted via OpenSSL pkcs8 utility by specifying PKCS#5 v1.5 or PKCS#12 algorithms with -v1 flag. The following command converts the encryption algorithm of a key to PBE-SHA1-3DES.
```
openssl pkcs8 -topk8 -in <PKCS#5v2.0_key_file> -out <new_key_file> -v1 PBE-SHA1-3DES
```

Import the certificate into the Java trust store.

keytool -import -alias example \ 
-keystore driver.trust -file certificate.pem

Start the proxy on the local machine, myhost, using 443 as the httpsPort

java -jar lib/httpproxy.jar \ 
-storeName kvstore \ 
-helperHosts kvhost1:5000,kvhost2:5000 \ 
-httpsPort 443  \ 
-storeSecurityFile proxy/proxy.login \ 
-sslCertificate certificate.pem \ 
-sslPrivateKey key-pkcs8.pem \ 
-sslPrivateKeyPass 123456 \ 
-verbose true

Create a driver_user user. In this example, the driver_user is granted readwrite role, which allows the application to perform only read and write operations. To run table DDLs like CREATE TABLE, the driver_user should be granted more roles. See Configuring Authorization in the Security Guide.
```
java -jar lib/sql.jar \ 
-helper-hosts kvhost1:5000,kvhost2:5000 -store kvstore \ 
-security kvroot/security/user.security

sql-> CREATE USER driver_user IDENTIFIED BY "DriverPass@@123";
sql-> GRANT READWRITE TO USER driver_user;

exit
```

In the application program, run the following code to connect to the proxy. Add JVM parameter -Djavax.net.ssl.trustStore=driver.trust when starting up the example program.

String endpoint = "https://localhost:8089";
StoreAccessTokenProvider atProvider = 
    new StoreAccessTokenProvider("driver_user","DriverPass@@123".toCharArray());

NoSQLHandleConfig config = new NoSQLHandleConfig(endpoint);
config.setAuthorizationProvider(atProvider);

NoSQLHandle handle = NoSQLHandleFactory.createNoSQLHandle(config);

See Oracle NoSQL Database Drivers to add CRUD operations for the example as needed.