Overview

Information about how Keeper Secrets Manager works.

Common Functionality

Additional details about aspects of Keeper Secrets Manager which are used across many integrations and SDKs.

Additional Resources

Information about other Keeper systems that impact Secrets Manager users.

System Architecture

In Keeper's model, all your servers, CI/CD pipelines, developer environments and source code pull secrets from a secure API endpoint.

The client device retrieves encrypted ciphertext from the Keeper cloud and the secrets are decrypted locally on the device (not on the server). Each secret is encrypted with a 256-bit AES key, and then encrypted again by another AES-256 Application Key.

In addition to Zero-Knowledge encryption, every request to the server is additionally encrypted with an AES-256 Transmission Key on top of TLS to prevent MITM or replay attacks. This multi-layered cryptography is handled transparently using our client-side SDKs which are easy to integrate into any environment.

High Availability and Local Cache

Keeper's infrastructure serves requests for millions of users and tens of thousands of Enterprise customers every day.

Keeper Secrets Manager benefits from the existing Keeper platform architecture in addition to an optional offline caching mechanism in all Secrets Manager SDK endpoints.

Each client device platform provides an optional local caching components. If the Keeper endpoint is unavailable, the Client Device will pull the last requested Secrets from a local encrypted cache.

Encryption Model

More details about the security and encryption model are available here.

Secrets Manager Structure

In order to organize and maintain access to Secrets, Keeper Secrets Manager uses structures called Applications and Clients.

Read below about how each of these items function in Secrets Manager.

Secret

Secrets are stored as records in the Keeper Vault and are typically stored as attachments or fields in these records.

Any record or shared folder from the vault can be shared with an Application.

Application

Keeper Secrets Manager Applications are assigned to specific secrets or shared folders. The application is a container of permissions, client devices, audit trail, and history. An application can only decrypt the records assigned.

Keeper recommends implementing the principle of least privilege, ensuring client devices only have access to the records they need. Although the user of the Vault can have unlimited secrets, Keeper recommends sharing up to 500 records per application for optimal performance.

An example of an Application would be a Production Github Actions pipeline or Jenkins server.

Client Device

A Client device is any endpoint that needs to access secrets associated with an Application. This can be a physical device, virtual device, or cloud-based device. A client device can also be identified by any software application running in the cloud or CI/CD tool.

Each Client device has a unique key to read and access the secrets.

Clients adhere to the following:

• One Time Access Tokens used for initialization that expire after 24 hours

• IP Address lock (optional)

• Access expiration (optional)

An example of a Client Device would be a development machine, Terraform script or a Github Actions instance. At least one client device is required to access secrets that are associated with an Application. Multiple client devices can be associated with the same Application.

Configuration

A Secrets Manager "Configuration" is a set of tokens that includes encryption keys, client identifiers and destination server information used to authenticate and decrypt data from the Keeper Secrets Manager APIs.

Secrets Manager configurations are created from One Time Access Tokens and have a one to one relationship with client devices.

A configuration can be stored as a text file with JSON, or it can be encoded into a single line string.

Overview

Keeper Secrets Manager is a Zero Knowledge platform. Encryption and decryption of secrets takes place locally on the Client Device running the ksm application, CI/CD plugins or the developer SDK.

Client Device Configuration File

The local configuration file (e.g. keeper.ini) for the ksm application contains the following format:

[_default]
clientkey = XXX
clientid = XXX
privatekey = XXX
appkey = XXX
hostname = US
serverpublickeyid = 10

[_config]
active_profile = _default

This file should be protected on your local filesystem. It contains keys can authenticate with the Keeper API and decrypt secrets that have been explicitly associated with the Application and Client Device.

Configuration File Fields

Authentication and Encryption

The Client Device only authenticates with the hashed One Time Access Token one time. The client signs the payload and registers a Client Device Public Key with the server on the first authentication. After the first authentication, subsequent requests are signed with the Client Device Private Key.

API requests to the Keeper Cloud are sent with a Client Device Identifier and a request body that is signed with the Client Device Private Key. The server checks the ECDSA signature of the request for the given Client Device Identifier using the Client Public Key of the device.

The Client Device decrypts the ciphertext response from the server with the Application Private Key, which decrypts the Record Keys and Shared Folder Keys. The Shared Folder Keys decrypt the Record Keys, and the Record Keys decrypt the individual Record secrets.

Protecting Access through IP Lockdown

By default, when creating a Client Device profile, IP lockdown is enabled.

For example:

My Vault> secrets-manager client add --app MyApplication

Successfully generated Client Device
====================================

