mirror of
https://github.com/edgelesssys/constellation.git
synced 2024-12-29 01:16:12 -05:00
90b88e1cf9
In the light of extending our eKMS support it will be helpful to have a tighter use of the word "KMS". KMS should refer to the actual component that manages keys. The keyservice, also called KMS in the constellation code, does not manage keys itself. It talks to a KMS backend, which in turn does the actual key management.
209 lines
8.3 KiB
Markdown
209 lines
8.3 KiB
Markdown
# constellation-kms-client
|
|
|
|
This library provides an interface for the key management services used with constellation.
|
|
It's intendet for the Constellation CSI Plugins and the CLI.
|
|
|
|
## KMS
|
|
|
|
The Cloud KMS is where we store our key encryption key (KEK).
|
|
The KMS should be initiated by the CLI and provided with a key release policy.
|
|
The CSP Plugin can request to encrypt data encryption keys (DEK) with the KEK to safely store the DEKs in persistent storage.
|
|
The [kms](../kms/) package interacts with the Cloud KMS APIs.
|
|
Support is planed for:
|
|
|
|
* AWS KMS
|
|
* GCP CKM
|
|
* Azure Key Vault
|
|
|
|
## Storage
|
|
|
|
Storage is where the CSI Plugin stores the encrypted DEKs.
|
|
Currently planned are:
|
|
|
|
* AWS S3, SSP
|
|
* GCP GCS
|
|
* Azure Blob
|
|
|
|
# Credentials
|
|
|
|
Each Plugin requires credentials to authenticate itself to a CSP.
|
|
|
|
## Storage
|
|
|
|
This section covers how credentials are used by the storage plugins.
|
|
|
|
### AWS S3 Bucket
|
|
|
|
To use the AWS S3 Bucket plugin, you need to have an existing [AWS account](https://aws.amazon.com/de/premiumsupport/knowledge-center/create-and-activate-aws-account/).
|
|
|
|
For authentication, you have to pass a config file to the plugin. The AWS config package lets you automatically fetch the data from the local AWS directory.
|
|
|
|
#### Passing credentials automatically
|
|
|
|
You need to store your credentials in your local AWS directory at `$HOME/.aws/`. The AWS config package uses the values from the directory to build a config file, which is used to authenticate the client. The local AWS directory must contain two files:
|
|
|
|
* `credentials`
|
|
|
|
```bash
|
|
[default]
|
|
aws_access_key_id = MyAccessKeyId
|
|
aws_secret_access_key = MySecretAccessKey
|
|
```
|
|
|
|
* `config`
|
|
|
|
```bash
|
|
[default]
|
|
region = MyRegion
|
|
output = json
|
|
```
|
|
|
|
If you have the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) installed, you can
|
|
initialise the files with the following command:
|
|
|
|
```bash
|
|
aws configure
|
|
```
|
|
|
|
To create the client:
|
|
|
|
```Go
|
|
cfg, err := config.LoadDefaultConfig(context.TODO())
|
|
store, err := storage.NewAWSS3Storage(context.TODO(), "bucketName", cfg, func(*s3.Options) {})
|
|
```
|
|
|
|
### Azure Blob Storage
|
|
|
|
To use the Azure Blob storage plugin, you need to first [create a storage account](https://docs.microsoft.com/en-us/azure/storage/common/storage-account-create?tabs=azure-portal) or give your application access to an existing storage account.
|
|
|
|
The plugin uses a connection string created for the storage account to authenticate itself to the Azure API.
|
|
The connection string can be found in your storage account in the Azure Portal under the "Access Keys" section or with the following Azure CLI command:
|
|
|
|
```bash
|
|
az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount
|
|
```
|
|
|
|
The client will use the specified Blob container if it already exists, or create it first otherwise.
|
|
|
|
To create the client:
|
|
|
|
```Go
|
|
connectionString := "DefaultEndpointsProtocol=https;AccountName=<myAccountName>;AccountKey=<myAccountKey>;EndpointSuffix=core.windows.net"
|
|
store, err := storage.NewAzureStorage(context.TODO(), connectionString, "myContainer", nil)
|
|
```
|
|
|
|
### Google Cloud Storage
|
|
|
|
To use the Google Cloud Storage plugin, the Cloud Storage API needs to be enabled in your Google Cloud Account. You can use an existing bucket, create a new bucket yourself, or let the plugin create the bucket on initialization.
|
|
|
|
When using the Google Cloud APIs, your application will typically [authenticate as a service account](https://cloud.google.com/docs/authentication/production).
|
|
You have two options for passing service account credentials to the Storage plugin: (1) Fetching them automatically from the environment or (2) passing them manually in your Go code.
|
|
|
|
Note that the serivce account requires the following permissions:
|
|
|
|
* `storage.buckets.create`
|
|
* `storage.buckets.get`
|
|
* `storage.objects.create`
|
|
* `storage.objects.get`
|
|
* `storage.objects.update`
|
|
|
|
#### Finding credentials automatically
|
|
|
|
If your application is running inside a Google Cloud environment, and you have [attached a service account](https://cloud.google.com/iam/docs/impersonating-service-accounts#attaching-to-resources) to that environment, the Storage Plugin can retrieve credentials for the service account automatically.
|
|
|
|
If your application is running in an environment with no service account attached, you can manually attach a [service account key](https://cloud.google.com/iam/docs/service-accounts#service_account_keys) to that environment.
|
|
After you [created a service account and stored its access key to file](https://cloud.google.com/docs/authentication/production#create_service_account) you need to set the environment variable `GOOGLE_APPLICATION_CREDENTIALS` to the location of that file.
|
|
The Storage Plugin will then be able to automatically load the credentials from there:
|
|
|
|
```bash
|
|
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-file.json"
|
|
```
|
|
|
|
To create the client:
|
|
|
|
```Go
|
|
store, err := storage.NewGoogleCloudStorage(context.TODO(), "myProject", "myBucket", nil)
|
|
```
|
|
|
|
#### Passing credentials manually
|
|
|
|
You may also explicitly use your service account file in code.
|
|
First, create a service account and key the same way as in [finding credentials automatically](#finding-credentials-automatically).
|
|
You can then specify the location of the file in your application code.
|
|
|
|
To create the client:
|
|
|
|
```Go
|
|
credentialFile := "/path/to/service-account-file.json"
|
|
opts := option.WithCredentialsFile(credentialFile)
|
|
store, err := storage.NewGoogleCloudStorage(context.TODO(), "myProject", "myBucket", nil, opts)
|
|
```
|
|
|
|
## Key Managment Service
|
|
|
|
This section covers how credentials are used by the KMS plugins.
|
|
|
|
### AWS KMS
|
|
|
|
To use the AWS KMS, you need to have an existing [AWS account](https://aws.amazon.com/de/premiumsupport/knowledge-center/create-and-activate-aws-account/).
|
|
|
|
For authentication, you have to pass a config file to the plugin. As with the AWS S3 Bucket, you can use the config package to retrieve the data for the config file from your local AWS directory. Follow the steps listed in the [AWS S3 Bucket](#aws-s3-bucket) section on how to build the config file automatically.
|
|
|
|
To create the client:
|
|
|
|
```Go
|
|
cfg, err := config.LoadDefaultConfig(context.TODO())
|
|
awsClient := kms.NewFromConfig(cfg)
|
|
client := kmsAws.New(awsClient, nil)
|
|
```
|
|
|
|
### Azure Key Vault
|
|
|
|
To use the Azure Key Vault, you need to first [create a new key vault](https://docs.microsoft.com/en-us/azure/key-vault/general/quick-create-portal) or use an existing vault.
|
|
|
|
The implementation uses `NewDefaultAzureCredential` to load credentials. If you application is running on Azure infrastructure, credentials will be loaded using [managed identities](https://docs.microsoft.com/en-us/azure/developer/go/azure-sdk-authentication?tabs=bash#managed-identity). Otherwise you can use [environment variables to configure the client](https://docs.microsoft.com/en-us/azure/developer/go/azure-sdk-authentication?tabs=bash#-option-1-define-environment-variables).
|
|
|
|
To create the client for Azure KMS:
|
|
|
|
```Go
|
|
client, err := kmsAzure.New(context.TODO(), "myVault", kmsAz.DefaultCloud, nil, nil)
|
|
```
|
|
|
|
To create the client for Azure manged HSM KMS:
|
|
|
|
```Go
|
|
client, err := kmsAzure.NewHSM(context.TODO(), "myHSM", nil, nil)
|
|
```
|
|
|
|
### Google KMS
|
|
|
|
To use the Google Key Management Service, you need to first enable the KMS API and [create a key ring](https://cloud.google.com/kms/docs/quickstart#key_rings_and_keys) to use with the plugin or use an existing key ring.
|
|
|
|
Providing credentials to your application for Google's Cloud Key Managment Service happens the same way as described in [Google Cloud Storage](#google-cloud-storage).
|
|
|
|
Note that the service account used for authentication requires the following permissions:
|
|
|
|
* `cloudkms.cryptoKeyVersions.create`
|
|
* `cloudkms.cryptoKeyVersions.update`
|
|
* `cloudkms.cryptoKeyVersions.useToDecrypt`
|
|
* `cloudkms.cryptoKeyVersions.useToEncrypt`
|
|
* `cloudkms.importJobs.create`
|
|
* `cloudkms.importJobs.get`
|
|
* `cloudkms.importJobs.useToImport`
|
|
|
|
Once your credentials are set up you can create your client:
|
|
|
|
* With automatic credential selection:
|
|
|
|
```Go
|
|
client, err := kmsGcp.New("myProject", "global", "myKeyRing", nil, kmspb.ProtectionLevel_SOFTWARE)
|
|
```
|
|
|
|
* With manual credential selection:
|
|
|
|
```Go
|
|
credentialFile := "/path/to/service-account-file.json"
|
|
opts := option.WithCredentialsFile(credentialFile)
|
|
client, err := kmsGcp.New("myProject", "global", "myKeyRing", nil, kmspb.ProtectionLevel_SOFTWARE, opts)
|
|
```
|