16 Management of SSH Keys - Setup and Configuration

You can use Oracle Key Vault to centrally manage Secure Shell (SSH) private and public keys and control access to SSH servers.

16.1 Setup SSH Admin

An Secure Shell (SSH) administrator is an Oracle Key Vault user who should be able to manage access to SSH servers for SSH users centrally in Oracle Key Vault.

An SSH admin manages the SSH Server wallets and SSH Server endpoints needed for the controlling access to SSH servers from Oracle Key Vault. An SSH admin may or may not manage the SSH user keys.

To setup an SSH administrator, you must:
  1. Create an Oracle Key Vault user.
  2. Grant the Create Endpoint privilege to the user. This user can then manage any endpoints that it creates.
  3. Grant the Manage Endpoint privilege to the user. This may be needed for those endpoint that are created by another user.

This section detail the steps required to setup an SSH administrator.

Create a regular Oracle Key Vault user

  1. Log in to the Oracle Key Vault management console as a user who has the System Administrator role.
  2. Select the Users tab, and then Manage Users in the left navigation bar.

    The Manage Users page appears with a list of existing users.

  3. In the Manage Users page, click Create.

    The Create User page appears.

  4. Provide the details for the required fields on the Create User page. For more information see, Creating an Oracle Key Vault User Account.
  5. Click Save.
  6. In a multi-master cluster, the user is initially created in the PENDING state. After cluster naming conflict resolution for the new user is completed, the user is transitioned to the ACTIVE state.

Grant the Create Endpoint Privilege

  1. Log in to the Oracle Key Vault management console as a user who has the System Administrator role.

    Users who have the Create Endpoint privilege cannot grant it to other users.

  2. Select the Users tab, and then Manage Users in the left navigation bar.

    The Manage Users page appears displaying the list of users.

  3. Select the user to whom you want to grant the Create Endpoint privilege.
  4. Under User Details, select the Create Endpoint check box.
  5. Click Save.

    Note:

    When a local Oracle Key Vault user with the Create Endpoint privilege creates an endpoint, Oracle Key Vault grants the Manage Endpoint privilege on that endpoint to the local user.

Grant the Manage Endpoint Privilege

  1. Log in to the Oracle Key Vault management console as a user who has the System Administrator role.

    Users who have the Manage Endpoint privilege cannot grant it to other users.

  2. Select the Users tab, and then Manage Users in the left navigation bar.

    The Manage Users page appears displaying the list of users.

  3. Select the user to whom you want to grant the Manage Endpoint privilege.
  4. In the Access on Endpoints area, click Add.
  5. In the Add Endpoint Access to User page, under Select Endpoint, select the endpoint to which you want to grant the user the Manage Endpoint privilege.
  6. Click Save.

Repeat above steps to grant the Manage Endpoint privilege on all other endpoints that the SSH admin needs to manage.

16.2 Controlling Access to SSH Server Centrally with Oracle Key Vault

You can centrally manage which SSH users have access to which SSH servers.

16.2.1 About Controlling Access to SSH Server Centrally with Oracle Key Vault

As an Secure Shell (SSH ) administrator, you manage one or more SSH servers within an organization. With Oracle Key Vault, you can centrally manage the SSH users access for SSH Servers.

To prepare an SSH server for the centralized access management in Oracle Key Vault, you must identify the SSH server host users you plan to allow the SSH users to log in as. t is recommended that you modify the OpenSSH daemon configuration to disallow the use of authorized_keys file to prevent access grants outside of Oracle Key Vault.

To centrally manage the SSH access of an SSH server, you need to:

  1. Register an SSH Server endpoint.
  2. Setup an SSH Server wallet for each SSH server host user that you plan to allow to log in as to the SSH server.
  3. Grant SSH Server endpoint read only access on the SSH server wallets.
  4. Provision the SSH Server endpoint on the SSH server.
  5. Setup the OpenSSH SSH daemon to use the Oracle Key Vault SSH Server endpoint software.
  6. Add the public keys of the SSH client users to the SSH Server wallets.

    Note:

    To authorize an SSH client user to connect to the SSH server as an SSH server host user, you add the user's public key in the SSH Server wallet corresponding to the SSH server host user.

16.2.2 Setup in Oracle Key Vault Server

As the SSH admin user, perform the steps given below for configuring the SSH Server endpoint and SSH Server wallets in Oracle Key Vault.

Register an SSH Server endpoint

You need to setup an SSH Server endpoint on the SSH server host. The OpenSSH daemon configuration is modified to use the SSH Server endpoint script to validate whether the key offered by the SSH client is among the authorized keys for the host user.

  1. Log in to the Oracle Key Vault management console as an SSH admin user. The SSH admin user must have the privilege to create an endpoint.
  2. Select the Endpoints tab, then Endpoints in the left navigation bar. The Endpoints page appears listing all the Oracle Key Vault endpoints.
  3. On the Endpoints page, click Add.
  4. The Register Endpoint page appears.
  5. From the Type drop-down list, select the type of endpoint as SSH Server.
  6. Selecting the endpoint type as SSH Server displays another field SSH Server Hostname. You add the hostname or IP address of the SSH server where this endpoint will be deployed.
  7. Provide the details of the required field in the Register Endpoint page. See Adding an Endpoint as an Oracle Key Vault System Administrator or Create Endpoint User
    These are the platforms on which you can deploy SSH server endpoint (except SSH Server endpoints on Windows).
    • Oracle Linux 7 and 8
    • Solaris X64 11.4
    • Solaris SPARC 11.4
    • HP-UX IA64 11.31
  8. Click Register to create the new endpoint.

    Once the endpoint is registered successfully, Endpoints page appears. Copy and save the Enrollment Token value for the new endpoint. You will need it to download the endpoint software and then enroll the endpoint on the SSH server.

