1. RESTful Services Administrator's Guide
  2. Administration Commands

3 Administration Commands

You can use the administration commands to manage client wallets and endpoints.

  • Client Wallet Management Commands
    You can use the client wallet management commands to manage client wallets that store user credentials. The client wallet management commands support LDAP and database users only.
  • Endpoint Management Commands
    The endpoint management commands enable you to perform endpoint-related tasks such as creating or provisioning endpoints.

3.1 Client Wallet Management Commands

You can use the client wallet management commands to manage client wallets that store user credentials. The client wallet management commands support LDAP and database users only.

Parent topic: Administration Commands

3.1.1 okv admin client-wallet add Command

The okv admin client-wallet add command adds the user's credentials to the client wallet. Oracle Key Vault creates the client wallets ewallet.p12 and cwallet.sso if they do not exist.

Required Authorization

None

Syntax

okv admin client-wallet add --client-wallet client_wallet_location --wallet-user user_name

JSON Input File Template

{
  "service" : {
    "category" : "admin",
    "resource" : "client-wallet",
    "action" : "add",
    "options" : {
      "clientWallet" : "#VALUE",
      "walletUser" : "#VALUE"
    }
  }
}

Parameters

Parameter/Template Parameter Required? Description

--client-wallet / clientWallet

Required

Location of the client wallet (that is, the directory where client wallet is created)

--wallet-user / walletUser

Required

User name

JSON Example

  1. Generate JSON input for the okv admin client-wallet add command. 
    okv admin client-wallet add --generate-json-input

    The generated input appears as follows: 

    {
  "service" : {
    "category" : "admin",
    "resource" : "client-wallet",
    "action" : "add",
    "options" : {
      "clientWallet" : "#VALUE",
      "walletUser" : "#VALUE"
    }
  }
}
  2. Save the generated input to a file (for example, client_wallet_add.json) and then edit it so that you can specify the client wallet location and the user whose password you want to add to the wallet.
    {
  "service" : {
    "category" : "admin",
    "resource" : "client-wallet",
    "action" : "add",
    "options" : {
      "clientWallet" : "/home/oracle/okv_client_wallet",
      "walletUser" : "psmith"
    }
  }
}
  3. Run the okv admin client-wallet add command using the generated JSON file. 
    okv admin client-wallet add --from-json client_wallet_add.json

    When prompted, enter the password for the user. After you enter the password, output similar to the following appears:

    Password: password
{
  "result" : "Success"
}

Note:

Prior to Oracle Key Vault release 21.7, when the client wallet file does not have write permission to the user, 'okv admin client-wallet add' gives the success message even though it did not add the user to the wallet client file. Starting with Oracle Key Vault release 21.7, RESTful Services Utility commands reports the permission issue with an error message

Parent topic: Client Wallet Management Commands

3.1.2 okv admin client-wallet delete Command

The okv admin client-wallet delete command deletes a user's credentials from a client wallet.

Required Authorization

Read-write permissions on the client wallet

Syntax

okv admin client-wallet delete --client-wallet <client_wallet_location> --wallet-user <wallet_user_name>

JSON Input File Template

{
  "service" : {
    "category" : "admin",
    "resource" : "client-wallet",
    "action" : "delete",
    "options" : {
      "clientWallet" : "#VALUE",
      "walletUser" : "#VALUE"
    }
  }
}

Parameters

Parameter/Template Parameter Required? Description

--client-wallet / clientWallet

Required

Location of the client wallet (that is, the directory where client wallet is created)

--wallet-user / walletUser

Required

User name

JSON Example

  1. Generate JSON input for the okv admin client-wallet delete command. 
    okv admin client-wallet delete --generate-json-input

    The generated input appears as follows: 

    {
  "service" : {
    "category" : "admin",
    "resource" : "client-wallet",
    "action" : "delete",
    "options" : {
      "clientWallet" : "#VALUE",
      "walletUser" : "#VALUE"
    }
  }
}
  2. Save the generated input to a file (for example, client_wallet_delete.json) and then edit it so that you can specify the name of the user to remove from the wallet and the client wallet location.
    {
  "service" : {
    "category" : "admin",
    "resource" : "client-wallet",
    "action" : "delete",
    "options" : {
      "clientWallet" : "/home/oracle/okv_client_wallet",
      "walletUser" : "psmith"
    }
  }
}
  3. Run the okv admin client-wallet delete command using the generated JSON file. 
    okv admin client-wallet delete --from-json client_wallet_delete.json

    Output similar to the following appears: 

    {
  "result" : "Success"
}

Parent topic: Client Wallet Management Commands

3.1.3 okv admin client-wallet list Command

The okv admin client-wallet list command lists the users whose credentials are stored in the client wallet.

Required Authorization

Read file permissions on the client wallet

Syntax

okv admin client-wallet list --client-wallet client_wallet_location

JSON Input File Template

{
  "service" : {
    "category" : "admin",
    "resource" : "client-wallet",
    "action" : "list",
    "options" : {
      "clientWallet" : "#VALUE"
    }
  }
}

Parameters

Parameter/Template Parameter Required? Description

--client-wallet / clientWallet

Required

Location of the client wallet (that is, the directory where client wallet is created)

JSON Example

  1. Generate JSON input for the okv admin client-wallet list command. 
    okv admin client-wallet list --generate-json-input

    The generated input appears as follows: 

    {
  "service" : {
    "category" : "admin",
    "resource" : "client-wallet",
    "action" : "list",
    "options" : {
      "clientWallet" : "#VALUE"
    }
  }
}
  2. Save the generated input to a file (for example, client_wallet_list.json) and then modify it to include the client wallet location. 
    {
  "service" : {
    "category" : "admin",
    "resource" : "client-wallet",
    "action" : "list",
    "options" : {
      "clientWallet" : "/home/oracle/okv_client_wallet"
    }
  }
}
  3. Run the okv admin client-wallet list command using the generated JSON file. 
    okv admin client-wallet list --from-json client_wallet_list.json

    Output similar to the following appears: 

    {
  "result" : "Success",
  "value" : {
    "walletUsers" : [ "psmith", "psmith" ]
  }
}

Parent topic: Client Wallet Management Commands

3.1.4 okv admin client-wallet update Command

The okv admin client-wallet update command updates the user's password in the client wallet.

Required Authorization

Read-write file permissions on the wallet

Syntax

okv admin client-wallet update --client-wallet client_wallet_location --wallet-user user_name

JSON Input File Template

{
  "service" : {
    "category" : "admin",
    "resource" : "client-wallet",
    "action" : "update",
    "options" : {
      "clientWallet" : "#VALUE",
      "walletUser" : "#VALUE"
    }
  }
}

Parameters

Parameter Required? Description

--client-wallet / clientWallet

Required

Location of the client wallet (that is, the directory where client wallet is created)

--wallet-user / walletUser

Required

User name

