Vault Implementation

Internal Stakeholders	Role	Department
Simon Jolly (Unlicensed)	Technical Architect
Anthony Commander (Unlicensed)	Devops Manager

Feature description

The Vault feature is a tool that enables access to secrets (anything that you want to tightly control access to, such as API keys, passwords, or certificates) in a secure way. It provides a unified interface to any secret, while providing tight access control and recording a detailed audit log.

Business Case Summary

Currently we use config files and environment variables to control and manage secrets (API keys) in our infrastructure. The keys are stored as plain text (not encrypted) in the service definition or application configuration files and are stored in different locations multiple times. We need a central management system that stores and encrypts secrets to prevent the risks of the keys being exposed.

Functional Requirements (Use Case)

1.

Use Case Title:	Secure secret storage
Description	Ensures secrets (API keys) are encrypted and secured
Trigger	New data is secured / encrypted when a storage location is created via an API request Existing storage location secrets will be passively secured / encrypted by the start up of the running environment
Primary Actors (Personas)
Secondary Actors
Stakeholders
Preconditions	Vault Service and API Encrypted communication with the Vault Access to the vault key is limited to System Admin System admin needs to be authenticated to access vault keys
Flow (Main success Scenario)	User sends data via an API to the Vault Vault receives the data via and encrypted connection Vault encrypts the data as secrets (encrypted data) Secrets can be decrypted back into their original form
Alternative flows	N/A
Post-conditions	Success End condition: Vault receives data and encrypts the data Data can be decrypted back into their original form Failure End condition: Data is not encrypted in the vault communication with the vault is not secure (encrypted)
Frequency	Determined by the API
Priority	MUST

2.

Use Case Title:	Rotate Vault access keys
Description	Enables system admin to rotate vault Keys with no data loss when required (e.g system breach or system maintenance).
Glossary	Rotate Vault Keys: The changing of the unseal key for vault, meaning that existingsecrets will be re-encrypted with a new key
Trigger	Triggered by System admin request
Primary Actors (Personas)
Secondary Actors
Stakeholders
Preconditions	Vault Service Documentation for Key Rotation
Flow (Main success Scenario)	System admin identifies need to rotate keys System admin can rotate keys in the vault service Vault Keys are rotated with no data loss
Alternative flows	N/A
Post-conditions	Success End condition: System admin can rotate keys in the vault service Vault Keys are rotated with no data loss Failure End condition: system admin cannot rotate keys vault keys are rotated with data loss
Frequency	Determined by Customer internal policies
Priority	MUST

3.

Use Case Title:	Add secrets in vault from a new storage location
Description	Ensures secrets (API keys) from a new storage location are added to the vault so that they are encrypted and secured
Trigger	Triggered when a new storage location is added by the appropriate API endpoint
Primary Actors (Personas)
Secondary Actors
Stakeholders
Preconditions	Vault Service and API Encrypted communication with the Vault New storage location endpoint has been added
Flow (Main success Scenario)	A new storage location API endpoint is added Vault receives the data from the new storage location via and encrypted connection Vault encrypts the data as secrets (encrypted data) Secrets can be decrypted back into their original form
Alternative flows	N/A
Post-conditions	Success End condition: Data from new storage location is added to the vault Vault receives data and encrypts the data Data can be decrypted back into their original form Failure End condition: Data from new storage location is not added to the vault Data is not encrypted in the vault communication with the vault is not secure (encrypted)
Frequency	Determined by the API
Priority	MUST

4.

Use Case Title:	Discard secrets in vault from a deleted storage location
Description	Ensures secrets (API keys) from a deleted storage location are removed permanently from the vault
Trigger	Triggered when a storage location is deleted by the appropriate API endpoint
Primary Actors (Personas)
Secondary Actors
Stakeholders
Preconditions	Vault Service and API Encrypted communication with the Vault New storage location endpoint has been deleted
Flow (Main success Scenario)	An existing storage location is deleted using the appropriate API endpoint Secrets in the vault are deleted for that storage location
Alternative flows	N/A
Post-conditions	Success End condition: Secrets are deleted permanently from the vault Failure End condition: Secrets are not deleted from the vault
Frequency	Determined by the API
Priority	MUST

Non functional requirements

Area	Requirement	MoSCoW	Additional comments
Hardware Requirements	n/a
Software Requirements and Licencing	n/a
Performance Requirements	Excluding startup of the system there should be no impact to the concurrent capture of the platform.
Supportability Requirements	Documentation on vault Key rotations Documented process for vault keys backup and recovery.
Security Requirements	Vault keys should be encrypted on disk Vault keys access is limited to system admins only
Interface Requirements	N/A
Usability/Accessibility	N/A
Compliance Requirement	N/A
Training	No training will be provided.		Documentation for Vault key rotations and Vault key backups and recovery will be provided.
Resilience	Vault keys will be rotated without data loss
Legal and Regulatory	N/A
Scalability	Must scale in line with the infrastructure (An instance of the Vault should be present on all nodes in the cluster.)

Assumptions

There will be no user interaction with the secrets stored in vault directly. As such, the only customer facing API endpoint will be the 'rotate' functionality. No 'GetKeyByAlias' functionality will exist
The provisioning of storage accounts (and the securing of their credentials in vault) will be handled at install time, no endpoint will be created to add a new key into vault
The rotate functionality will only change the encryption keys for vault itself, the secrets will remain unchanged when encrypted (obviously changing the vault encryption key will mean all the underlying encrypted secrets change)

Scope for future development
Brief description of Future enhancements

Baz Chougule (Unlicensed)
(QA) to review and sign-off
Liam Hayman Tansley (Unlicensed)
(Team Lead) to review and sign-off

Anthony Commander (Unlicensed)
(Dev Manager) to review and sign-off
Kirill Zotkin (Unlicensed)
(Team Lead) to review and sign-off
Jayasri (Unlicensed)
Konstantin Kovbasa (Deactivated)

Project Team: Alpha, Beta or Charlie	Roles