Create SSH Server wallets
You need to setup an SSH Server wallet for each SSH server host user that you plan to allow SSH client users to log in as to the SSH server.
  1. Log in to the Oracle Key Vault management console as an SSH admin user.
  2. Select the Keys & Wallets tab, and then select Wallets from the left navigation bar.
  3. In the Wallets area, click Create. The Create Wallet page appears.
  4. For the Wallet Type, select SSH Server.
  5. Selecting the Wallet Type as SSH Server displays another field SSH Server Host User.

    Enter the name of the SSH server host user for whom this wallet will control SSH access. SSH client users whose public keys are added to this wallet can access the SSH server as this host user.

  6. Provide the details of the required fields in the Create Wallet page. See,Creating a Virtual Wallet.
  7. Click Save to create the new wallet.

    Note:

    You can use an SSH Server wallet to manage the authorization for an SSH server host user on the multiple SSH servers if the same set of the SSH client users need to log in as that host user on all of these SSH servers. Such shared use of SSH Server wallets may further simplify the SSH access management at scale.
Grant SSH Server endpoint Read Only access on the SSH Server wallets
Grant the SSH Server endpoint Read Only access to each SSH Server wallets. This access would allow the SSH Server endpoint to validate if the public key offered by the ssh client is present in the SSH Server wallet of the host user that the client user is connecting as.
  1. Log in to the Oracle Key Vault management console as an SSH admin user.
  2. Select the Endpoints tab, and then select Endpoints from the left navigation bar.
  3. Endpoints page is displayed. Find the SSH Sever endpoint, and then click on the endpoint name. Endpoint Details page is displayed.
  4. In the Access to Wallets area, click on Add. Add Access To Endpoint page is displayed.
  5. In the Select Wallet area, select the SSH Server wallets on which you want to grant access to.
  6. In the Select Access Level area, select Read Only.
  7. Click Save.

16.2.3 Setup on SSH Server

Perform the steps given below to deploy and configure the SSH Server endpoint and modify the OpenSSH configuration on the SSH server.

Because the OpenSSH daemon is typically run as the root user, ensure that the SSH Server endpoint is deployed as the root user on the SSH server.

If the SSH admin user does not have the root access on the SSH server, then the SSH admin must coordinate the execution of below configuration steps with an administrator who has the root access of the SSH server. This document assumes that the SSH admin has the root access on the SSH server.

Provision the SSH Server endpoint on the SSH server using the following steps:

Enroll the Endpoint and Download the Software

You enroll the endpoint using the enrollment token and then download the endpoint software.

You can download the endpoint software from the SSH server where you want to deploy it, or you can download the software from another host and then copy over the downloaded endpoint software (okvclient.jar) to the SSH server. Ensure that you protect the integrity of the downloaded software by applying stricter file permissions.

After registering the endpoint, the Oracle Key Vault system administrator sends this endpoint's enrollment token to the endpoint administrator by email or other out-of-band method.
  1. Log in to the SSH server as the root user.
  2. Connect to the Oracle Key Vault management console as an SSH admin user

    For example: https://192.0.2.254.

    The login page to the Oracle Key Vault management console appears. Do not log in.

  3. Click on the Endpoint Enrollment and Software Download immediately below the Login button. The Enroll Endpoint & Download Software page appears.
  4. In the Enrollment Token field, enter the SSH Server endpoint's enrollment token, and click Submit Token. You saved the enrollment token during the endpoint registration step.
    1. If the token is valid, then a valid token message appears below the Enrollment Tokenfield. The Endpoint Type, Endpoint Platform, Email and Description fields are automatically populated with the values that were entered during endpoint registration.

      If the token is invalid, then an invalid token message appears. Check the token and retry the download procedure.

    2. Click Enroll at the top right corner of the page.
  5. In the directory window that appears, follow the prompt to save the okvclient.jar endpoint software file.

    You must navigate to the directory where you want to save the file.

  6. Save the file to a secure directory with appropriate permissions in place so that it cannot be read or copied by others.
  7. Verify that the file has been downloaded.

    Note:

    If you did not download the file to the endpoint system, you must use an out-of-band method to copy the file to that system and install it there. At this stage, you are ready to install the Oracle Key Vault okvclient.jar software file on the SSH server.

Install the SSH Server endpoint on the SSH Server

You install the SSH Server endpoint on the SSH server using the downloaded endpoint software file okvclient.jar.

You install the endpoint as the root user on the SSH server because the OpenSSH daemon is typical run as the root user.

Before you install the SSH Server endpoint, ensure the following:
  • That you have JDK 1.5 or later installed, and that the PATH environment variable includes the java executable (in the JAVA_HOME/bin directory). Oracle Key Vault supports JDK versions 1.5, 1.6, 7, and 8. The 64-bit version of Java is required.
  • That the version of OpenSSH used on the system is version 8 or later (with support for the AuthorizedKeysCommand keyword).

To install the SSH Server endpoint onto the SSH server host:

  1. Ensure that you are logged in to the SSH server host as the root user.
  2. Navigate to a new SSH Server endpoint directory on the server where you want to deploy the endpoint software.
  3. Move the okvclient.jar file from it’s saved location to this new SSH endpoint directory.
  4. After confirming this directory is empty other than the okvclient.jar file, run the java command as the root user to install the okvclient.jar file. For example,
    java -jar okvclient.jar -d /<path_to_SSH_EP_directory>/<SSH_EP_directory> –v

    In this specification:

    • -d specifies the directory location for the endpoint software and configuration files, in this case /<path_to_SSH_EP_directory>/<SSH_EP_directory>.
    • -v writes the installation logs to the /<path_to_SSH_EP_directory>/<SSH_EP_directory>/log/okvutil.deploy.log file at the server endpoint.
  5. When you are prompted for the password, enter:
    • <enter> for the auto-login endpoint or
    • a valid password for the password-protected endpoint.
    • If you want to create a password-protected endpoint, at minimum enter a password between 8 and 30 characters and then press Enter. For better security, Oracle recommends that you include uppercase letters, lowercase characters, special characters, and numbers in the password. The following special characters are allowed: (.), comma (,), underscore (_), plus sign (+), colon (:), space.
    Enter new Key Vault endpoint password (<enter> for auto-login): Key_Vault_endpoint_password
    Confirm new endpoint password: Key_Vault_endpoint_password

Note:

A password-protected wallet is an Oracle wallet file that stores the endpoint's credentials to access Oracle Key Vault. This password will be required whenever the endpoint connects to Oracle Key Vault.

Additional configuration for Password-protected endpoint

If you installed the SSH Server endpoint as the auto-login endpoint, skip these steps.

For the password-protected endpoint, additional configuration is required to automate the supplying of the endpoint password to the SSH Server endpoint's authorized keys lookup script. The OpenSSH daemon executes this script when authenticating the SSH client connections and this script must be able to connect to the Oracle Key Vault without asking for the endpoint password.

To automate the supplying of the endpoint password, complete below configuration:

  • Create a script or an executable which when executed returns the endpont password in cleartext on the standard output.
  • Change directory to the endpoint's directory.
  • Open the script bin/okv_ssh_ep_lookup_authorized_keys for editing.
  •   SSH_SERVER_ENDPOINT_GET_PASSWORD_SCRIPT="<full-path-of-the-password-script>"
Configure SSH Server Host User to SSH Server Wallet mapping

You must setup the SSH server mapping file which contains the SSH Server host user to SSH Server wallet mapping. This is the configuration file for the okv_ssh_ep_lookup_authorized_keys script. For each SSH server host user there must be a corresponding SSH Server wallet setup in Oracle Key Vault. When an SSH client connection is received, the okv_ssh_ep_lookup_authorized_keys script first looks up the SSH Server wallet corresponding to the host user of the incoming SSH connection. The okv_ssh_ep_lookup_authorized_keys then verifies whether the public key offered by the client is present in mapped SSH Server wallet.

Update the SSH Server endpoint configuration file
/<path_to_SSH_EP_directory>/<SSH_EP_directory>/conf/okvsshendpoint.conf
to map the SSH server host users with their corresponding SSH Server wallets.

For example, below configuration file shows the mapping for the host OS users oracle, opc, and root on the SSH Server pheonix to their mapped SSH Server wallets oracle_ssh_wallet, opc_ssh_wallet, and root_ssh_wallet_for_phoenix respectively.

# Configuration file for Oracle Key Vault SSH server endpoints
[ oracle ]
ssh_server_wallet=oracle_ssh_wallet

[ opc ]
ssh_server_wallet=opc_ssh_wallet

[ root ]
ssh_server_wallet=root_ssh_wallet_for_phoenix

Configure OpenSSH daemon to integrate with Oracle Key Vault

Configure the OpenSSH SSH daemon to use the Oracle Key Vault SSH endpoint software. On the SSH Server update the AuthorizedKeysCommand keyword of the OpenSSH daemon configuration file sshd_config and set it to invoke the SSH Server endpoint lookup script okv_ssh_ep_lookup_authorized_keys.
  1. On the SSH server host, stop the SSH daemon using commands specific to the platform on which it runs. For example, on Oracle Linux 7, stop the SSH daemon as follows:
    /usr/bin/systemctl stop sshd
  2. Edit the SSH server host's sshd_config file to use SSH Server endpoint lookup script by updating the following lines:
    #AuthorizedKeysCommand none
    #AuthorizedKeysCommandUser nobody
    AuthorizedKeysCommand
              /<path_to_SSH_EP_directory>/<SSH_EP_directory>/bin/okv_ssh_ep_lookup_authorized_keys
              get_authorized_keys_for_user %u %f %k
    AuthorizedKeysCommandUser
        root

    Ensure that you specify the arguments to the okv_ssh_ep_lookup_authorized_keys script exactly as shown above, including their relative order.

  3. Restart the SSH daemon on the SSH server host using commands specific to the platform on which the SSH server host runs. For example, on Oracle Linux 7, restart the SSH daemon using the systemctl command.
    /usr/bin/systemctl restart sshd

    Note:

    You should keep a root user session open on the SSH server until you have validated that the ssh users can connect to the SSH server.
.

16.2.4 Manage SSH Server Access from Oracle Key Vault

After completing the configuration steps in the Oracle Key Vault and the SSH Server, you can now control which users can connect to the SSH server using SSH public key authentication.

To authorize a ssh client user to connect as an SSH server host user on an SSH server, you add the ssh client user's public key to the SSH Server wallet that is configured to hold the authorized public keys for the the host user on the SSH server.

If the SSH user's public key is not yet available in Oracle Key Vault, then first upload the SSH public key using the Oracle Key Vault RESTful services utility. See Oracle Key Vault RESTful Services Administrator's Guide for the details on configuring and using the RESTful services utility.

If the public key that you are uploading is in the SSH-format, as is the case with the public keys in the host user's authorized_keys file, then first convert the public key to the PKCS8 format using the ssh-keygen utility as shown in the below example:

$ ssh-keygen -e -m PKCS8 -f john-pubkey-ssh.pub > john-pubkey-pkcs8.pub
Verify that the public key is in the PKCS8 format.
$ cat opc-pubkey-pkcs8.pub
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArbHYwXcOapqD6Xv4B8VX
8Ce8IilZBUl2iUtYcl1K/179IxD+ViD6B+yBYO+Yp0J5aXvFSwMyztEfQdSn7GmG
ASUVSXGmqqKr0skWxkVsIyxzGC7zxBXcISkmB3kkZFMCwLsj+hzpEQfKTFItMGaZ
eTfC0CxtSprP3HQopn796KMsxvsuubTGayy05pZQXCScryTIR1Mcwa/quKdFy1Vj
t3VI/nzLAdMTGYN9MAOnkt1hmD2jE+dBBQ/excoHl+WoZLjek0wNcyifFRxeOM64
d7LDv90G5pjQctQk+73gkqPhBewFlMh2Ql068i2Jg0ygbceK6qoUqxRnFsUkBDXa
/QIDAQAB
-----END PUBLIC KEY-----
You upload the SSH public key in the PKCS8 format to the Oracle Key Vault using the RESTful services utility:
okv managed-object public-key register --output_format text --object john-pubkey-pkcs8.pub --algorithm RSA --length 2048 -mask "ENCRYPT" 
--ssh-user "John" --name "SSH public key of John" --activation-date now --deactivation-date "2025-10-15 00:00:00"