JSON Example

  1. Generate JSON input for the okv admin client-wallet update command. 
    okv admin client-wallet update --generate-json-input

    The generated input appears as follows: 

    {
  "service" : {
    "category" : "admin",
    "resource" : "client-wallet",
    "action" : "update",
    "options" : {
      "clientWallet" : "#VALUE",
      "walletUser" : "#VALUE"
    }
  }
}
  2. Save the generated input to a file (for example, client_wallet_update.json) and then edit it so that you can specify the user whose password you want to update to the wallet and the client wallet location.
    {
  "service" : {
    "category" : "admin",
    "resource" : "client-wallet",
    "action" : "update",
    "options" : {
      "clientWallet" : "/home/oracle/okv_client_wallet",
      "walletUser" : "psmith"
    }
  }
}
  3. Run the okv admin client-wallet update command using the generated JSON file. 
    okv admin client-wallet update --from-json client_wallet_update.json

    When prompted, enter the password for the user. After you enter the password, output similar to the following appears:

    Password: password
{
  "result" : "Success"
}

Related Topics

Parent topic: Client Wallet Management Commands

3.2 Endpoint Management Commands

The endpoint management commands enable you to perform endpoint-related tasks such as creating or provisioning endpoints.

Parent topic: Administration Commands

3.2.1 okv admin endpoint check-status Command

The okv admin endpoint check-status command displays the current state of an endpoint. The state will be either ACTIVE or PENDING.

This command is meant primarily for multi-master cluster environments. However, it is still valid for other deployments and can be used to check the existence of an endpoint.

Required Authorization

System Administrator role or the Manage Endpoint object privilege for the endpoint

Syntax

okv admin endpoint check-status --endpoint endpoint_name|--locator-id UUID

JSON Input File Template

{
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "check-status",
    "options" : {
      "endpoint" : "#VALUE",
      "locatorID" : "#VALUE"
    }
  }
}

Parameters

Parameter/Template Parameter Required? Description

--endpoint / endpoint or --locator-id / locatorID

Optional

The name of the endpoint or the locator ID (universally unique ID (UUID)) of the endpoint that you want to check. The --locator-id / locatorID is required only if you are using a multi-master cluster environment.

You must specify either the --endpoint / endpoint value or the --locator-id / locatorID value, not both.

To find existing endpoints, run the okv admin endpoint list command.

To find the locator ID, check the output of the okv admin endpoint create command that was used to create this endpoint.

JSON Example

  1. Generate a JSON input template for the okv admin endpoint check-status command. 
    okv admin endpoint check-status --generate-json-input

    The generated input appears as follows:

    {
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "check-status",
    "options" : {
      "endpoint" : "#VALUE",
      "locatorID" : "#VALUE"
    }
  }
}
  2. Save the generated input to a file (for example, check-status_ep.json) and then edit it to so that you can check the endpoint. Specify either the endpoint value or the locatorID value, but not both. 
    {
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "check-status",
    "options" : {
      "locatorID" : "1AC9B321-6540-4F2B-809B-95FD7416999E"
    }
  }
}
  3. Run the okv admin endpoint check-status command using the generated JSON file. 
    okv admin endpoint check-status --from-json check-status_ep.json

    Output similar to the following appears: 

    {
  "result" : "Success",
  "value" : {
    "status" : "ACTIVE",
    "endpoint" : "HR_DB_EP"
  }
}

    The output includes the name of the endpoint if the endpoint object is in ACTIVE state. The endpoint name shown here may be different from what was specified at the endpoint creation time. If the endpoints with the same name are created on multiple cluster nodes, then Oracle Key Vault performs naming conflict resolution and it renames all but one endpoints by appending _OKVnode-id to the endpoint name. For example, if you named the endpoint hr_db_ep, and there is a naming conflict, then the name could be hr_db_ep_okv01.

    On deployments other than multi-master cluster, this command returns Success if the endpoint exists and output does not include entries showing the endpoint name and its state.

Parent topic: Endpoint Management Commands

3.2.2 okv admin endpoint create Command

The okv admin endpoint create command adds a new endpoint to Oracle Key Vault.

After you add the endpoint, the endpoint will be in the Registered state.

Required Authorization

System Administrator role or the Create Endpoint system privilege

Syntax

okv admin endpoint create [--description <description>] [--email <email>] --endpoint <endpoint> [--platform <platform>] [--ssh-server-host-name <ssh-server-host-name>] [--strict-ip-check <strict-ip-check>] [--subgroup <subgroup>] [--type <type>] [--unique <unique>]

JSON Input File Template

{
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "create",
    "options" : {
      "endpoint" : "#VALUE",
      "description" : "#VALUE",
      "email" : "#VALUE",
      "platform" : "#LINUX64|SOLARIS64|SOLARIS_SPARC|HP-UX|AIX|WINDOWS",
      "type" : "#ORACLE_DB|ORACLE_NON_DB|ORACLE_ACFS|MYSQL_DB|SSH_SERVER|OTHER",
      "subgroup" : "#VALUE|NO SUBGROUP|USE CREATOR SUBGROUP",
      "strictIpCheck" : "#TRUE|FALSE",
      "unique" : "#TRUE|FALSE",
      "sshServerHostName" : "#VALUE"
    }
  }
}

Parameters

Parameter/Template Parameter Required? Description

--endpoint / endpoint

Required

The name of the endpoint that you want to add. See Naming Guidelines for Objects.

To find existing endpoints, run the okv admin endpoint list command.

--description / description

Optional

A user-friendly description of the endpoint. If the description contains spaces, then you must enclose it within double quotation marks.

--email / email

Optional

Email address of the endpoint administrator. Enclose this value in double quotation marks.

--platform / platform

Optional

The endpoint platform. Allowed values are:

  • AIX

  • HP-UX

  • LINUX64

  • SOLARIS64

  • SOLARIS_SPARC

  • WINDOWS

    The default value is:

  • LINUX64

--type / type

Optional

Type of the endpoint. Allowed values are:

  • MYSQL_DB

  • ORACLE_ACFS

  • ORACLE_DB

  • ORACLE_NON_DB

  • SSH_SERVER

  • OTHER

    The default value is:

  • ORACLE_DB

--subgroup / subgroup

Optional

For multi-master cluster environments, defines the affinity that an endpoint will have to a specific Oracle Key Vault cluster subgroup. Values are as follows:

  • Enter the name of a multi-master cluster subgroup. To find subgroups, in the Oracle Key Vault management console, select the Cluster tab, then Management in the left navigation bar. Subgroups for the cluster are listed under Cluster Information.
  • NO SUBGROUP creates an endpoint that will have no Oracle Key Vault cluster subgroup affinity.
  • USE CREATOR SUBGROUP creates an endpoint with affinity to the Oracle Key Vault cluster subgroup to which the node belongs where the endpoint is created.

--strict-ip-check / strictIpCheck

Optional

Controls whether the Oracle Key Vault server checks the incoming IP address for a given endpoint.

  • TRUE enables Oracle Key Vault to check the incoming IP address of an endpoint. If the IP address does not match with the one that was used when the client endpoint software was installed, then Oracle Key Vault does not allow the connection.
  • FALSE disables this check and allows the incoming connection for the endpoint to come from any IP address.

Note:

The default value is TRUE.

--unique / unique

Optional

In a multi-master cluster environment, creates the endpoint as a unique endpoint. In a multi-master cluster, it is possible that an endpoint with the same name could be created from two different nodes. If that happens, then endpoint names may conflict. The Oracle Key Vault conflict resolution scheme will keep one endpoint with the given name and rename other endpoints with the conflicting names to a name using this format: given_ep_name_OKVnode_id.