One-Time Access Token: PqwnPcUo2Wc3dv3zvu_zC3nHhNAbNWDfooECWMBTRJM
IP Lock: Enabled
Token Expires On: 2021-08-17 21:00:28
App Access Expires on: Never

The client which initializes using this token will be locked on IP. To disable IP lockdown, an additional parameter must be specified, for example:

My Vault> secrets-manager client add --app MyApplication --unlock-ip

It is recommended to allow IP lockdown, unless you are deploying to an environment which has a dynamic WAN IP.

Additional Information

Keeper utilizes best-in-class security with a Zero-Knowledge security architecture and Zero-Trust framework. Technical documentation about Keeper's Zero-Knowledge encryption model can be found at the links below:

Keeper Encryption Model

Secrets Manager Encryption Model

Security Disclosure Page

Keeper is SOC 2 Type 2, ISO27001 certified. Customers may request access to our certification reports and technical architecture documentation under mutual NDA.

Vulnerability Disclosure Program

Keeper has partnered with Bugcrowd to manage our vulnerability disclosure program. Please submit reports through https://bugcrowd.com/keepersecurity or send an email to security@keepersecurity.com.

About

Keeper Secrets Manager uses a "One Time Access Token" to perform a key exchange and initialize a new client device that will access the Secrets Manager API. Each client device should be initialized with its own, individual One-Time Access Token.

One time access tokens can be generated using Keeper Commander, or in the Keeper Vault. One time access tokens are generated when a client device is created.

The purpose of the One Time Access Token is to create a "Configuration", which is made up of several encryption keys and identifiers. Configurations are stored either locally on the client device or within the target CI/CD platform.

Using Commander To Generate a Token

1. Create an Application

Use secrets-manager app create to create a new Secrets Manager application

My Vault> secrets-manager app create DevOps
Application was successfully added

secrets-manager app list can be used to see a list of available applications.

My Vault> secrets-manager app list

List all Secrets Manager Applications

Title              UID
-----------------  ----------------------
DevOps             fe6mv_ZBLqca35dBUTdNeQ
Examples           Xym5lhpSidvtk9VlmV_3dQ
Github Actions     L5FqK5DUJhxeCXp50nSkuw
Jenkind            R2jMVW_QwL3FsCJziotpLQ

2. Associate the Application to Shared Folders or Records

You need to assign Shared Folders or records with the application in order to give it access to the vault records.

From Commander, use the following command to share with an application:

secrets-manager share add --app <APPLICATION NAME> --secret <FOLDER OR RECORD UID>

Optionally use the --editable flag to give the application edit permissions.

In the example below, "XXX" would be replaced by a record or shared folder UID

My Vault> secrets-manager share add --app DevOps --secret XXX --editable

Successfully added secrets to app uid=XXX, editable=True:
        RpdmKFgF5lpsaID3TcHu8A Shared Folder

3. Create a Client Device

An application is made up of one or more Client Devices. At least one client device is required to access vault records.

Use the command secrets-manager client add --app <APPLICATION NAME> to create a new client device.

Optionally, --name <NAME> can be used to set a client device name and --unlock-ip can be used to allow any authenticated device to connect. By default, access is locked down based on external IP address of the client device.

My Vault> secrets-manager client add --app DevOps --name server1

Successfully generated Client Device
====================================

One-Time Access Token: US:19-V--cbg8P-o9OVDzMl_hWnrt-QE1eAMQHgSkQMUi0
Name: server1
IP Lock: Enabled
Token Expires On: 2021-10-01 11:14:18
App Access Expires on: Never

Note the One-Time Access Token is displayed when the client device is created.

Copy the one time access token from the output and use it to initialize a device from the Keeper Secrets Manager SDKs or integrations. Once the token is used on a target device, it cannot be used again. You can generate as many client devices as you need to access the records associated to the application.

Using The Keeper Vault to Generate a Token

With a New Application

1. Navigate to Secrets Manager

In the Keeper Vault, select Secrets Manager from the navigation menu.

2. Create a New Application

To create a new Secrets Manager Application and generate a one time token, first select "Create Application" from the Secrets Manager tab. The "Create Application" button appears on the top right side of the page, or in the middle if no Applications currently exist.

In the Add Application Form, create a name for the new application

Use the dropdown to select which shared folder to give the application access to. Multiple Folders can be selected.

You can choose to give this application read or edit permissions using the dropdown.

Optionally, check "Lock external WAN IP Address of device for initial request" to restrict the application's first client device to the first IP Address that connects to it.

3. Generate a One Time Access Token

Once you've configured the application, click "Generate Access Token" to generate the first client device and receive a one time token.

