constellation/internal/kms/README.md

# Key Management Service backend implementation

This library provides an interface for the key management services used by Constellation.
Its intended to be used for secure managing for data encryption keys and other symmetric secrets.

## [kms](./kms/)

A Key Management Service (KMS) is where we store our key encryption key (KEK).

We differentiate between two cases:

* cluster KMS (cKMS):

    The Constellation cluster itself holds the master secret (KEK) and manages key derivation.
    The KEK is generated by an admin on `constellation init`.
    Once send to the cluster, the KEK never leaves the confidential computing context.
    As keys are only derived on demand, no DEK is ever persisted to memory by the cKMS.

* external KMS (eKMS):

    An external KMS solution is used to hold and manage the KEK.
    DEKs are encrypted and persisted to cloud storage solutions.
    An admin is required to set up and configure the KMS before use.

### KMS Credentials

This section covers how credentials are used by the KMS plugins.

#### AWS KMS

The client requires the region the KMS is located, an access key ID, and an access key secret.
Read the [access key documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) for more details.

The IAM role requires the following permissions on the key:

* `kms:DescribeKey`
* `kms:Encrypt`
* `kms:Decrypt`

#### Azure Key Vault / Azure managed HSM

Authorization for Azure Key Vault happens through the use of manged identities.
The managed identity used by the client needs the following permissions on the KEK:

* `keys/get`
* `keys/wrapKey`
* `keys/unwrapKey`

The client is set up using the tenant ID, client ID, and client secret tuple.
Further, the vault type is chosen to configure whether or not the Key Vault is a managed HSM.

### Google KMS

Providing credentials to your application for Google's Cloud KMS happens through the usage of service accounts.
A credentials file for the service account is used to authorize the client.

Note that the service account used for authentication requires the following permissions:

* `cloudkms.cryptoKeyVersions.get`
* `cloudkms.cryptoKeyVersions.useToDecrypt`
* `cloudkms.cryptoKeyVersions.useToEncrypt`

## [storage](./storage/)

Storage is where the CSI Plugin stores the encrypted DEKs.

Supported are:

* In-memory (used for testing only)
* AWS S3, SSP
* GCP GCS
* Azure Blob

### Storage Credentials

Each Plugin requires credentials to authenticate itself to a CSP.

#### AWS S3 Bucket

For authentication an access key ID and an access key secret is used.
As a fallback, the client may try to automatically fetch the data from the local AWS directory.

#### Azure Blob Storage

Authorization for Azure Blob Storage happens through the use of manged identities.
The managed identity requires the following permissions:

* `Microsoft.Storage/storageAccounts/blobServices/containers/write` (only if a storage container is not set up in advance)
* `Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write`
* `Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read`
* `Microsoft.Storage/storageAccounts/blobServices/containers/blobs/add/action`

#### Google Cloud Storage

Providing credentials to your application for Google's Cloud Storage happens through the usage of service accounts.
A credentials file for the service account is used to authorize the client.

Note that the service account requires the following permissions:

* `storage.buckets.create` (only if a bucket is not set up in advance)
* `storage.buckets.get`
* `storage.objects.create`
* `storage.objects.get`
* `storage.objects.update`