Valid settings are as follows:

  • TRUE appends _OKVnode_id to the given name and thus prevent the conflict for this endpoint name. The endpoint is immediately usable.
  • FALSE (default) causes Oracle Key Vault to begin a checking process to find if the endpoint name is unique. A unique ID is returned. You can use this ID to check the status of the endpoint creation, whether it is in progress (PENDING) or complete (ACTIVE). If the status is PENDING, then it is not yet usable, so any actions performed on the endpoint will fail. If the status is ACTIVE, then the endpoint is usable. To check the status, run the okv admin endpoint check_status command. If the name that you provided is already used in another node, then the name for this endpoint will have _OKVxx appended to it. For example, if you named the endpoint ep12, and there is a naming conflict, the name could be EP12_OKV01.
--ssh-server-host-name / sshServerHostName Optional

The hostname or IP address of the host where you want to deploy the SSH_SERVER endpoint. This option can only be used with the SSH_SERVER type endpoint..

JSON Example

  1. Generate JSON input for the okv admin endpoint create command. 
    okv admin endpoint create --generate-json-input

    The generated input appears as follows: 

    {
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "create",
    "options" : {
      "endpoint" : "#VALUE",
      "description" : "#VALUE",
      "email" : "#VALUE",
      "platform" : "#LINUX64|SOLARIS64|SOLARIS_SPARC|HP-UX|AIX|WINDOWS",
      "type" : "#ORACLE_DB|ORACLE_NON_DB|ORACLE_ACFS|MYSQL_DB|SSH_SERVER|OTHER",
      "subgroup" : "#VALUE|NO SUBGROUP|USE CREATOR SUBGROUP",
      "strictIpCheck" : "#TRUE|FALSE",
      "unique" : "#TRUE|FALSE",
      "sshServerHostName" : "#VALUE"
    }
  }
}
  2. Save the generated input to a file (for example, create_ep.json) and then edit it so that you can create the endpoint.
    {
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "create",
    "options" : {
      "endpoint" : "hr_db_ep",
      "description" : "HR database endpoint",
      "email" : "psmith@example.com",
      "platform" : "LINUX64",
      "type" : "ORACLE_DB",
      "subgroup" : "USE CREATOR SUBGROUP",
      "strictIpCheck" : "TRUE",
      "unique" : "FALSE"
    }
  }
}
  3. Run the okv admin endpoint create command using the generated JSON file. 
    okv admin endpoint create --from-json create_ep.json

    Output similar to the following appears: 

    {
  "result" : "Success",
  "value" : {
    "status" : "PENDING",
    "locatorID" : "1AC9B321-6540-4F2B-809B-95FD7416999E"
  }
}

    You can use the locatorID from above output with the okv admin endpoint check-status command to display the current state of the endpoint object. If the object status is ACTIVE, this command also displays the object name after the conflict-name resolution.

Parent topic: Endpoint Management Commands

3.2.3 okv admin endpoint delete Command

The okv admin endpoint delete command removes an endpoint from Oracle Key Vault.

Required Authorization

System Administrator role or the Manage Endpoint object privilege for the endpoint

Syntax

okv admin endpoint delete --endpoint endpoint_name

JSON Input File Template

{
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "delete",
    "options" : {
      "endpoint" : "#VALUE"
    }
  }
}

Parameters

Parameter/Template Parameter Required? Description

--endpoint / endpoint

Required

Name of the endpoint.

To find existing endpoints, run the okv admin endpoint list command.

JSON Example

  1. Generate JSON input for the okv admin endpoint delete command. 
    okv admin endpoint delete --generate-json-input

    The generated input appears as follows:

    {
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "delete",
    "options" : {
      "endpoint" : "#VALUE"
    }
  }
}
  2. Save the generated input to a file (for example, delete_ep.json) and then edit it so that you can delete the endpoint.
    {
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "delete",
    "options" : {
      "endpoint" : "hr_db_ep"
    }
  }
}
  3. Run the okv admin endpoint delete command using the generated JSON file. 
    okv admin endpoint delete --from-json delete_ep.json

    Output similar to the following appears: 

    {
  "result" : "Success"
}

Parent topic: Endpoint Management Commands

3.2.4 okv admin endpoint download Command

The okv admin endpoint download command downloads the endpoint software (okvclient.jar) to the specified directory.

If you want to both download and then install the endpoint software, then use the okv admin endpoint provision command.

Required Authorization

System Administrator role or the Manage Endpoint object privilege for the endpoint

Syntax

okv admin endpoint download --endpoint endpoint_name --location download_location

JSON Input File Template

{
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "download",
    "options" : {
      "endpoint" : "#VALUE",
      "location" : "#VALUE"
    }
  }
}

Parameters

Parameter/Template Parameter Required? Description

--endpoint

/ endpoint

Required

Name of the endpoint.

To find existing endpoints, run the okv admin endpoint list command

--location / location

Required

Absolute path to the download directory for the endpoint software. For example, if you specify /tmp, then the endpoint software is downloaded to /tmp/endpoint_name/okvclient.jar.

JSON Example

  1. Generate JSON input for the okv admin endpoint download command. 
    okv admin endpoint download --generate-json-input

    The generated input appears as follows:

    {
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "download",
    "options" : {
      "endpoint" : "#VALUE",
      "location" : "#VALUE"
    }
  }
}
  2. Save the generated input to a file (for example, download_ep.json) and then edit it so that you can create the endpoint.
    {
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "download",
    "options" : {
      "endpoint" : "hr_db_ep",
      "location": "/opt/downloads/okv"
    }
  }
}
  3. Run the okv admin endpoint download command using the generated JSON file. 
    okv admin endpoint download --from-json download_ep.json

    A successful download of the okvclient.jar file displays the following output: 

    {
  "result" : "Success"
}

Related Topics

Parent topic: Endpoint Management Commands

3.2.5 okv admin endpoint get Command

The okv admin endpoint get command retrieves detailed information for an endpoint, such as its endpoint group and associated wallets.

Required Authorization

System Administrator role or the Manage Endpoint object privilege for the endpoint

Syntax

okv admin endpoint get --endpoint endpoint_name

JSON Input File Template

{
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "get",
    "options" : {
           "endpoint" : "#VALUE"
    }
  }
}

Parameters

Parameter/Template Parameter Required? Description

--endpoint / endpoint

Required

Name of the endpoint.

To find existing endpoints, run the okv admin endpoint list command.

