SFTPGo KMS plugin
This plugin adds support for additional KMS secret providers to SFTPGo.
Configuration
The supported services can be configured within the plugins
section of the SFTPGo configuration file. This is an example configuration.
...
"kms": {
"secrets": {
"url": "hashivault://my-key",
"master_key": "",
"master_key_path": ""
}
},
"plugins": [
{
"type": "kms",
"kms_options": {
"scheme": "hashivault",
"encrypted_status": "VaultTransit"
},
"cmd": "<path to sftpgo-plugin-kms>",
"args": [],
"sha256sum": "",
"auto_mtls": true
}
]
...
In the above example we enabled the transit secrets engine in Vault.
Supported Services
This plugin use Go CDK to access several key management services in a portable way.
Google Cloud Key Management Service
To use keys from Google Cloud Platform’s Key Management Service (GCP KMS) you have to use gcpkms
as URL scheme like this.
gcpkms://projects/[PROJECT_ID]/locations/[LOCATION]/keyRings/[KEY_RING]/cryptoKeys/[KEY]
This plugin will use Application Default Credentials. See here for alternatives such as environment variables.
The URL host+path are used as the key resource ID; see here for more details.
If a master key is provided we first encrypt the plaintext data using the SFTPGo local provider and then we encrypt the resulting payload using the Cloud provider and store this ciphertext.
In the configuration section kms_options
set:
scheme
to gcpkms
encrypted_status
to GCP
AWS Key Management Service
To use customer master keys from Amazon Web Service’s Key Management Service (AWS KMS) you have to use awskms
as URL scheme. You can use the key’s ID, alias, or Amazon Resource Name (ARN) to identify the key. You should specify the region query parameter to ensure your application connects to the correct region.
Here are some examples:
- By ID:
awskms://1234abcd-12ab-34cd-56ef-1234567890ab?region=us-east-1
- By alias:
awskms://alias/ExampleAlias?region=us-east-1
- By ARN:
arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34bc-56ef-1234567890ab?region=us-east-1
This plugin will use the default AWS session. See AWS Session to learn about authentication alternatives such as environment variables.
If a master key is provided we first encrypt the plaintext data using the SFTPGo local provider and then we encrypt the resulting payload using the Cloud provider and store this ciphertext.
In the configuration section kms_options
set:
scheme
to awskms
encrypted_status
to AWS
Azure KeyVault
To use keys from Azure KeyVault you have to use azurekeyvault
as URL scheme. Here is an example URL.
azurekeyvault://mykeyvaultname.vault.azure.net/keys/mykeyname
The "azurekeyvault" URL scheme is replaced with "https" to construct an Azure Key Vault keyID, as described here. You can add an optional "/{key-version}" to the path to use a specific version of the key; it defaults to the latest version.
This plugin will use the default credentials from the environment.
If a master key is provided we first encrypt the plaintext data using the SFTPGo local provider and then we encrypt the resulting payload using the Cloud provider and store this ciphertext.
In the configuration section kms_options
set:
scheme
to azurekeyvault
encrypted_status
to AzureKeyVault
HashiCorp Vault
To use the transit secrets engine in Vault you have to use hashivault
as URL scheme like this: hashivault://my-key
.
The Vault server endpoint and authentication token are specified using the environment variables VAULT_SERVER_URL
and VAULT_SERVER_TOKEN
, respectively.
If a master key is provided we first encrypt the plaintext data using the SFTPGo local provider and then we encrypt the resulting payload using Vault and store this ciphertext.
In the configuration section kms_options
set:
scheme
to hashivault
encrypted_status
to VaultTransit