Copy the one time access token from the output and use it to initialize a device from the Keeper Secrets Manager SDKs or integrations. Once the token is used on a target device, it cannot be used again. You can generate as many client devices as you need to access the records associated to the application.

With an Existing Application

1. Navigate to Secrets Manager

In the Keeper Vault, select Secrets Manager from the navigation menu.

2. Create a New Client Device on an Existing Application

To create a new client device and generate new one time tokens on existing Secrets Manager applications, first select the application to use from the list in the Secrets Manager tab.

Selecting an application opens the details view, which shows the folders and records that this application has access to.

In order to create a new client device, first navigate to the "Devices" tab, and then click "Edit" and then the "+ Device" button.

In the Add Device form, select a name for the new device. Optionally you can check "Lock external WAN IP Address of device for initial request" to restrict the client device to the first IP Address that connects to it.

3. Generate a One Time Access Token

Click "Generate Access Token" to create the client device and see the one time token.

Copy the one time access token from this screen to use it with Keeper Secrets Manager SDKs and integrations, you will not be able to access this token in the future (but you can create additional client devices to generate more tokens).

Generating Configurations

Some of the 3rd party Keeper Secrets Manager integrations require pre-built configurations, instead of creating the configuration from a one-time access token.

The next section reviews how to create a Secrets Manager Configuration.

About

Each Keeper Secrets Manager SDK and integration uses a "configuration" to store connection tokens, encryption keys, identifiers and domain information used to authenticate and decrypt data from the Keeper Secrets Manager APIs.

Secrets Manager configurations are created from One Time Access Tokens and have a one to one relationship with client devices.

Configuration Uniformity

All Keeper Secrets Manager SDKs and integrations use the same configuration format. Raw configurations are in JSON format, though some integrations accept base64 format.

Creating a Secrets Manager Configuration

In the Keeper Vault

A Secrets Manager configuration can be created in the Keeper Vault when creating a new Secrets Manager device.

First navigate to the Secrets Manager tab, and select an Application from the list.

Then, select the "Devices" tab in the right-hand application pane, and click "Edit" to go into edit mode.

From the edit view, you can click "Add Device" to create a new Secrets Manager device to the application.

The Add Device menu will appear. Enter a name for this device, and then select "Configuration File" from the method dropdown.

After Configuration File is selected, you are given options for receiving the configuration. You can choose to generate a configuration in Base64 or json format, and download the configuration to a file, or copy it to the clipboard.

Most Secrets Manager integrations use a base64 string, but you may need a json file in some circumstances.

When ready, click the download or copy button to receive you configuration. Note that when you do this the first time, the device will be created. You are able to download or copy the configuration multiple times.

Using a SDK/Integration

Many Keeper Secrets Manager SDKs and Integrations support creating their own configuration file. You need to pass a One Time Access Token, and the configuration is created automatically.

SDK Example

Below is an example of how to use the Python SDK to create a configuration file. The configuration is created when Secrets Manager is initialized with a One Time Access Token.

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('config.json')
)

In this example, the configuration is being saved to a file named "config.json"

Integration Example

Below is in example of using the Keeper Secrets Manager Jenkins Plugin.

The Jenkins plugin takes a One Time Access Token to initialize and creates a configuration automatically behind-the-scenes. In this example, simply enter a One Time Access Token in the form and click 'OK'.

Using a CLI Tool

A Secrets Manager configuration can be initialized from a One Time Access Token using the Secrets Manager CLI as well as the Commander CLI tools. Some Keeper Secrets Manager integrations require a pre-initialized configuration and you will need to use the CLI tools to create a configuration in these cases.

Secrets Manager CLI

The Secrets Manager CLI (KSM) tool can initialize a One Time Access Token and create a configuration.

To do this, run the init command

# initialize a configuration in JSON format and display it
$ ksm init default <One Time Access Token>

# initialize a configuration in k8s format and display it
$ ksm init k8s <One Time Access Token>

# initialize a JSON configuration and save it to a file
$ ksm init default --plain <One Time Access Token> > <FILENAME>

# initialize a configuration in JSON and display it
$ ksm init default US:KBChlYeZ15wLzvhLVXmT61euw0DJO0cTVfkD-b-qesw

# initialize a configuration in k8s format and display it
$ ksm init k8s US:KBChlYeZ15wLzvhLVXmT61euw0DJO0cTVfkD-b-qesw

# initialize a configuration and save it to a file
$ ksm init default --plain US:KBChlYeZ15wLzvhLVXmT61euw0DJO0cTVfkD-b-qesw > "ksm-config.json"

Commander CLI