JSON Example

  1. Generate JSON input for the okv admin endpoint get command. 
    okv admin endpoint get --generate-json-input

    The generated input appears as follows:

    {
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "get",
    "options" : {
           "endpoint" : "#VALUE"
    }
  }
}
  2. Save the generated input to a file (for example, get_ep.json) and then edit it to specify an endpoint.
    {
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "get",
    "options" : {
           "endpoint" : "hr_db_ep"
    }
  }
}
  3. Run the okv admin endpoint get command using the generated JSON file. 
    okv admin endpoint get --from-json get_ep.json

    Output similar to the following appears: 

    {
  "result" : "Success",
  "value" : {
    "administratorEmail" : "",
    "certificateExpirationTime" : "2023-10-29 14:48:46",
    "creationTime" : "2021-11-02 14:48:46",
    "defaultWallet" : "",
    "description" : "",
    "effectiveEndpointConfiguration" : {         
                                       "expirePkcs11PersistentCacheOnDatabaseShutdown" : "FALSE",
                                       "serverPollTimeout" : "PT0.3S",
                                       "pkcs11ConfigurationParameterRefreshInterval" : "PT10M",
                                       "pkcs11InMemoryCacheTimeout" : "PT1H",
                                       "pkcs11PersistentCacheRefreshWindow"\" : "PT30M",
                                       "pkcs11PersistentCacheTimeout" : "PT24H",
                                       "pkcs11TraceDirectoryPath" : "/tmp"
                                        },
    "effectiveEndpointSettingsForManagedObjects" : {
      "extractableAttribute" : {
        "symmetricKey" : "TRUE"
      }
    },
    "endpoint" : "HR_DB_EP",
    "endpointConfiguration" : {
      "expirePkcs11PersistentCacheOnDatabaseShutdown" : "FALSE",
      "serverPollTimeout" : "",
      "pkcs11ConfigulationParameterRefreshInterval" : "",
      "pkcs11InMemoryCacheTimeout" : "",
      "pkcs11PersistentCacheRefreshWindow" : "",
      "pkcs11PersistentCacheTimeout" : "",
      "pkcs11TraceDirectoryPath" : ""
    },
    "endpointGroupMembership" : [ {
      "endpointGroup" : "EPG_HR",
      "description" : ""
    } ],
    "endpointSettingsForManagedObjects" : {
      "extractableAttribute" : {
        "symmetricKey" : ""
      }
    },
    "ipAddress" : "100.70.00.00",
    "platform" : "LINUX",
    "selfEnrolled" : "FALSE",
    "status" : "ENROLLED",
    "strictIpCheck" : "TRUE",
    "type" : "ORACLE DATABASE",
    "walletAccess" : [ {
      "access" : "RO",
      "type" : "VIA ENDPOINT GROUP",
      "wallet" : "HR_WALLET"
    } ]
  }
}

    The output under effectiveEndpointConfiguration and effectiveEndpointSettingsForManagedObjects represents the settings that are used for the endpoint configuration (hence, the use of effectiveEndpoint... in the name). They are determined based on the endpoint-specific settings and the global endpoint specific settings.

Parent topic: Endpoint Management Commands

3.2.6 okv admin endpoint get-enrollment-token Command

The okv admin endpoint get-enrollment-token command retrieves an enrollment token for a registered endpoint.

The enrollment token is a one-time token that is generated during the endpoint creation (registration). Oracle Key Vault uses this token to download the software and install the endpoint. The okv admin endpoint get-enrollment-token is useful for the cases where the endpoint administrator (and not the Oracle Key Vault administrator) must download and provision the endpoint. These endpoint administrators, who generally are not Oracle Key Vault users, use the Oracle Key Vault management console to download the endpoint software by providing the token. The okv admin endpoint get-enrollment-token command enables the Oracle Key Vault administrator to retrieve the token using the RESTful services utility, and then pass it securely to an endpoint administrator through an out-of-band channel (for example, email).

This command will work only for endpoints that are in the Registered state.

Required Authorization

System Administrator role or the Manage Endpoint object privilege for the endpoint

Syntax

okv admin endpoint get-enrollment-token --endpoint endpoint_name

JSON Input File Template

{
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "get-enrollment-token",
    "options" : {
      "endpoint" : "#VALUE"
    }
  }
}

Parameters

Parameter/Template Parameter Required? Description

--endpoint / endpoint

Required

Name of the registered endpoint.

To find existing endpoints, run the okv admin endpoint list command.

JSON Example

  1. Generate JSON input for the okv admin endpoint get-enrollment-token command. 
    okv admin endpoint get-enrollment-token --generate-json-input

    The generated input appears as follows:

    {
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "get-enrollment-token",
    "options" : {
      "endpoint" : "#VALUE"
    }
  }
}
  2. Save the generated input to a file (for example, get_token.json) and then edit it so that you can get the enrollment token.
    {
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "get-enrollment-token",
    "options" : {
      "endpoint" : "hr_db_ep"
    }
  }
}
  3. Run the okv admin endpoint get-enrollment-token command using the generated JSON file. 
    okv admin endpoint get-enrollment-token --from-json get_token.json

    Output similar to the following appears: 

    {
  "result" : "Success",
  "value" : {
    "token" : "Si71duR2mGQ8naSZ"
  }
}

Parent topic: Endpoint Management Commands

3.2.7 okv admin endpoint list Command

The okv admin endpoint list command lists the endpoints along with their associated information such as creation time, certificate expiry, and default wallet.

Required Authorization

System Administrator role or the Manage Endpoint object privilege for the endpoint

Syntax

okv admin endpoint list [--limit <limit>] [--platform <platform>]
     [--status <status>] [--type <type>]

JSON Input File Template

{
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "list",
    "options" : {
      "platform" : "#LINUX64|SOLARIS64|SOLARIS_SPARC|HP-UX|AIX|WINDOWS",
      "type" : "#ORACLE_DB|ORACLE_NON_DB|ORACLE_ACFS|MYSQL_DB|SSH_SERVER|OTHER",
      "status" : "#REGISTERED|ENROLLED|SUSPENDED",
      "limit" : "#VALUE"
    }
  }
}

Parameters

Parameter/Template Parameter Required? Description

--limit / limit

Optional

Number of endpoint objects to list.

Enter any whole number from 1 and higher. If the limit is specified, then Oracle Key Vault fetches the number of objects up to the specified limit. If the limit is not specified, then Oracle Key Vault fetches up to 10,000 objects. If you specify a value that is greater than 10,000, then Oracle Key Vault will attempt to fetch that value, depending on the server, client, and network resources. In the output that you retrieve, the fetchedObjectCount value lists the actual number of objects that are fetched. For example, if you specify 100 as the limit but there are only 50 objects fetched, then Oracle Key Vault sets fetchedObjectCount to 50. If you omit this parameter, then Oracle Key Vault retrieves up to 10,000 objects. For another example, if the limit is 100 and fetchedObjectCount is 100, then this means that there are more objects. To fetch all objects, you need to run this command with an increased value for the --limit parameter. If fetchedObjectCount is less than the specified limit, then it means that you have retrieved all the available objects.

--platform /platform

Optional
The endpoint platform. The allowed values are:
  • AIX
  • HP-UX
  • LINUX64
  • SOLARIS64
  • SOLARIS_SPARC
  • WINDOWS

You can also specify a combination of comma separated values. The filter is applied to each value independently, and the combined results returned effectively supporting an OR operation.

--type / type

Optional
Type of the endpoint platform. The allowed values are:
  • MYSQL_DB
  • ORACLE_ACFS
  • ORACLE_DB
  • ORACLE_NON_DB
  • SSH_SERVER
  • OTHER

You can also specify a combination of comma separated values. The filter is applied to each value independently, and the combined results returned effectively supporting an OR operation.

--status / status

Optional
Status of the endpoint platform. The allowed values are:
  • REGISTERED
  • ENROLLED
  • SUSPENDED

You can also specify a combination of comma separated values. The filter is applied to each value independently, and the combined results returned effectively supporting an OR operation.

