Working with External Keystores

Introduction

CORE allows expanding the boundaries of a partition by attaching to it cloud keystores and on-premises HSMs.

We use the term external keystore to indicate a cloud keystore or on-premises HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing when the description applies to them both.

Deployment Options

CORE uses service architecture to implement interworking with the cloud keystore providers and on-premises HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing vendors. Each keystore has a dedicated service to handle interaction with the keystore. Such service may be:

1. Coupled with CORE Server software and installed automatically during the CORE deployment.
2. Deployed separately. Such services are tagged with the "deployed externally = true" setting.

CORE applies the following rule regarding these services:
- All cloud keystore services are coupled with CORE service software.
- Contrastingly, all HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing keystore services (HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing Connect) are "deployed externally".

Capabilities

CORE permits many-to-many relationships between partitions and external keystores:

• A partition may attach to itself many external keystores.
• Multiple partitions may be linked to the same external keystore.

CORE applications may generate, import, and use the linked keys using CORE UIDs or key names. Yet:

• Only the external keystores may perform cryptographic operations using these keys.
• The crypto capabilities of the linked keys depend on the capabilities provided by the vendor's API.

To summarize these capabilities and for configuration quickstarts, click the link in the CORE Specifications column.

Cloud keystore	SDK name	SDK version	CORE specification
AWS KMSKey Management System	aws-java-sdk-kms	1.11.682	AWS KMS
Azure Key Vault	azure-keyvault	1.2.4	Azure Key Vault
GCP KMSKey Management System	google-cloud-kms	1.43.0	Google Cloud KMS

On-premises HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing vendor	HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing model	HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing client version	CORE specification
Thales	Safenet Luna	7.4	HSM - Luna
Entrust (nCipher)	nShield Connect HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing	12.71.0	HSM - nCipher

Prerequisites

To attach an external keystore to the CORE partition, the following prerequisites must be met:

• Partition settings.

The partition must be qualified to attach external keystores - it must be created with the allow_keystores capability. For example, ucl partition create --allow_keystores. This capability has the following properties:

• Permanent: It cannot be changed once the partition is created.
• Upgraded systems: It cannot be applied to the existing partitions.
• FIPSFederal Information Processing Standards - standards developed by the United States federal government for use in computer systems by non-military government agencies and government contractors: This capability applies to new partitions that are allowed to operate in non-FIPS modeUKC system advanced execution mode that hasn't yet received the FIPS certification.
• Keystore Credentials.
  

 To attach an external keystore to a partition, the partition's SOSecurity officer - UKC partition administrator role. must obtain the necessary credentials:

• for cloud keystores, it is usually the organization's service account credentials in the cloud.
• for on-premises HSMs, it is usually the user credentials that allow generating and using key material.

Note
Users of a partition linked to an external keystore share the identity and privileges granted to their partition.
To control a partition's user access to key material in an external keystore, use CORE IAM.

In addition, certain features and keystores may require:

• Deployment of docker containers designated to provide the required function.
• Deployment of external agents, such as in the case of the HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing Connect.

Keystore Service Settings

Cloud Keystore Service Settings

To attach a cloud keystore to a partition, the partition's SOSecurity officer - UKC partition administrator role. must specify the cloud keystore and provide service account credentials that authorize accessing this keystore:

• Access key ID - Service account ID that allows access to the external keystore.
  
  - Mandatory for AWS and Azure.
  
  - Not applicable for GCP.
• Secret key - mandatory. The secret part of the access key (AWS and Azure), or the access token (GCP).
• Cloud keystore specification method (Parameters) is unique to each keystore provider. CORE addresses such a variety of options by using key-value pairs.

Cloud keystore parameter names and values are case-sensitive. They depend on the keystore provider as follows:

• AWS KMSKey Management System

Parameter-name	Value	Example of value
REGION	Name of the region	US_WEST_2

• Azure Key Vault

Parameter-name	Value	Example of value
URL	URL of the key vault	https://hello-world.vault.azure.net/

• GCP KMSKey Management System

Parameter-name	Value	Example of value
location	Name of the region	us-east1
keyring_id	Name of the keyring	my-keyring

In addition, a partition SOSecurity officer - UKC partition administrator role. must specify CORE-specific attributes of external keystore:

• Name - mandatory and permanent.
• Deploy as external service - "No". Mandatory. See Deployment Options.
• Keystore Sync Method - see automation in Working with External Keystores.

For the detailed UI description, see New Keystore.

HSM Keystore Service Settings

HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing keystore service (HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing Connect) settings are defined into two groups:

• Service settings:
  • Name - mandatory and permanent.
  • Deploy as external service - "Yes". Mandatory. See Working with External Keystores.
  • Keystore Sync Method - see automation in Working with External Keystores.
  • Secret key - mandatory. Password of the HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing partition's Crypto Officer.
• Service registration with CORE settings:
  • URL of the service.
  • PKIPublic Key Infrastructure artifacts of the service: 
    • PFXAn archive file format for storing cryptography objects using Base64 encoding file that contains key and certificate required to set up TLSTransport Layer Security - a cryptographic protocol that provides communications security over a computer network connection.
    • JKSA Java KeyStore (JKS) is a repository of security certificates – either authorization certificates or public key certificates – plus corresponding private keys, used for instance in SSL encryption. file that contains a certificate that validates that the HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing service request originated from CORE.

For the detailed UI description, see Register HSM Connect Agent.

Synchronization Options

To sync keys in the CORE partition with the changes that occurred in its external keystore, the partition's SOSecurity officer - UKC partition administrator role. has two options:

• Manual update:
  • Use the UI link command to add a link to a new key in the keystore.
  • Use the UI relink command to update the existing key.
• Automatic update:
  
  • Launch the partition's key-sync service. It is a scheduled job that runs periodically according to the specification provided on its launch. The default interval is 30 minutes. The minimum period is one minute.
  • Control the synchronization scope by managing the sync policy of each keystore specified in the partition's configuration (see Edit Keystore):

  NONE

  do not synchronize this keystore (default). The sync service makes no changes in the partition.

  ONLY_LINKED_KEYS

  as needed, re-sync already linked keys.

  ALL_ACTIVE_KEYS

  1. as needed, re-sync already linked keys.

  2. link to the new keys that were created in the external keystore.

  Note
  The key-sync service withholds from synchronizing the CORE keys with the deleted, destroyed, or revoked keys in the external keystore.You must explicitly perform the corresponding CORE command to synchronize CORE with the deleted, destroyed, or revoked external keys.

External Key Indicators in CORE

isExternal Setting

An external key is identified in CORE by the following settings:

• isExternal - true.
• keyStoreProperties:

  • Name - the name assigned to the keystore.

  • ObjectId - name (Id) of the key in the external keystore.

  • ProtectionMethod - how the key is stored in the external keystore (HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing or "Software").

  • BYOKBring Your Own Key - true or false.

• local - true if the key is BYOKBring Your Own Key, false otherwise.

Note
All crypto functions of an isExternal key are executed by the external keystore. The BYOKBring Your Own Key setting of a key is not relevant.

BYOK Setting and Requirements

Unlike cloud keystores, we assume that on-premises HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing is managed by the organization that uses the CORE partition, and therefore, the BYOKBring Your Own Key in such a case is redundant.

1. BYOKBring Your Own Key and Exportability
   • non-BYOKBring Your Own Key - such a key is not exportable from CORE.
   • BYOKBring Your Own Key - exporting a BYOKBring Your Own Key from CORE conforms to the exporting restrictions specified in its CORE settings.
2. BYOKBring Your Own Key and Import:
   • CORE key import procedure for a key designated to a cloud keystore includes the following steps:
     1. Key is imported to CORE, where it starts the BYOKBring Your Own Key process.
     2. The cloud keystore provides a wrapping key used by CORE to forward the wrapped material to the keystore.
     3. Key types that cannot be imported to the keystore due to wrapping limitations are declined.
3. BYOKBring Your Own Key delivery process and user's permissions.
   A user involved in the BYOKBring Your Own Key delivery process (either by generating a BYOKBring Your Own Key key or importing a key) must be authorized to perform all the necessary crypto operations required to protect the forwarded material. In particular, the user must be authorized to wrap a key using the type of key specified by the keystore provider.

Keystore Troubleshooting

Ping

CORE periodically checks the responsiveness of the keystores referred from a partition and the validity of the credentials used to access the keystore. The result appears in the keystore's status setting. It has two values {STOPPED, RUNNING}. To check the reason for being STOPPED, use the UI command Show the Last Error.

In addition, UI allows a partition SOSecurity officer - UKC partition administrator role. to manually trigger this test by clicking the Ping command that performs the same test. The test's implementation is specific to each keystore provider:

AWS Ping

Send a request to generate a random number.

 

Azure Ping

Send key list request.

 

GCP Ping

Send Get request to the keyring.

 

HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing (Luna) Ping

Open a session, login, close the session.

Log files

See External Keystore Trace Logs.