Commander CLI can be used to initialize a One Time Access Token and create Secrets Manager configuration.

Use the secrets-manager client add Command with --config-init to create a configuration. Configurations can be created in json or base64 formats, or in integration-specific formats in some cases. (see the integrations documentation for more information on what format each integration accepts)

my vault> secrets-manager client add --app <APP NAME> --config-init <FORMAT>

# create a json configuration
secrets-manager client add --app MyApp --config-init json --unlock-ip

# create a base64 configuration
secrets-manager client add --app MyApp --config-init b64 --unlock-ip

# create a Kubernetes configuration
secrets-manager client add --app MyApp --config-init k8s --unlock-ip

About

Keeper notation is used by Keeper Secrets Manager SDKs and integrations to query fields in Keeper records. To view the different types of records and the field names available, click here.

Notation

"fields": [
    { "type": "name", "value": [ 
        {"first:": "John", "last": "Doe"},
        {"first:": "Jane", "last": "Doe"} ]
    },
    { "type": "phone", "value": [
        {"number": "555-5555555", "ext": "55"}, 
        {"number": "777-7777777", "ext": "77"} ]
    }
]

[
    {"number": "555-5555555", "ext": "55"}, 
    {"number": "777-7777777", "ext": "77"}, 
    {"number": "888-8888888", "ext": "", "type": "Home"}, 
    {"number": "999-9999999", "type": "Work"}
]

[
  {"number": "123-456-7890", "type": "work"},
  {"number": "555-555-5555", "type": "home"}
]

Fetching Records by Name

Keeper Secrets Manager SDKs support Keeper Notation fetching of records by record name.

Escaping notation characters

If any part of the record contains "/" "\" "[" or "]" you will need to escape that character with a backslash. These special characters are used by notation as internal section and index delimiters and need to be escaped if present in the record title, field label or file name.

Examples:

Title: "Twitter Login [Marketing]" keeper://Twitter Login \[Marketing\]/field/password URL custom field with Label: "/. links" keeper://My Slashdot Links/custom_field/\/.links[] (all links) keeper://My Slashdot Links/custom_field/\/.links[1] (2nd link only) File name: "creds[2].crt" keeper://My \/. Credentials/file/creds\[2\].crt

Using Name to Simplify Environment Switching

With the Keeper Notation record title fetching capability, it is possible to create your notation queries once, and use them across different build environments by utilizing different Secrets Manager Applications.

Example:

In this example, two shared folders have been created. One for developer environments and one for production. Inside each folder there are identically named records. These records have the same name, but different credentials stored in them.

Each shared folder will be associated with a different Secrets Manager application.

In the associated Secrets Manager integration, use notation to fetch the credentials. For example: keeper://MySQL Creds/field/password In integrations used for development builds, use the Secrets Manager application associated to the Dev folder (in this case "Development Environment"). Then to build for production, simply change the associated Secrets Manager application to "Production Environment" no change in code or scripts needed.

Keeper Secrets Manager generates several events in the Advanced Reporting & Alerts Module. These events are available for analysis in several places including:

• Keeper Admin Console (Learn More about the Event Reporting & Alerts Module): https://docs.keeper.io/enterprise-guide/event-reporting

• SIEM Export to Splunk and other common providers: https://docs.keeper.io/enterprise-guide/event-reporting/splunk

• Webhooks such as Slack and Teams: https://docs.keeper.io/enterprise-guide/webhooks

• Commander audit-report CLI command and audit-log CLI command

Secrets Manager Events

Below is the list of events generated from Secrets Manager. "Application" refers to the Secrets Manager Application which is associated to a record or folder in the Keeper Vault.

For a list of all events, visit: https://docs.keeper.io/enterprise-guide/event-reporting

Field Types

Field types defined how a field's data is stored. Field types are used in the default record type and user created custom records.

accountNumber

A string value. There is no validation of the value.

address

A dictionary value containing:

• street1 - Street address 1

• street2 - Street address 2

• city - City

• state - State

• zip - Postal code

• country - ISO3166 Alpha-2 country code

None of the keys are required.

Example:

{"street1": "100 Main Street", "city": "Town", "state": "RI", "zip": "55555",
    "country": "US"}

bankAccount

A dictionary value containing:

• accountType - Checking | Savings | Other

• otherType - Description of the other account type

• routingNumber - The bank routing number

• accountNumber - The account number

None of the keys are required.

Example:

{"accountType": "Checking", "routingNumber": "123456", "accountNumber": "55555555"}

birthDate

A epoch milliseconds value. Depending on method of creation, ie using a helper modules, an ISO8601 value may be used. The ISO8601 value will be converted to an epoch millisecond value.