JSON Example

  1. Generate a JSON input template for the okv admin endpoint list command. 
    okv admin endpoint list --generate-json-input

    The generated input appears as follows:

    {
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "list",
    "options" : {
      "platform" : "#LINUX64|SOLARIS64|SOLARIS_SPARC|HP-UX|AIX|WINDOWS",
      "type" : "#ORACLE_DB|ORACLE_NON_DB|ORACLE_ACFS|MYSQL_DB|SSH_SERVER|OTHER",
      "status" : "#REGISTERED|ENROLLED|SUSPENDED",
      "limit" : "#VALUE"
    }
  }
}
  2. Save the generated input to a file (for example, list_ep.json) and then edit it to specify the number of objects to fetch. 
    {
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "list",
    "options" : {
           "limit" : "2"
    }
  }
}
  3. Run the okv admin endpoint list command using the generated JSON file. 
    okv admin endpoint list --from-json list_ep.json

    Output similar to the following appears: 

    {
  "result" : "Success",
  "value" : {
    "endpoints" : [ {
      "commonNameOfCertificateIssuer" : "CA",
      "createdBy" : "OKVADMIN",
      "creationTime" : "2021-07-13 15:26:47",
      "defaultWallet" : "HR_WALLET",
      "description" : " ",
      "endpoint" : "HR_DB_EP_1",
      "endpointCertificateExpiration" : "2023-07-13 15:26:47",
      "enrollmentToken" : "",
      "ipAddress" : "",
      "platform" : "LINUX",
      "status" : "ENROLLED",
      "type" : "ORACLE DATABASE"
    }, {
      "commonNameOfCertificateIssuer" : "CA",
      "createdBy" : "OKVADMIN",
      "creationTime" : "2021-06-25 19:22:36",
      "defaultWallet" : "",
      "description" : "",
      "endpoint" : "HR_DB_EP_2",
      "endpointCertificateExpiration" : "2023-06-25 19:22:36",
      "enrollmentToken" : "",
      "ipAddress" : "192.0.2.143",
      "platform" : "LINUX",
      "status" : "ENROLLED",
      "type" : "ORACLE DATABASE"
    } ],
    "fetchedObjectCount" : "2"
  }
}

Parent topic: Endpoint Management Commands

3.2.8 okv admin endpoint list-objects Command

The okv admin endpoint list-objects command lists security objects that are associated with a specified endpoint.

Required Authorization

System Administrator role or the Manage Endpoint object privilege for the endpoint

Syntax

okv admin endpoint list-objects --endpoint <endpoint> [--exclude-wallet-membership  <exclude-wallet-membership>] 
    [--limit <limit>][--state <state>] [--type <type>]

JSON Input File Template

{
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "list-objects",
    "options" : {
      "endpoint" : "#VALUE",
      "state" : "#PRE-ACTIVE|ACTIVE|DEACTIVATED|COMPROMISED|DESTROYED|DESTROYED_COMPROMISED",
      "type" : "#CERTIFICATE|OPAQUE|PRIVATE_KEY|PUBLIC_KEY|SECRET|SYMMETRIC_KEY",
      "limit" : "#VALUE",
      "excludeWalletMembership" : "#TRUE|FALSE"
    }
  }
}

Parameters

Parameter/Template Parameter Required? Description

--endpoint / endpoint

Required

Name of the endpoint.

To find existing endpoints, run the okv admin endpoint list command.

--limit / limit

Optional

Number of objects to list.

Enter any whole number from 1 and higher. If the limit is specified, then Oracle Key Vault fetches the number of objects up to the specified limit. If the limit is not specified, then Oracle Key Vault fetches up to 10,000 objects. If you specify a value that is greater than 10,000, then Oracle Key Vault will attempt to fetch that value, depending on the server, client, and network resources. In the output that you retrieve, the fetchedObjectCount value lists the actual number of objects that are fetched. For example, if you specify 100 as the limit but there are only 50 objects fetched, then Oracle Key Vault sets fetchedObjectCount to 50. If you omit this parameter, then Oracle Key Vault retrieves up to 10,000 objects. For another example, if the limit is 100 and fetchedObjectCount is 100, then this means that there are more objects. To fetch all objects, you need to run this command with an increased value for the --limit parameter. If fetchedObjectCount is less than the specified limit, then it means that you have retrieved all the available objects.

--exclude-wallet-membership / excludeWalletMembership

Optional

Controls whether wallet membership is shown for each object.

  • TRUE disables the showing of wallet membership for endpoint objects.
  • FALSE (default) enables the showing of wallet membership for endpoint objects.

--type / type

Optional

Type of the security object. The allowed values are:

  • CERTIFICATE
  • OPAQUE
  • PRIVATE_KEY
  • PUBLIC_KEY
  • SECRET
  • SYMMETRIC_KEY

You can also specify a combination of comma separated values. The filter is applied to each value independently, and the combined results returned effectively supporting an OR operation.

--state / state

Optional

State of the security object. The allowed values are:

  • PRE-ACTIVE
  • ACTIVE
  • DEACTIVATED
  • COMPROMISED
  • DESTROYED
  • DESTROYED_COMPROMISED

You can also specify a combination of comma separated values. The filter is applied to each value independently, and the combined results returned effectively supporting an OR operation.