Above command returns the unique identifier of the new SSH public key in Oracle Key Vault.

Next, you add the SSH public key to the SSH Server wallet using the following steps:
  1. Log in to the Oracle Key Vault management console as an SSH admin user.
  2. Select the Keys & Wallets tab, then Keys & Secrets in the left navigation bar. The Keys & Secrets page appears.
  3. In the search bar, enter the unique identifier of the SSH public key created above. Click Go.
  4. For the key found, click Edit. The Object Details page appears.
  5. In the Wallet Membership area, click on Add Wallet Membership.
  6. In the Add Wallet Membership dialog box, select the SSH Server wallet where you want to add this SSH public key and click Add.

    You have now authorized the SSH user to connect to the SSH server as the SSH server host user associated with the SSH server wallet.

Implementation considerations:
  • If the user's SSH public key is already present in the Oracle Key Vault, then do not upload the key again. As an SSH admin, you can add the same public key to different SSH Server wallets to grant the user access to different SSH servers and as different host users.
  • If the SSH keys are created and managed by SSH users themselves, then the SSH users must add their public key to a separate wallet and grant the access of that wallet to the SSH admin. This way, the SSH admin can access the user's public key from that wallet and then add it to the required SSH Server wallets.
  • If the SSH keys are created and managed by an SSH admin, then the SSH admin already has access to the SSH user's public key. The SSH admin can add the user's public key to the required SSH Server wallets without needing another intermediate wallet to hold the user's public key.

16.3 Managing SSH User Keys with Oracle Key Vault

You can manage the Secure Shell (SSH) keys of the SSH users centrally in Oracle Key Vault and enforce key management and governance.

16.3.1 About Managing the SSH User Keys with Oracle Key Vault

You can manage the SSH keys of the SSH users centrally in Oracle Key Vault and enforce key management and governance.

The SSH public key authentication is often the preferred method of user authentication within an enterprise. Hundreds of SSH client, users and servers alike, generate and manage their own SSH key pairs. Not all users are familiar with the best practices around key management. These poorly managed SSH keys are distributed across enterprise leading to a "key sprawl" that presents as a security weakness for any organization-wide deployment.
The Oracle Key Vault PKCS#11 library supports SSH public key authentication using a SSH key pair that is stored in Oracle Key Vault. You can centrally manage the SSH keys of the enterprise users in Oracle Key Vault to simplify key life-cycle management, enable key governance and uniformly enforce policies. The SSH users connect to the SSH servers using their keys directly from Oracle Key Vault.
There are two models to manage the SSH users keys.
  • The SSH admin is responsible for the SSH user key management.

    In this deployment model, a central team of administrators manages the complete life cycle of the SSH users keys. The SSH users are only given the authorization to the use their SSH keys, but they do not have the ownership rights on their keys. In this model, the SSH users cannot share their private keys with other users if the SSH admin set the private keys as non-extractable.

    In this model, the SSH users need not be an Oracle Key Vault user.

  • The SSH users are responsible for the management of their own keys.

    In this deployment model, the SSH users create and manage their own SSH keys. They retain the full ownership of their SSH user keys and are responsible for managing the complete life cycle.

    In this model, each SSH user must have their own user account in Oracle Key Vault.

Depending upon the model you choose to manage the SSH keys - by the SSH admins or the SSH users, the steps described below may vary slightly. This document assumes that the SSH user key management is done by the SSH administrators.

To centrally manage the SSH user keys in Oracle Key Vault, as an SSH admin you would need to:

  1. Register an endpoint for the SSH user and deploy it on the SSH client host.
  2. Create a general wallet with exclusive access to the endpoint created previously.
  3. Create or Register the SSH key pair and it to the general wallet created previously.
    • You can use the UI or RESTful utility to create an SSH key pair.
    • Or you can register an existing SSH key pair using the RESTful utility.
  4. Download the public key and share it with the administrator of the SSH server.

    SSH server admin adds the keys to relevant authorized_keys files.

16.3.2 Oracle Key Vault Server Setup

Register an endpoint for SSH user.

Register an endpoint for SSH user

You register an endpoint to use with the OpenSSH client. You can also use an existing endpoint, such as an Oracle Database endpoint, with the OpenSSH client.
  1. Log in to the Oracle Key Vault management console as an SSH admin user or or a user with the System administrator role or the privilege to create an endpoint.
  2. Select the Endpoints tab, then Endpoints in the left navigation bar. The Endpoints page appears listing all the Oracle Key Vault endpoints.
  3. On the Endpoints page, click Add.
  4. The Register Endpoint page appears.
  5. From the Type drop-down list, select the endpoint type.

    You can select any endpoint type, as appropriate, except for the SSH Server as they are meant to be deployed on the SSH Servers.

  6. Provide the details of the required field in the Register Endpoint page. See, Adding an Endpoint as an Oracle Key Vault System Administrator or Create Endpoint User.
  7. Click Register.

    Once the endpoint is registered successfully, Endpoints page appears. Copy and save the Enrollment Token value for the new endpoint. You will need it to download the endpoint software and then enroll the endpoint on the SSH client host.

Create a General Wallet for SSH user keys

You create a general wallet to store the SSH keys for a SSH user. You will store the SSH public and private keys of an SSH user in this wallet.
  1. Log in to the Oracle Key Vault management console as an SSH admin user.
  2. Select the Keys & Wallets tab, and then select Wallets from the left navigation bar.
  3. In the Wallets area, click Create. The Create Wallet page appears.
  4. For the Wallet Type, select General.
  5. Provide the details of the required fields in the Create Wallet page. See,Creating a Virtual Wallet .
  6. Click Save to create the new wallet.
.

Create or Register an SSH key pair

You create or register an SSH key pair and store them in the general wallet created previously.

You can create an SSH key pair using the Oracle Key Vault management console or RESTful services utility. When creating the key from the Oracle key Vault management console, you can specify the general wallet at the time of key creation itself.

