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 and have a one to one relationship with .

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

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 .

Overview

Information about how Keeper Secrets Manager works.

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:

This file must be protected on the 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.

Protection of Configuration Files

Keeper provides several methods of configuration file protection through 3rd party secrets storage mechanisms including:

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:

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

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 is SOC 2 Type 2, ISO27001 certified, FedRAMP and StateRAMP Authorized . Customers may request access to our certification reports and technical architecture documentation at Center.

Vulnerability Disclosure Program

Keeper has partnered with Bugcrowd to manage our vulnerability disclosure program. Please submit reports through or send an email to [email protected].

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 , or in the . One time access tokens are generated when a client device is created.

Overview

After creating a Keeper Secrets Manager (KSM) Application, you have the option to share it with other end users within your organization. Shared users gain access to the features and resources within the application, including the ability to view secrets, manage devices and gateways, and configure PAM record types using the associated Keeper Gateway.

Sharing enables teams to collaborate securely while maintaining strict access control through Keeper’s zero-knowledge architecture.

Prerequisites

Prior to proceeding with this guide, ensure that you have created a KSM application. KSM applications can be created from your Vault or on Commander, for step-by-step instructions:

Sharing KSM Applications

To share the KSM application:

1. Select the KSM Application you want to share

2. Edit the KSM Application by clicking edit

3. Navigate to the "Users" tab

4. In the search bar, enter the user’s email address

User Permissions

When sharing a KSM application with other users, the following permissions can be assigned:

Sharing Implications

Shared Folders

Shared folders assigned to a KSM application are accessible by the devices and gateways associated with the application. When sharing a KSM application with another user, if the user does not already have access to the shared folders associated with the application, those folders will be automatically shared with the user.

The level of access the user receives to these shared folders depends on their assigned role in the application:

• If the user is added as a "Member":

  • The user receives the "No User Permissions" shared folder permissions

If the user already had access to any of the shared folders before being added to the KSM application, their existing folder permissions remain unchanged and are not overwritten.

Records

Records can be directly assigned to a KSM application via Keeper Commander secrets-manager app share command.

When sharing a KSM application with another user, if the user does not already have access to the records associated with the application, those records will be automatically shared with the user. The level of access the user receives to these records is "View Only".

Note: Adding individual records to a KSM application requires using Keeper Commander.

Removing a user from the KSM application

Removing a user from the KSM application does not revoke their permissions from the shared folders. Folder access must be manually removed if desired.

Sharing KSM Applications via Commander

KSM Applications can also be shared on Commander using the secrets-manager app share command. For more information, visit this .

Sharing Keeper Gateways

Gateways are associated with KSM applications. When you share a KSM application with another user, the associated Keeper Gateway is also shared. For more information, visit this .

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 theto create a configuration file. The configuration is created when Secrets Manager is initialized with a One Time Access Token.

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.

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 tool can initialize a One Time Access Token and create a configuration.

To do this, run the init command

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 for more information on what format each integration accepts)

About

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

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:

• Commander CLI command and 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:

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

None of the keys are required.

Example:

bankAccount

A dictionary value containing:

• accountType - Checking | Savings | Other

• otherType - Description of the other account type

• routingNumber

None of the keys are required.

Example:

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:

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:

A dictionary value containing:

• publicKey - Public key

• privateKey - Private key

None of the keys are required.

Example:

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

None of the keys are required.

Example:

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

Example:

phone

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

• region - The country code number

• number - Normal phone number

• ext

None of the keys are required.

Example:

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:

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.

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