JSON Example

  1. Generate a JSON input template for the okv admin endpoint list-objects command. 
    okv admin endpoint list-objects --generate-json-input

    The generated input appears as follows:

    {
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "list-objects",
    "options" : {
      "endpoint" : "#VALUE",
      "state" : "#PRE-ACTIVE|ACTIVE|DEACTIVATED|COMPROMISED|DESTROYED|DESTROYED_COMPROMISED",
      "type" : "#CERTIFICATE|OPAQUE|PRIVATE_KEY|PUBLIC_KEY|SECRET|SYMMETRIC_KEY",
      "limit" : "#VALUE",
      "excludeWalletMembership" : "#TRUE|FALSE"
    }
  }
}
  2. Save the generated input to a file (for example, list-obj_ep.json) and then edit it to specify an endpoint the number of records. 
    {
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "list-objects",
    "options" : {
        "endpoint" : "sales-ep",
        "limit" : "8"
    }
  }
}
  3. Run the okv admin endpoint list-objects command using the generated JSON file. 
    okv admin endpoint list-objects --from-json list-obj_ep.json

    Output similar to the following appears: 

    {
  "result" : "Success",
  "value" : {
    "fetchedObjectCount" : "8",
    "managedObjects" : [ {
      "creatingEndpoint" : "SALES-EP",
      "creationDate" : "2021-08-04 18:34:52",
      "deactivationDate" : "2051-10-10 10:10:10",
      "displayName" : "X.509 Certificate: DN EMAILADDRESS=psmith@example.com, CN=vienna, OU=Security, O=Oracle, L=Reston, ST=VA, C=US",
      "name" : "ps30090",
      "protectStopDate" : "2053-10-10 10:10:10",
      "state" : "PRE-ACTIVE",
      "type" : "CERTIFICATE",
      "uuid" : "847D1538-915D-4FD7-BF14-829B1A11FAF9"
    }, {
      "creatingEndpoint" : "SALES-EP",
      "creationDate" : "2021-08-03 21:40:25",
      "deactivationDate" : "2029-12-25 15:11:11",
      "displayName" : "Symmetric Key: Name Sales Key 1",
      "name" : "sales_key_1",
      "protectStopDate" : "",
      "state" : "Pre-Active",
      "type" : "Symmetric Key",
      "uuid" : "670B600E-1667-4FD1-BF94-C35C4BC81E8B"
    }, {
      "creatingEndpoint" : "SALES-EP",
      "creationDate" : "2021-08-03 21:21:33",
      "deactivationDate" : "2029-12-25 15:11:11",
      "displayName" : "X.509 Certificate: DN EMAILADDRESS=psmith@example.com, CN=vienna, OU=Security, O=Oracle, L=Reston, ST=VA, C=US",
      "name" : "orders_key_1",
      "protectStopDate" : "2029-12-25 15:11:11",
      "state" : "Pre-Active",
      "type" : "Certificate",
      "uuid" : "0C11B125-B17A-4F90-BF16-F876E5E20A21"
    }, {
      "creatingEndpoint" : "SALES-EP",
      "creationDate" : "2021-08-03 13:36:01",
      "deactivationDate" : "",
      "displayName" : "rec_key_1",
      "protectStopDate" : "",
      "state" : "Pre-Active",
      "type" : "Symmetric Key",
      "uuid" : "780608F6-0CA6-4FC5-BF46-A7B8A36074F7"
    }, {
      "creatingEndpoint" : "SALES-EP",
      "creationDate" : "2021-08-02 15:41:38",
      "deactivationDate" : "2029-12-25 15:11:11",
      "displayName" : "X.509 Certificate: DN EMAILADDRESS=psmith@example.com, CN=vienna, OU=Security, O=Oracle, L=Reston, ST=VA, C=US",
      "name" : "cert_key_1",
      "protectStopDate" : "2029-12-25 15:11:11",
      "state" : "Pre-Active",
      "type" : "Certificate",
      "uuid" : "72EA8183-98BA-4F5A-BF31-CE7256E29496"
    }, {
      "creatingEndpoint" : "SALES-EP",
      "creationDate" : "2021-07-26 20:19:32",
      "deactivationDate" : "2029-12-25 15:11:11",
      "displayName" : "X.509 Certificate: DN EMAILADDRESS=psmith@example.com, CN=vienna, OU=Security, O=Oracle, L=Reston, ST=VA, C=US",
      "name" : "emp_key_1",
      "protectStopDate" : "2029-12-25 15:11:11",
      "state" : "Pre-Active",
      "type" : "Certificate",
      "uuid" : "975F17DF-11C1-4F16-BFBC-28E9C200C99F"
    }, {
      "creatingEndpoint" : "SALES-EP",
      "creationDate" : "2021-07-23 17:22:14",
      "deactivationDate" : "2041-10-10 10:10:10",
      "displayName" : "emp_key_2",
      "protectStopDate" : "",
      "state" : "Active",
      "type" : "Symmetric Key",
      "uuid" : "330F5527-0DB2-4FD1-BF54-1FA189C8A765"
    }, {
      "creatingEndpoint" : "SALES-EP",
      "creationDate" : "2021-06-30 21:01:48",
      "deactivationDate" : "",
      "displayName" : "Symmetric Key: Name psc7",
      "name" : "emp_key_2,emp_key_3,emp_key_5,emp_key_6,emp_key_7",
      "protectStopDate" : "",
      "state" : "Active",
      "type" : "Symmetric Key",
      "uuid" : "7432AED6-6628-4F43-BF7C-9D30023A4301"
    } ]
  }
}

Parent topic: Endpoint Management Commands

3.2.9 okv admin endpoint provision Command

The okv admin endpoint provision command downloads and installs the endpoint software in the specified directory.

This directory should have read, write, and execute permissions for the owner and its group. For example, if the Oracle Key Vault endpoint software is installed in an Oracle Database server, then this endpoint installation directory should have read, write, and execute permissions by the oracle user and the oinstall group. This ensures that processes can access directories appropriately at run time.

You must meet the following prerequisites to run this command:

  • You must be a user with System Administrator role or the Manage Endpoint object privilege for the endpoint.

  • You must ensure that the soft link/usr/bin/java points to $ORACLE_HOME/jdk/jre/bin/java.

  • You must know how the installation process determines the location of the okvclient.ora file.

If you only want to download the endpoint software but not install it, then use the okv admin endpoint download command.

Required Authorization

System Administrator role or the Manage Endpoint object privilege for the endpoint

Syntax

okv admin endpoint provision --endpoint endpoint_name --location software_location --auto-login TRUE|FALSE

JSON Input File Template

{
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "provision",
    "options" : {
      "endpoint" : "#VALUE",
      "location" : "#VALUE",
      "autoLogin" : "#TRUE|FALSE"
    }
  }
}

Parameters

Parameter/Template Parameter Required? Description

--endpoint / endpoint

Required

Name of the endpoint.

To find existing endpoints, run the okv admin endpoint list command.

--location / location

Required

Path to the location where to install the endpoint software. For Transparent Data Encryption (TDE) environments, specify WALLET_ROOT/okv as the installation directory.

--auto-login / autoLogin

Optional

Enter one of the following values:

  • TRUE to enable auto-login authentication
  • FALSE (default) to store the endpoint credentials that are used to connect to the Oracle Key Vault server in a password-protected wallet. When --auto-login is set to FALSE, then you will be prompted to enter a password interactively.

JSON Example

  1. Generate JSON input for the okv admin endpoint provision command. 
    okv admin endpoint provision --generate-json-input

    The generated input appears as follows:

    {
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "provision",
    "options" : {
      "endpoint" : "#VALUE",
      "location" : "#VALUE",
      "autoLogin" : "#TRUE|FALSE"
    }
  }
}
  2. Save the generated input to a file (for example, provision_ep.json) and then edit it so that you can download and install the endpoint software.
    {
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "provision",
    "options" : {
      "endpoint" : "hr_db_ep",
      "location" : "/u01/opt/oracle/product/okv",
      "autoLogin" : "TRUE"
    }
  }
}
  3. Run the okv admin endpoint provision command using the generated JSON file. 
    okv admin endpoint provision --from-json provision_ep.json

    Output similar to the following appears: 

    {
  "result" : "Success"
}

Related Topics

Parent topic: Endpoint Management Commands

3.2.10 okv admin endpoint re-enroll Command

The okv admin endpoint re-enroll command re-enrolls a previously enrolled endpoint.

Required Authorization

System Administrator role or the Manage Endpoint object privilege for the endpoint

Syntax

okv admin endpoint re-enroll --endpoint endpoint_name

JSON Input File Template

{
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "re-enroll",
    "options" : {
      "endpoint" : "#VALUE"
    }
  }
}

Parameters

Parameter/Template Parameter Required? Description

--endpoint / endpoint

Required

Name of the endpoint.

To find existing endpoints, run the okv admin endpoint list command.

JSON Example

  1. Generate JSON input for the okv admin endpoint re-enroll command. 
    okv admin endpoint re-enroll --generate-json-input

    The generated input appears as follows: 

    {
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "re-enroll",
    "options" : {
      "endpoint" : "#VALUE"
    }
  }
}
  2. Save the generate input to a file (for example, re-enroll_ep.json) and then edit it so that you can re-enroll the endpoint.
    {
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "re-enroll",
    "options" : {
      "endpoint" : "hr_db_ep"
    }
  }
}
  3. Run the okv admin endpoint re-enroll command using the generated JSON file. 
    okv admin endpoint re-enroll --from-json re-enroll_ep.json

    Output similar to the following appears: 

    {
  "result" : "Success"
}

Parent topic: Endpoint Management Commands

3.2.11 okv admin endpoint re-enroll-all Command

The okv admin endpoint re-enroll-all command re-enrolls all previously enrolled endpoints.