You can register the existing SSH keys in the Oracle Key Vault using the RESTful services utility only. After registering, you move them to the general wallet.

Use the steps below to create an SSH key pair using the Oracle Key Vault management console.

  1. Log in to the Oracle Key Vault management console as an SSH admin.
  2. Select the Keys & Wallets tab, and then select Keys & Secrets from the left navigation bar.
  3. In the Keys & Secrets page, click Create.
  4. In the page that appears, select SSH Key Pair from the Application Keys section. The Create SSH Key Pair page appears.

  5. Complete the information on SSH Key Pair page:
    • SSH User: Enter the name of SSH client user who will be using these SSH keys. This user need not be an Oracle Key Vault user.
    • Cryptographic Algorithm: Supported algorithm is RSA.
    • Cryptographic Length: Key length. Keys of three lengths are supported: 2048, 3072, 4096.
    • Private Key Extractable: Should the private key of the SSH key pair be extractable from the Oracle Key Vault server. The default and recommended value is False.
    • Date of Activation: The time from when the SSH key pair should become active. The default value is the current system time.
    • Date of Deactivation: The time from when the SSH key pair should become deactivated i.e. expired. You should rotate the SSH keys before they expire. The default value is 2 years from the current system time.
    • Wallet Membership: The wallet where you want to store the new SSH keys. You must have the Manage Wallet permission on the wallet. This should be set to the general wallet created above.
    • Click Create to create the new SSH key pair.

Grant the SSH user's endpoint read only access on the general wallet for the SSH user

You grant the SSH user's endpoint read only acess to the general wallet for the SSH user. This allows the endpoint to use the SSH keys from the general wallet when user attempts an SSH connection using SSH public key authentication.

  1. Log in to the Oracle Key Vault management console as an SSH admin user.
  2. Select the Keys and Wallets tab, and then select Wallets from the left navigation bar.
  3. Wallets page is displayed. Find the SSH user's general wallet and click on the pencil icon. The Wallet Overview page appears.
  4. In the Wallet Access Settings area, click Add.

    In the Select Endpoint/User Group area, select type Endpoints from the drop-down list.

  5. Select the checkbox for the SSH user's endpoint that you want to grant access to.
  6. In the Select Access Level area, select Read Only.
  7. Click Save

Note:

If you are using the deployment model where SSH users create and manage their own SSH keys, many of these steps described above are done by SSH users themselves. An SSH user must have an Oracle Key Vault user account in order to manage their own SSH keys in Oracle Key Vault.
In this model, above steps would change as below:
  1. Register an endpoint for SSH user: No change. You continue to run this step as an SSH admin.
  2. Create a general wallet for SSH user keys: You now run this step as an SSH user.
  3. Create or register an SSH key pair: You now run this step as an SSH user.
  4. Grant the SSH user's endpoint read only access on the general wallet for the SSH user: You now run this step as an SSH user.

16.3.3 SSH Client Host Setup

You install the SSH user's endpoint on the SSH client host from where the SSH user would connect to SSH servers.

To perform the SSH public key authentication using the SSH keys from the Oracle Key Vault, you need an Oracle Key Vault endpoint on the SSH client host. The SSH user uses the OpenSSH client with the endpoint's Oracle Key Vault PKCS#11 library to establish SSH connections.

You may choose to install the endpoint in a network folder such as under the user's home directory. This would allow the user to make SSH connections using this endpoint from multiple hosts.

The SSH user's endpoint provides access to the private keys of the SSH user. It is recommended that you install the endpoint as password-protected. The permissions on the endpoint must be restricted to the SSH user. Generally, SSH users would install their endpoints themselves.

In certain deployments, such as when SSH users are applications or machines and not the human users, you may use existing endpoints. For example, you may use an existing Oracle Database endpoint to make SSH connections as the SSH client user 'oracle'. In such setup, you would grant this endpoint the Read Only access to the wallet that holds the keys for the application or machine user.

Use these steps to provision the SSH user's endpoint on the SSH client host.

Enroll the Endpoint and Download the Software

You enroll the endpoint using the enrollment token and then download the endpoint software.

You can download the endpoint software from the SSH client host where you want to deploy it, or you can download the software from another host and then copy over the downloaded endpoint software (okvclient.jar) to the SSH server. Ensure that you protect the integrity of the downloaded software by applying stricter file permissions.

  1. og in to the SSH client host as the SSH user
  2. Connect to the Oracle Key Vault management console as an SSH admin user or a user with the System administrator role or the privilete to create an endpoint.

    For example: https://192.0.2.254.

    The login page to the Oracle Key Vault management console appears. Do not log in.

  3. Click on the Endpoint Enrollment and Software Download immediately below the Login button. The Enroll Endpoint & Download Software page appears.
  4. In the Enrollment Token field, enter the SSH Server endpoint's enrollment token, and click Submit Token. You saved the enrollment token during the endpoint registration step.
    1. If the token is valid, then a valid token message appears below the Enrollment Token field. The Endpoint Type, Endpoint Platform, Email and Description fields are automatically populated with the values that were entered during endpoint registration.

      If the token is invalid, then an invalid token message appears. Check the token and retry the download procedure.

    2. Click Enroll at the top right corner of the page.
    3. Click on the Endpoint Enrollment and Software Download immediately below the Login button. The Enroll Endpoint & Download Software page appears.
    4. In the Enrollment Token field, enter the SSH Server endpoint's enrollment token, and click Submit Token. You saved the enrollment token during the endpoint registration step.
      1. If the token is valid, then a valid token message appears below the Enrollment Token field. The Endpoint Type, Endpoint Platform, Email and Description fields are automatically populated with the values that were entered during endpoint registration.

        If the token is invalid, then an invalid token message appears. Check the token and retry the download procedure.

      2. Click Enroll at the top right corner of the page.
    5. In the directory window that appears, follow the prompt to save the okvclient.jar endpoint software file.

      You must navigate to the directory where you want to save the file.

    6. Save the file to a secure directory with appropriate permissions in place so that it cannot be read or copied by others.
    7. Verify that the file has been downloaded.

      Note:

      If you did not download the file to the SSH client host, you must use an out-of-band method to copy the file to that system and install it there.

      At this stage, you are ready to install the Oracle Key Vault okvclient.jar software file on the SSH client host.

