1 Introduction to Oracle Key Vault RESTful Services

The Oracle Key Vault RESTful services utility commands enable you to perform many Oracle Key Vault tasks, such as managing endpoints or performing backups, at the command line.

• About Oracle Key Vault RESTful Services
  The Oracle Key Vault tasks that you can automate using RESTful services include the management of endpoints, wallets, security objects, deployment operations, and backup operations.
• General Process for Using Oracle Key Vault RESTful Services
  After you enable the RESTful services, in some cases, you will use JSON to perform the Oracle Key Vault RESTful services tasks.
• Required Privileges for Using RESTful Services
  The required RESTful services privileges are consistent with the privileges required to perform the same task in the Oracle Key Vault management console.

1.1 About Oracle Key Vault RESTful Services

The Oracle Key Vault tasks that you can automate using RESTful services include the management of endpoints, wallets, security objects, deployment operations, and backup operations.

Though the Oracle Key Vault management console user interface is sufficient for managing these features, the process of completing these tasks is a manual one, with Oracle Key Vault administrators having to click through the user interface. A large distributed enterprise deployment often requires automation through scripting to enable mass deployment. The Oracle Key Vault RESTful services utility commands enable you perform all of these tasks in a way that facilitates faster deployment with less human intervention.

With Oracle Key Vault RESTful services, you can run a single service command from the command line. For most of the Oracle Key Vault RESTful services utility commands, you can specify command line options as a JavaScript Object Notation (JSON) input file. The reference sections in this guide provide examples of generating and modifying JSON input template for each command. The output of the RESTful services utility commands is in JSON format. To run the service commands from the command line, you will need to set certain configuration parameters. You can simplify the execution of RESTful services utility commands by having these commonly used parameters in the RESTful services configuration file. These parameters cover areas that are universal, such as the name of the RESTful administrator who needs to run the command. Oracle Key Vault also provides a logging properties file to customize how logging is handled. In order to run the RESTful service utility, the endpoint must have at minimum Java Runtime Environment version 1.7.0.21 installed.

After you use RESTful services to perform Oracle Key Vault tasks, you should disable the RESTful services to minimize the number of entry points to Oracle Key Vault.

1.2 General Process for Using Oracle Key Vault RESTful Services

After you enable the RESTful services, in some cases, you will use JSON to perform the Oracle Key Vault RESTful services tasks.

To configure the Oracle Key Vault RESTful services, you will follow these general steps:

1. Enable RESTful services from the Oracle Key Vault management console.

   This step entails ensuring that the endpoint meets the system requirements, and then using the Oracle Key Vault management console to enable the network services and the RESTful services functionality.

2. Download the RESTful service utility okvrestclipackage.zip.

   This file contains an okvrestcli.jar file, the RESTful services command line utility script, a configuration file, and the default logging file.

3. Customize the following configuration and logging files to work with your environment:
   • okvrestcli.ini contains properties that are specific to your environment, such as the name of the user who will run the RESTful services utility commands.
   • okvrestcli_logging.properties determines how logging is handled.

After the Oracle Key Vault RESTful services have been configured, you can begin to use the RESTful services utility commands right away. You can run the commands individually, using different methods. In most cases, the RESTful services utility commands support JSON formatting.

1.3 Required Privileges for Using RESTful Services

The required RESTful services privileges are consistent with the privileges required to perform the same task in the Oracle Key Vault management console.

Based on the activity that you want to perform, the required privileges are as follows:

• Creating endpoints: System Administrator role or the Create Endpoint system privilege
• Managing endpoints: System Administrator role or the Manage Endpoint object privilege for the endpoint
• Creating endpoint groups: Key Administrator role or the Create Endpoint Group system privilege
• Managing endpoint groups: Key Administrator role or the Manage Endpoint Group object privilege for the endpoint group
• Managing wallets and keys: Key Administrator role or wallet privileges

  There are three modes for wallet privileges:

  • Read-only access (RO)
  • Read-and-modify access (RM)
  • Manage-wallet access (MW)

  You can grant wallet privileges in any of the following combinations:

  • RO
  • RM
  • RO_MW
  • RM_MW

  For example, if an endpoint is assigned only read-only (RO) and read-and-modify (RM) wallet access, then you cannot use the okv managed-object wallet add-member on the endpoint because this command requires manage-wallet access (RM_MW).

• Managing security objects: Key Administrator role
• Executing commands to check the status of and information about clusters or primary-standby deployments: System Administrator role
• Managing Backup and Restore: System Administrator Role

To simplify administration tasks, you can create a user who has one or more of these roles. Typically, this user is an administrator who must self-register their databases with Oracle Key Vault by using scripts that will need to perform the actions that need these privileges.

You do not need to have endpoint administrator privileges to use the Oracle Key Vault RESTful services.