Required Authorization

System Administrator role

Syntax

okv admin endpoint re-enroll-all

JSON Input File Template

{
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "re-enroll-all"
  }
}

Parameters

None

JSON Example

  1. Generate JSON input for the okv admin endpoint re-enroll-all command. 
    okv admin endpoint re-enroll-all --generate-json-input

    The generated input appears as follows: 

    {
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "re-enroll-all"
  }
}
  2. Save the generate input to a file (for example, re-enroll-all_ep.json).
  3. Run the okv admin endpoint re-enroll-all command using the generated JSON file. 
    okv admin endpoint re-enroll-all --from-json re-enroll-all_ep.json

    Output similar to the following appears: 

    {
  "result" : "Success"
}

Parent topic: Endpoint Management Commands

3.2.12 okv admin endpoint resume Command

The okv admin endpoint resume command resumes a suspended endpoint.

Required Authorization

System Administrator role or the Manage Endpoint object privilege for the endpoint

Syntax

okv admin endpoint resume --endpoint endpoint_name

JSON Input File Template

{
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "resume",
    "options" : {
     "endpoint" : "#VALUE"
    }
  }
}

Parameters

Parameter/Template Parameter Required? Description

--endpoint / endpoint

Required

Name of the suspended endpoint.

To find the names of suspended endpoints, run the okv admin endpoint list command, and in the output, look for the endpoints that have a status of Suspended.

JSON Example

  1. Generate JSON input for the okv admin endpoint resume command. 
    okv admin endpoint resume --generate-json-input

    The generated input appears as follows:

    {
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "resume",
    "options" : {
     "endpoint" : "#VALUE"
    }
  }
}
  2. Save the generated input to a file (for example, resume_ep.json) and then edit it to specify the suspended endpoint. 
    {
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "resume",
    "options" : {
     "endpoint" : "hr_db_ep"
    }
  }
}
  3. Run the okv admin endpoint resume command using the generated JSON file. 
    okv admin endpoint resume --from-json resume_ep.json

    Output similar to the following appears: 

    {
  "result" : "Success"
}

Parent topic: Endpoint Management Commands

3.2.13 okv admin endpoint suspend Command

The okv admin endpoint suspend command suspends an endpoint.

Required Authorization

System Administrator role or the Manage Endpoint object privilege for the endpoint

Syntax

okv admin endpoint suspend --endpoint endpoint_name

JSON Input File Template

{
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "suspend",
    "options" : {
           "endpoint" : "#VALUE"
    }
  }
}

Parameters

Parameter/Template Parameter Required? Description

--endpoint / endpoint

Required

Name of the endpoint.

To find existing endpoints, run the okv admin endpoint list command.

JSON Example

  1. Generate JSON input for the okv admin endpoint suspend command. 
    okv admin endpoint suspend --generate-json-input

    The generated input appears as follows:

    {
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "suspend",
    "options" : {
           "endpoint" : "#VALUE"
    }
  }
}
  2. Save the generated input to a file (for example, suspend_ep.json) and then edit it to specify the endpoint to suspend.
    {
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "suspend",
    "options" : {
           "endpoint" : "hr_db_ep"
    }
  }
}
  3. Run the okv admin endpoint suspend command using the generated JSON file. 
    okv admin endpoint suspend --from-json suspend_ep.json

    Output similar to the following appears: 

    {
  "result" : "Success"
}

Parent topic: Endpoint Management Commands

3.2.14 okv admin endpoint update Command

The okv admin endpoint update command updates the settings of an endpoint.

Required Authorization

System Administrator role or the Manage Endpoint object privilege for the endpoint

Syntax

okv admin endpoint update 
--endpoint current_endpoint_name 
--name new_endpoint_name
--description "description" 
--email email_address 
--platform platform --type type  
--subgroup "subgroup_value" 
--unique #TRUE|FALSE
--strict-ip-check #TRUE|FALSE

JSON Input File Template

{
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "update",
    "options" : {
      "endpoint" : "#VALUE",
      "name" : "#VALUE",
      "description" : "#VALUE",
      "email" : "#VALUE",
      "platform" : "#LINUX64|SOLARIS64|SOLARIS_SPARC|HP-UX|AIX|WINDOWS",
      "type" : "#ORACLE_DB|ORACLE_NON_DB|ORACLE_ACFS|MYSQL_DB|OTHER",
      "subgroup" : "#VALUE|NO SUBGROUP|USE CREATOR SUBGROUP",
      "unique" : "#TRUE|FALSE",
      "strictIpCheck" : "#TRUE|FALSE",
      "endpointConfiguration" : {
        "expirePkcs11PersistentCacheOnDatabaseShutdown" : "#TRUE|FALSE",
        "serverPollTimeout" : "#VALUE",
        "pkcs11ConfigurationParameterRefreshInterval" : "#VALUE",
        "pkcs11InMemoryCacheTimeout" : "#VALUE",
        "pkcs11PersistentCacheRefreshWindow" : "#VALUE",
        "pkcs11PersistentCacheTimeout" : "#VALUE",
        "pkcs11TraceDirectoryPath" : "#VALUE"
      },
      "endpointSettingsForManagedObjects" : {
        "extractableAttribute" : {
          "privateKey" : "#TRUE|FALSE",
          "symmetricKey" : "#TRUE|FALSE"
        }
      }
    }
  }
}

Parameters

Parameter/Template Parameter Required? Description

--endpoint / endpoint

Required

Name of the endpoint that you want to update.

To find existing endpoints, run the okv admin endpoint list command.

--name / name

Optional

A new name for the endpoint. Ensure that you follow the naming guidelines for objects. See Naming Guidelines for Objects.

--description / description

Optional

A user-friendly description of the endpoint. If the description contains spaces, then you must enclose it within double quotation marks.

--email / email

Optional

Email address of the endpoint administrator. Enclose this value in double quotation marks.

--platform / platform

Optional

The endpoint platform. Allowed values are:

  • AIX

  • HP-UX

  • LINUX64

  • SOLARIS64

  • SOLARIS_SPARC

  • WINDOWS

--type / type

Optional

Type of the endpoint. Allowed values are:

  • MYSQL_DB

  • ORACLE_ACFS

  • ORACLE_DB

  • ORACLE_NON_DB

  • OTHER

--subgroup / subgroup

Optional

For multi-master cluster environments, defines the affinity that an endpoint will have to a specific Oracle Key Vault cluster subgroup. Values are as follows:

  • Enter the name of a multi-master cluster subgroup. To find subgroups, in the Oracle Key Vault management console, select the Cluster tab, then Management in the left navigation bar. Subgroups for the cluster are listed under Cluster Information.
  • NO SUBGROUP creates an endpoint that will have no Oracle Key Vault cluster subgroup affinity.
  • USE CREATOR SUBGROUP creates an endpoint with affinity to the Oracle Key Vault cluster subgroup to which the node that the endpoint is created in belongs.

--unique / unique

Optional

In a multi-master cluster environment, creates the endpoint as a unique endpoint. In a multi-master cluster, it is possible that an endpoint with the same name could be created from two different nodes. If that happens, then endpoint names may conflict. The Oracle Key Vault conflict resolution scheme will keep one endpoint with the given name and rename other endpoints with the conflicting names to a name using this format: given_ep_name_OKVnode_id.