Install the SSH user's endpoint on the SSH client host

As the SSH user, you install the SSH user's endpoint on the SSH client host using the downloaded endpoint software file okvclient.jar.

Before you install the SSH user's endpoint, ensure that you have JDK 1.5 or later installed, and that the PATH environment variable includes the java executable (in the JAVA_HOME/bin directory). Oracle Key Vault supports JDK versions 1.5, 1.6, 7, and 8. The 64-bit version of Java is required.

To install the SSH user's endpoint onto the SSH client host:
  1. Ensure that you are logged in to the SSH user.
  2. Navigate to a new directory on the SSH client host where you want to deploy the endpoint software.
  3. Move the okvclient.jar file from it’s saved location to this new endpoint directory.
  4. After confirming this directory is empty other than the okvclient.jar file, run the java command as the root user to install the okvclient.jar file.

    For example,

    java -jar okvclient.jar -d /<path_to_EP_directory>/<EP_directory> -v

    In this specification:

    • -d specifies the directory location for the endpoint software and configuration files, in this case /<path_to_EP_directory>/<EP_directory>.
    • -v writes the installation logs to the /<path_to_EP_directory>/<EP_directory>/log/okvutil.deploy.log file at the server endpoint.
  5. When you are prompted for the password, enter:
    • <enter> for the auto-login endpoint or
    • a valid password for the password-protected endpoint
      If you want to create a password-protected endpoint, at minimum enter a password between 8 and 30 characters and then press Enter. For better security, Oracle recommends that you include uppercase letters, lowercase characters, special characters, and numbers in the password. The following special characters are allowed: (.), comma (,), underscore (_), plus sign (+), colon (:), space.
      Enter new Key Vault endpoint password (<enter> for auto-login): Key_Vault_endpoint_password
      Confirm new endpoint password: Key_Vault_endpoint_password

    A password-protected wallet is an Oracle wallet file that store the endpoint's credentials to access Oracle Key Vault. This password will be required whenever the endpoint connects to Oracle Key Vault. It is recommended that you install the endpoint as password-protected as the endpoint has the access to the SSH user's private keys.

16.3.4 Authorize SSH User's Public Key on SSH Server

Before an SSH user can connect to an SSH server using SSH public key authentication, user's public key must be authorzed on the SSH servers that user needs to connect to.

If you are using the Oracle Key Vault for the SSH user key management only, then the user's public key needs to added to the authorized_keys files on different SSH servers individually. You need to coordinate this step with the administrator of respective SSH servers.

As an SSH admin, you download the public key, convert it to the SSH format and share it with the SSH server administrator. The SSH administrator adds the public key to the authorized_keys file of the relevant host user on the SSH server.

Use below steps to download the SSH public key in SSH format:

  1. As an SSH admin, ensure that you have an endpoint setup to use with the RESTful services utility. See, Running Oracle Key Vault RESTful Services Utility Commands.
  2. Get the Unique Identifier of the SSH public key using these steps:
    1. Log in to the Oracle Key Vault management console as an SSH admin.
    2. Select the Reports tab, and then select Reports from the left navigation bar.
    3. Expand on the SSH Reports and click on the SSH Key Metadata Report.
    4. Search and identify the SSH public key of the new SSH user. Click on Key Details. The Object Details page appears.
    5. Copy the value of the Unique Identifier.

  3. Use the RESTful services utility command 'okv managed-object public-key get' with the Unique ID of the public key to download the SSH public key.
    ./bin/okv managed-object public-key get --output_format TEXT --uuid FAB07067-03F5-4F01-BF3F-67CEDCDE0307
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqarY8fRQlhpbtawGyVSC
    LsPrQN4RLWcnzzEo+QIcqRc4/rpVbTs7aEx63MYtheGDQ5V2NPPBYwrZOrb09ETw
    QvkXqZBD+xvAVRc8t8c6wTCvGvMgAkoDzBA7nD7nl0WBd4PVnrkDbAdELQx4DLNW
    lke/XhBeQOCKT2yA31CVDDnMKZElwcKy3G6J3jdO2e3jV5Daj5r8h7RN0f6a9HJO
    8Xmaa61Vj9duTr1SKvLmG1gAwZ2Jzkat6+PgTsKE+3n8Evy+E9YOtvyieXJG/c0V
    GZ3Uwx8HUkqkw5h6nQkCVEjNWabFHDVkGkn1aq9axg1oYJMHPTJszGSmqbfNlo6N
    ZQIDAQAB
    -----END PUBLIC KEY-----

    Redirect the standard output of the above command to a file, say public_key.pub. The downloaded public key is in the PKCS#8 format.

  4. Use the sshkey-gen utility to convert the downloaded public key from the PKCS#8 format to the SSH format that the authorized_keys file accepts.
    ssh-keygen -i -f public_key.pub -m PKCS8
    ssh-rsa 
    AAAAB3NzaC1yc2EAAAADAQABAAABAQCpqtjx9FCWGlu1rAbJVIIuw+tA3hEtZyfPMSj5AhypFzj+ulVtOztoTHrcxi2F4YNDlXY088FjCtk6tvT0RPBC+RepkEP7G8BVFzy3xzrBMK8a8yACSgPMEDucPueXRYF3g9WeuQNsB0QtDHgMs1aWR79eEF5A4IpPbIDfUJUMOcwpkSXBwrLcboneN07Z7eNXkNqPmvyHtE3R/pr0ck7xeZprrVWP125OvVIq8uYbWADBnYnORq3r4+BOwoT7efwS
    /L4T1g62/KJ5ckb9zRUZndTDHwdSSqTDmHqdCQJUSM1ZpsUcNWQaSfVqr1rGDWhgkwc9MmzMZKapt82Wjo1l

    Redirect the standard output of the above command to a file. This file now contains the SSH user's public key in the SSH format.

  5. Share the user's public key with the administrators of SSH servers. These admins will add the public key to the appropriate authorized_keys file.

