sftpgo-plugin-kms

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