cardRef

An array of payment card record uids.

Examples:

["OlLZ6JLjnyMOS3CiIPHBjw", "XJ2VISBJ3JAeCwU_YGAXYg"]

date

A epoch milliseconds value. Depending on method of creation, ie using a helper modules, an ISO8601 value may be used. The ISO8601 value will be converted to an epoch millisecond value.

email

A string value, normally for a user's email address. There is no validation of the value.

expirationDate

A epoch milliseconds value. Depending on method of creation, ie using a helper modules, an ISO8601 value may be used. The ISO8601 value will be converted to an epoch millisecond value.

fileRef

An array of file UIDs. When a file is attached to a record, that files UID will appear in this array.

host

A dictionary value containing:

• hostName - Hostname or IP

• port - Remote port

None of the keys are required.

Example:

{"hostName": "localhost", "port": "22"}

A dictionary value containing:

• publicKey - Public key

• privateKey - Private key

None of the keys are required.

Example:

{"publicKey": "PUBLIC KEY", "privateKey": "PRIVATE KEY"}

licenseNumber

A string value. There is no validation of the value.

login

A string value, normally the user's login. There is no validation of the value. Many Keeper related services will look for a field of this type for the login value.

multiline

A string value, normally for text that has line feed. There is no validation of the value.

name

A dictionary value containing:

• first - Person's first name

• middle - Person's middle name

• last - Person's last name

None of the keys are required.

Example:

{"first": "John", "middle": "Unknown", "last": "Smith"}

note

A string value that allow for multiline. The value is masked. There is no validation of the value.

otp

One time password URL for TOTP.

oneTimeCode

One time code URL for TOTP.

password

A string value. There is no validation of the value. Many Keeper related services will look for a field of this type for the password value.

paymentCard

A dictionary value containing:

• cardNumber - A payment card number

• cardExpirationDate - MM/YYYY expiration.

• cardSecurityCode - The security code

Example:

{"cardNumber": "5555 5555 5555 5555", "cardExpirationDate": "01/2023",
    "cardSecurityCode": "123"}

phone

An array of phone dictionaries. Each phone dictionary contains the following key/values:

• region - The country code number

• number - Normal phone number

• ext - Extension

• type - Mobile | Home | Work

None of the keys are required.

Example:

[
    {"region": "+1", "number": "555-555-5555", "ext": "1234", "type": "Work"},
    {"number": "555-555-6666", "type": "Mobile"}
]

pinCode

A string value. There is no validation of the value.

secret

A string value. This type of field is normally masked. There is no validation of the value.

securityQuestion

A dictionary value containing:

• question - The security question

• answer - The answer to the security question

Example:

{"question": "What Number?", "answer": "42"}

text

A string value. There is no validation of the value.

url

A string value, normally a web URL. There is no validation of the value.

Default Record Types

The following are the default record types provided by Keeper and the fields within the record type. Record types contain a collection of field types for the standard fields. Custom fields are not defined by a record type.

address (Address)

bankAccount (Bank Account)

bankCard (Payment Card)

birthCertificate (Birth Certificate)

• name - First Name, Middle Name, Last Name

• birthDate - Date of Birth

contact (Contact)

databaseCredentials (Database)

driverLicense (Driver's License)

encryptedNotes (Secure Note)

file (File Attachment)

This record is created when a file is attached to another record. The record UID will be attached to the record via the fieldRef field type.

Currently attaching files to records across all SDK is not finished. Content to be added.

healthInsurance (Health Insurance)

login (Login)

membership (Membership)

passport (Passport)

photo (Photo)

This record is created when a photo is attached to another record. The record UID will be attached to the record via the fieldRef field type.

Currently attaching photos to records across all SDK is not finished. Content to be added.

serverCredentials (Server)

softwareLicense (Software License)

ssnCard (Identity Card)

sshKeys (SSH Key)

Custom Record Types

Custom record types can be used with the Secrets Manager.

Keeper Commander can be used to get the schema for the custom record type.

My Vault> rti --format json -lr "My Custom" --output my_record_type.json
[
  {
    "recordTypeId": 18,
    "content": "{\"$id\":\"My Custom\",\"categories\":[\"login\"],
        \"description\":\"SSH key template\",\"fields\":
           [{\"$ref\":\"login\"},
            {\"$ref\":\"keyPair\"},
            {\"$ref\":\"password\",\"label\":\"passphrase\"},
            {\"$ref\":\"host\"},
            {\"$ref\":\"fileRef\"}]}"
  }
]

Based on the SDK being used, the JSON may be imported allowing the custom record to be used with any helper tools.