16.3.5 Connect to SSH Servers using Oracle Key Vault PKCS#11 library

After completing the configuration steps in the Oracle Key Vault and the SSH client host, the SSH user can now initiate the SSH connections using OpenSSH client and Oracle Key Vault PKCS#11 library.

Ensure that OpenSSH client version is 8.1 or higher.

To initiate SSH connections from the SSH client host to the SSH server host:

  1. As an SSH user, login to the SSH client host.
  2. Set OKV_HOME environment variable to the SSH user endpoint's installation directory.
  3. Connect as follows:
    ssh -I $OKV_HOME/lib/liborapkcs.so <ssh_server_user>@<ssh_server_host>
    
    Example:
    ssh -I $OKV_HOME/lib/liborapkcs.so oracle@phoenix
  4. Above command will ask for the endpoint's password with the prompt:
    Enter pin for 'label':

    For the auto-login endpoint, enter NULL. Otherwise, enter the endpoint's password and hit enter.

  5. SSH session is now established.

    Note:

    Use ssh-agent to avoid supplying the PKCS#11 library path and the pin repeateadly. After ssh agent is setup and the pin for the endpoint's PKCS#11 library has been added, you can then execute teh ssh command as usual.
    For example:
    ssh oracle@phoenix

16.4 Oracle Key Vault and SSH Integration

Users can manage both the SSH user's keys and the access to SSH servers with Oracle Key Vault. This setup is ideal since it not only provides the ability to enumerate the SSH user's keys and the SSH server access using those keys, but it also allows for transparent rotation of the SSH user's keys. SSH user's private key can also be marked not extractable which means the private key would never leave the boundary of the Oracle Key Vault deployment.

16.4.1 SSH Administrators Managing both the SSH User's Keys and the SSH Server Access

As an SSH administrator, you can setup the SSH server wallet, the SSH server endpoint, and the OpenSSH configuration on the SSH server as described in the section Controlling access to SSH server centrally with Oracle Key Vault.

The SSH administrator can setup the SSH user's keys as and SSH client endpoint. See Managing SSH User Keys with Oracle Key Vault.

Since the SSH administrator has full control over the SSH user's keys, the SSH administrator can rotate them per policy and also add the SSH user's public keys to the SSH server wallets to grant or revoke access to SSH servers.

16.4.2 SSH Client Managing SSH User Keys and SSH Admin Managing the SSH Server Access

As an SSH administrator, you can setup the SSH server wallet, the SSH server endpoint, and the OpenSSH configuration on the SSH server as described in the section Controlling access to SSH server centrally with Oracle Key Vault.

The SSH users can setup their SSH user's keys and SSH client endpoint. See Managing SSH User Keys with Oracle Key Vault.

The SSH administrator can add the public keys from the SSH user's public keys wallet to the SSH server wallets to grant or revoke access to SSH servers. The SSH administrator cannot rotate the user's keys on their own and would need to notify the SSH user to perform key rotation. But, the SSH administrator will be able to revoke access from the SSH server hosts if the keys are not rotated on time.

16.5 Migrating Existing SSH Deployments to Oracle Key Vault

Administrators can migrate their SSH deployments for SSH user key management or managing access control of SSH servers or both.

