[CBBS] Document how to create an encrypted repository

What is the problem?

Our backup service REST API documentation does not say how to create an encrypted repository.

What is the solution?
We should inform users to create an encrypted repo they need to pass the parameters documented here. encryption_key_url and km_auth_type are required, and then other fields are required based on the value of km_auth_type:

• environment - no required fields
• file - km_access_file_path required
• credentials - km_credential_name or km_credentials_id and km_credentials_key required; km_tenant_id is also required for Azure Key Vault, and km_region for AWS KMS.

These values map to the similarly named cbbackupmgr arguments. See this doc page for examples.

"encryption_key_url" value examples:

AWS KMS:
"encryption_key_url":"awskms://alias/mytestkey"

Azure Key Vault:
"encryption_key_url":"azurekeyvault://{vault-name}.vault.azure.net/{object-type}/{object-name}/{object-version}"
"encryption_key_url":"azurekeyvault://my-key-vault.vault.azure.net/keys/my-azure-key/17054e1bff8a40cf81e85ab5aa01aede"

GCP KMS:
"encryption_key_url":"gcpkms://projects/project-id/locations/location/keyRings/keyring/cryptoKeys/key"

HashiCorp Vault Transit Engine:
"encryption_key_url":"hashivaults://127.0.0.1:8200/key"

Example of creating a Backup Service repository using encryption with AWS KMS key and "km_auth_type":"credentials" (using km_credentials_id and km_credentials_key):

Only AWS KMS requires the "kms_region" field.

curl -X POST http://localhost:8097/api/v1/cluster/self/repository/active/test_encrypted_repo -u Administrator:'password' -d '{"plan":"_daily_backups", "archive":"/somepath/cb_backup", "encryption_key_url":"awskms://alias/mytestkey", "km_auth_type":"credentials", "km_region":"us-west-2", "km_credentials_id":"AKIAWIDGYGBUXXXXXXXX", "km_credentials_key":"XXXXXXXZtmAyT1ORzm1RXNqRXXXXXXXXXXXXXXXX"}'

When the archive repository is created successfully with encryption, you'll see a lock symbol in the UI next to the repository name.

You will also see the "encryption_opts" object in the output of the GET for the archive repository description, as shown below:

curl -X GET http://localhost:8097/api/v1/cluster/self/repository/active/test_encrypted_repo  -u Administrator:'password' | jq .

{

  "id": "test_encrypted_repo",

  "plan_name": "_daily_backups",

  "state": "active",

  "archive": "/somepath/cb_backup",

  "repo": "d9555611-c142-4d18-b1da-b2f7617c8d8a",

  "scheduled": {

    ...

  },

  "version": 1,

  "health": {

    "healthy": true

  },

  "creation_time": "2024-03-21T15:57:53.770094-07:00",

  "update_time": "2024-03-21T16:00:19.236048-07:00",

  "encryption_opts": {

    "key_url": "awskms://alias/mytestkey",

    "auth_type": "credentials",

    "region": "us-west-2",

    "creds_name": "f48381a8-7ea7-4de8-a795-a5eae8a5a83a"

  }

}

You'll see that in the above output, the "encryption_opts" object has a "creds_name" field.

The value of "creds_name" is what you would use for "km_credential_name" if you wanted to create a second archive repository using the same KMS credentials as the one used in the above archive repository creation.

Example using "km_credential_name":

curl -X POST http://localhost:8097/api/v1/cluster/self/repository/active/test_encrypted_repo2 -u Administrator:'password' -d '{"plan":"_daily_backups", "archive":"/somepath/cb_backup2", "encryption_key_url":"awskms://alias/hjvtestkey", "km_auth_type":"credentials", "km_region":"us-west-2", "km_credential_name":"f48381a8-7ea7-4de8-a795-a5eae8a5a83a"}'

Below is an example of creating a Backup Service repository using encryption with Azure Key Vault key and "km_auth_type":"credentials" (using km_credentials_id, km_credentials_key, and km_tenant_id). Azure Key Vault requires the "km_tenant_id" field with "km_credentials_id" and "km_credentials_key".

curl -X POST http://localhost:8097/api/v1/cluster/self/repository/active/test_encrypted_repo -u Administrator:'password' -d '{"plan":"_daily_backups", "archive":"/some_path/cb_backup", "encryption_key_url":"azurekeyvault://my-key-vault.vault.azure.net/keys/my-azure-key/17054e1bff8a40cf81e85ab5aa01aede", "km_auth_type":"credentials", "km_tenant_id":"111b1d11-f111-1fde-bc11-111be11111d0", "km_credentials_id":"XXXX4658-XX8b-44f4-9aXX-79ab06b7XXXX", "km_credentials_key":"eXXXQ~csUuE_XXXXMyy5B1cuXXXX0bTgEXXXXXXX"}'