Valid settings are as follows:

  • TRUE appends _OKVnode_id to the given name and thus prevent the conflict for this endpoint name.
  • FALSE (default) causes Oracle Key Vault to begin a checking process to find if the endpoint name is unique. A unique ID is returned. You can use this ID to check the status of the endpoint creation, whether it is in progress (PENDING) or complete (ACTIVE). If the status is PENDING, then it is not yet usable, so any actions performed on the endpoint will fail. If the status is ACTIVE, then the endpoint is usable. To check the status, run the okv admin endpoint check_status command. If the name that you provided is already used in another node, then the name for this endpoint will have _OKVxx appended to it. For example, if you named the endpoint ep12, and there is a naming conflict, the name could be EP12_OKV01.

--strict-ip-check / strictIpCheck

Optional

Controls whether the Oracle Key Vault server checks the incoming IP address for a given endpoint.

  • TRUE enables Oracle Key Vault to check the incoming IP address of an endpoint. If the IP address does not match with the one that was used when the client endpoint software was installed, then Oracle Key Vault does not allow the connection.
  • FALSE disables this check and allows the incoming connection for the endpoint to come from any IP address.

/endpointConfiguration

Optional

Each endpointConfiguration setting represents an endpoint configuration parameter. You must use the JSON syntax to add an endpoint configuration parameter(s). You cannot specify these endpoint configuration parameter(s) at the command line.

Values that you can enter are as follows:

  • expirePkcs11PersistentCacheOnDatabaseShutdown sets whether the PKCS#11 persistent cache for a given endpoint database automatically expires upon shutdown of the endpoint database.
    • TRUE (default) enables expirePkcs11PersistentCacheOnDatabaseShutdown.
    • FALSE disables expirePkcs11PersistentCacheOnDatabaseShutdown.

    For any endpoint-specific configuration parameters, you can also set them to an empty value (default) which signifies the absence of an endpoint specific parameter. In this case, the endpoint inherits this parameter from the global endpoint.

    You remove an endpoint-specific configuration parameter by specifying an empty value for it. After an endpoint-specific parameter is removed, the endpoint starts inheriting the setting from the global endpoint.

  • The following timeout parameters:
    • serverPollTimeout specifies the server poll timeout.
    • pkcs11ConfigurationParameterRefreshInterval sets the frequency at which a long-running process will re-read the okvclient.ora configuration file.
    • pkcs11InMemoryCacheTimeout sets how long a master encryption key is available in the in-memory cache.
    • pkcs11PersistentCacheRefreshWindow extends the time the master encryption key remains available for use in the persistent cache after its persistent cache timeout period has expired.
    • pkcs11PersistentCacheTimeout sets how long the master encryption is available in the persistent cache.

    You can use different ways to set these timeout values, which use the duration format based on the ISO-8601 standard. Examples are as follows: 

    "serverPollTimeout" : "PT0.3S", -- 300 millseconds
"pkcs11InMemoryCacheTimeout" : "PT10M", -- 10 minutes
"pkcs11PersistentCacheTimeout" : "PT5H", -- 5 hours
"pkcs11PersistentCacheRefreshWindow" : "P1D", -- 1 day
  • pkcs11TraceDirectoryPath sets the path of the trace files

/endpointSettingsForManagedObjects

Optional

extractableAttribute enables you to specify whether symmetric keys can be extracted from Oracle Key Vault. You must use the JSON syntax to add or modify this setting. You cannot specify this setting at the command line. The setting is as follows:

  • symmetricKey
    • TRUE allows the symmetricKey object value to be extracted from Oracle Key Vault.
    • FALSE prevents the symmetricKey object value from being extracted from Oracle Key Vault.
  • privateKey
    • TRUE allows the privateKey object value to be extracted from Oracle Key Vault.
    • FALSE prevents the privateKey object value from being extracted from Oracle Key Vault.

    For any endpoint-specific settings, you can also set them to an empty value (default) which signifies the absence of an endpoint specific setting. In this case, the endpoint inherits this setting from the global endpoint.

    You remove an endpoint specific-setting by specifying an empty value for it. After an endpoint-specific setting is removed, the endpoint starts inheriting the setting from the global endpoint.

    The default value for the symmetricKey and privateKeysetting is inherited from the global endpoint configuration. If you provide an empty value in endpointConfiguration or extractableAttribute, then it will remove the corresponding configuration.

JSON Example

  1. Generate JSON input for the okv admin endpoint update command. 
    okv admin endpoint update --generate-json-input

    The generated input appears as follows: 

    {
  "service" : {
    "category" : "admin",
    "resource" : "endpoint",
    "action" : "update",
    "options" : {
      "endpoint" : "#VALUE",
      "name" : "#VALUE",
      "description" : "#VALUE",
      "email" : "#VALUE",
      "platform" : "#LINUX64|SOLARIS64|SOLARIS_SPARC|HP-UX|AIX|WINDOWS",
      "type" : "#ORACLE_DB|ORACLE_NON_DB|ORACLE_ACFS|MYSQL_DB|OTHER",
      "subgroup" : "#VALUE|NO SUBGROUP|USE CREATOR SUBGROUP",
      "unique" : "#TRUE|FALSE",
      "strictIpCheck" : "#TRUE|FALSE",
      "endpointConfiguration" : {
        "expirePkcs11PersistentCacheOnDatabaseShutdown" : "#TRUE|FALSE",
        "serverPollTimeout" : "#VALUE",
        "pkcs11ConfigurationParameterRefreshInterval" : "#VALUE",
        "pkcs11InMemoryCacheTimeout" : "#VALUE",
        "pkcs11PersistentCacheRefreshWindow" : "#VALUE",
        "pkcs11PersistentCacheTimeout" : "#VALUE",
        "pkcs11TraceDirectoryPath" : "#VALUE"
      },
      "endpointSettingsForManagedObjects" : {
        "extractableAttribute" : {
          "privateKey" : "#TRUE|FALSE",
          "symmetricKey" : "#TRUE|FALSE"
        }
      }
    }
  }
}
  2. Save the generated input to a file (for example, update_ep.json) and then edit it to update the endpoint.
    {
  "service": {
    "category": "admin",
    "resource": "endpoint",
    "action": "update",
    "options": {
      "endpoint": "hr_db_ep",
      "description": "",
      "platform": "LINUX64",
      "email": "",
      "type": "ORACLE_DB",
      "strictIpCheck" : "TRUE",
      "endpointConfiguration" : {
          "expirePkcs11PersistentCacheOnDatabaseShutdown" : "TRUE",
          "serverPollTimeout" : "PT5M",
          "pkcs11ConfigurationParameterRefresh" : "PT11M",
          "pkcs11InMemoryCacheTimeout" : "PT20M",
          "pkcs11PersistentCacheRefreshWindow" : "PT30M",
          "pkcs11PersistentCacheTimeout" : "PT40M",
          "pkcs11TraceDirectoryPath" : "/users/psmith/work"
      },
      "endpointSettingsForManagedObjects" : {
          "extractableAttribute" : {
              "symmetricKey" : "FALSE"
          }
        }
     }
  }
}
  3. Run the okv admin endpoint update command using the generated JSON file. 
    okv admin endpoint update --from-json update_ep.json

    Output similar to the following appears: 

    {
  "result" : "Success",
}

Related Topics

Parent topic: Endpoint Management Commands