To migrate the access control of SSH server into Oracle Key Vault:

  1. Identify the SSH users on each SSH server host.
  2. For each SSH user identified on the SSH server host, create an SSH server wallet.
  3. For each SSH server create an SSH server endpoint.
  4. Grant the SSH server endpoint read only rights to SSH server wallet.
  5. Deploy the SSH endpoint on the SSH server host.
  6. Upload the public keys (from the SSH server host user's authorized_keys file) as SSH keys into their corresponding SSH server wallet on the Oracle Key Vault server.
  7. Setup the SSH server mapping file.
  8. Setup the OpenSSH daemon to look at the SSH server endpoint lookup script inside the deployed SSH endpoint environment.
  9. Optionally limit the authorized_keys file use on the SSH servers.

To migrate SSH user key management:

  1. Identify the SSH users you want to migrate to Oracle Key Vault.
  2. Create a regular endpoint and general wallet for SSH users.
  3. Deploy the regular endpoint on SSH client host.
  4. Use the REST APIs to register the public-private keys of all SSH users as SSH keys into their corresponding general wallets on the Oracle Key Vault server.
  5. Use the PKCS#11 library when initiating an ssh connection.
    ssh -i $OKV_HOME/lib/liborapkcs.so oracle@phoenix

    If you are migrating both the access control of SSH servers and the SSH user key management to Oracle Key Vault, then do it in two phases. First migrate the access control of SSH server into Oracle Key Vault. Once every SSH server that needs migration is centrally managed in Oracle Key Vault then migrate the SSH user key management into Oracle Key Vault.

16.6 Guidelines for OpenSSH SSHD Configuration

When you use Oracle Key Vault to securely manage SSH user keys or control access to SSH servers, the time to establish an SSH connection depends on multiple factors.

Some of the factors that determine the performance characteristics of establishing an SSH connection are:
  • SSH user keys are managed locally or in an Oracle Key Vault.
  • The number of SSH user keys in the user’s general wallet.
  • SSH server access is controlled through the authorized_keys file or from the Oracle Key Vault.
  • Number of concurrent SSH connection requests.
Additionally, one or both the SSH clients or SSH servers may connect to Oracle Key Vault, adding a network delay during the SSH authentication process.

Review the following OpenSSH SSHD configuration parameters and modify them as necessary:

LoginGraceTime

  • The server disconnects after LoginGraceTime time if the user has not successfully logged in.
  • If the SSH user’s endpoint has access to multiple SSH keys, then openssh makes an attempt to authenticate each key, one at a time. You should set the LoginGraceTime to a value that is sufficient for the authentication attempts to be made using all available keys for the user.
  • Oracle recommends that you maintain a small number of keys for each user. Move the old, unused keys to other wallets.

MaxAuthTries

  • Specifies the maximum number of authentication attempts permitted per connection.
  • If the SSH user’s endpoint has access to multiple SSH keys, then openssh makes an attempt to authenticate using each key, one at a time. Each offered key counts as one attempt. An SSH connection fails if authentication remains unsuccessful after MaxAuthTries authentication attempts. You should configure MaxAuthTries parameter to a value larger than the number of SSH keys accessible to SSH user’s endpoint.
  • Oracle recommends that you maintain a small number of keys for each user. Move the old, unused keys to other wallets.

MaxStartUps

  • Specifies the maximum number of concurrent, unauthenticated connections to the SSHD. Additional connections will be dropped until authentication succeeds or the LoginGraceTime expires for a connection.
  • You should set MaxStartUps considering the expected number of concurrent connections in your environment.

16.7 Reports

Oracle Key Vault offers several reports that you can use to check Secure Shell (SSH) user keys, SSH server access control configuration and also to track the SSH user activity.

16.7.1 Viewing SSH Reports

All users can view the SSH reports.

Oracle Key Vault offers several reports that you can use to centrally manage the configuration of SSH user keys, their authorization to access SSH servers, and monitor the SSH server host access. These include:

16.7.2 SSH Key Details Reports

The SSH Key details reports group includes the SSH Key Metadata Report and SSH Key Usage Report.

Oracle Key Vault Secure Shell (SSH) Details reports consists of the following reports:

  • SSH Key Metadata Report
  • SSH Key Usage Report

SSH Key Metadata Report

This report shows the metadata for SSH public and private keys including owner, key length, expiration, and wallet membership.

You use this report to gain complete visibility of the SSH keys inventory and ensure that SSH key management best practices and enterprise specific policies are uniformly applied.

You can use this report to:
  • identify weaker keys - keys with key size smaller than what your enterprise security policy may require
  • identify keys that are expiring soon and rotate them before they expire to avoid any disruption
  • identify keys that are likely unused if they are not a member of any wallets


SSH Key Usage Report

This report shows all operations on currently managed SSH keys by endpoints and the users.

You use this report to:
  • monitor usage of the SSH keys to identify any suspicious activity or any tampering to the key authorization or key attributes.
  • identify usage pattern and unused keys. For example:
    • a user may have multiple SSH keys but some of the keys may not be in use anymore.
    • a user may have both public and private keys in Oracle Key Vault but only private key access is shown, indicating use of local authorized_keys files on SSH servers.


16.7.3 SSH Server Access Management Reports

Oracle Key Vault offers SSH Server Access Management reports to view the authorized SSH user who can access the reports.

Oracle Key Vault SSH Server Access Management reports consists of the following reports:

  • SSH Server Authorization Report
  • SSH Server Access Report
  • SSH Server Wallet Report

SSH Server Authorization Report

This report shows SSH servers and the SSH users who are authorized to access them. It is used to review who has access to SSH servers.

You use this report to:
  • review the authorization granted to SSH users to access the SSH Servers through their pubic keys.

    This will help you ensure that access is granted to only those who need it and identify any unintended or unexpected authorization.

  • identify left-over access grants, such as from when an employee leaves the organization or changes his/her role.


SSH Server Access Report

This report shows attempts to access SSH servers using SSH users' public keys. It is used to assess who is accessing the SSH servers.

As part of SSH user authentication, fingerprint of the public key offered by the client, the SSH host user and the wallet that the SSH server endpoint looks up to determine access are recorded. The information shown in the SSH User column is derived from the SSH public key metadata if it exists in system. The SSH User column will show the value 'Unknown' If the SSH public key that is used to access an SSH server is managed outside of Oracle Key Vault, that is SSH user information associated with the SSH public key is unavailable within Oracle Key Vault.

A user trying to establish an SSH connection may have more than one public key. This report shows attempts made using each public key to authenticate the user. If an SSH user has multiple public keys and some of these public keys are not authorized to access the SSH server, then you may see entries with failed access attempts before an entry for the successful access attempt for that user.

You use this report to:
  • monitor the SSH server access to ensure that SSH servers are accessed by only authorized users. This information is useful for the forensic analysis of a security incident.
  • review the failed attempts to access an SSH server to determine if these attempts were legitimate or otherwise.


SSH Server Wallet Report

This report shows SSH server wallets that authorize the access of SSH servers as SSH server host users. It is used when provisioning new SSH users and/or new SSH servers.

You use this report to:
  • determine the SSH server wallets where SSH public key of a newly provisioned user needs to be added.
  • determine the SSH server wallets that a newly provisioned server should use if the new server follows the SSH access configuration of other servers in the enterprise.
  • get the enterprise-wide view of the SSH server wallets and the SSH servers for which they authorize access. You can use an SSH server wallet to authorize SSH access on multiple servers.


16.7.4 SSH User Private Key Management Reports

Oracle Key Vault offers SSH User Private Key Management reports to view the SSH user who can access the private keys.

Oracle Key Vault SSH User Private Key Management reports consists of the following reports:

  • SSH Private Key Authorization Report
  • SSH Private Key Usage Report

SSH Private Key Authorization Report

This report shows the endpoints and users who are authorized to use SSH private keys and also how their access is granted. It is used to review who has access to SSH private keys.

You use this report to:
  • review and audit endpoints and users who are granted access of the SSH private keys.
  • identify and limit use of shared private keys. An SSH private key is meant for a specific user or an endpoint. Any temporary sharing of SSH private keys must be removed as soon as the business need is completed.


SSH Private Key Usage Report

This report shows the use of SSH user private keys by endpoints and users. It is used to assess changes to the SSH users private keys and review their access.

This report includes the activity information from the use of the SSH private keys to access SSH servers as well as all operations that are performed on them.

You use this report to:
  • review and audit the use of SSH private keys. You can review access patterns of the private key and identify unusual activity like use of a user's private key when user is away on a vacation or fetch of a user's private key by an unexpected endpoint.
  • identify any unusual changes that are made to SSH private keys. For example, the extractable attribute of an SSH private key is modified so that the key can leave the Oracle Key Vault boundary. Such changes could be a cause of concern and must be reviewed. You should immediately rotate SSH keys whose integrity may be suspect.