oldwingman

Objective

This document provides instructions on how to encrypt your application secrets using the Volterra Blindfold and how to decrypt from your vk8s application. To know more about Blindfold and secrets management, see Volterra Blindfold.

The following image illustrates the sequence of actions performed by Volterra in securing the secrets -

application secret workflow — Figure: Volterra Blindfold

Using the instructions provided in this guide, you can encrypt application secrets and store it in code or configmap.

Prerequisites

The following prerequisites apply:

Volterra Account

Note: If you do not have an account, see Create a Volterra Account.

An application running on vk8s

Note: If you do not have an application running on vk8s, see Deploy Application.

The vesctl tool. Download vesctl on your local machine as it is used to apply Blindfold to the TLS certificate.

Accessing secrets in Application

Workflow

Applying Blindfold to the secret of your cloud application includes performing the following sequence of actions:

Phase	Description
Create a Secret Policy Rule	Create a policy rule to permit your application to decrypt the secret.
Create a Secret Policy	Create a policy to permit your application to decrypt the secret.
Prepare Credentials and Policy	Retrieve API credentials from VoltConsole, derive certificates, derive keys, and obtain policy.
Encrypt application secret	Perform the encryption on a local computer. It is recommended to use an air-gapped computer.
Access decrypted secret from your application	Make a REST call to volterra security sidecar(Wingman) to access decrypted secret.

Note: The API credentials are required to be downloaded in PKCS #12 file format.

Create a Secret Policy Rule

The secret policy rule allows Wingman running as sidecar in your application access to the secret.

Step 1: Select the namespace where you want to create your Secret Policy. Select Security from the configuration menu and Secret Management from the options pane. Select Policy Rules and click Add secret policy rule. The policy rule creation form gets loaded.

Step 2: Enter the policy rule configuration parameters as per the following guidelines:

Name: Name of the service policy rule
Action: Supported actions are ‘allow’ and ‘deny’
Client Name: Name of the client accessing the server
Client Label Selector: Label selector expression for the client. Any label applied to the application can be used to write the expression.
Client Name Matcher: Client Name Matcher field has following subfields.
- Exact Values: exact DNS names of the clients to match.
- Regex Values: regex patterns for DNS names to match.

secret pol rule — Figure: Create Secret Policy Rule

Create a Secret Policy

The secret policy allows Wingman running as sidecar in your application access to the secret.

Step 1: Select the same namespace where you created your Secret Policy Rule. Select Security from the configuration menu and Secret Management from the options pane. Select Policies and click Add secret policy. The policy creation form gets loaded.

Step 2: Enter the policy configuration parameters as per the following guidelines:

Name: Name of the Service Policy
Rule Combining Algorithm: The algorithm is of the following types:
- First Rule Match: Evaluates each rule in the order of configuration
- Deny Rule Overrides: Evaluates all "allow" rules only.
- Allow Rule Overrides: Evaluates all "deny" rules before evaluating any "allow" rules.
Rules: Select service policy rule created above

secret pol app — Figure: Create Secret Policy

Prepare Credentials and Policy

Step 1: Select system namespace. Select IAM from the configuration menu and API Credentials from the options pane. Click Create credentials.

Step 2: Provide a name for the credentials, select Credential type as API Certificate, and provide a password to access the credentials. Click Download. The credentials are returned in the JSON format.

Step 3: Derive a certificate from the downloaded PKCS #12 file. This example shows how to derive the certificate using OpenSSL.

openssl pkcs12 -nokeys -in demo-api-credentials.p12 -out demo-api.crt

Note: This step prompts for password. Enter the password used in Step 1 to generate the certificate file in the .crt file.

Step 4: Derive a key from the downloaded PKCS 12 file. Enter the following command:

openssl pkcs12 -nocerts -nodes -in demo-api-credentials.p12 -out demo-api.key

Note: This step prompts for password. Enter the password used in Step 1 and a passphrase to generate the key file in the .key format.

Step 5: Obtain a public-key using vesctl and store the output to a file. This example stores the output to a file named demo-api-pubkey.

vesctl --cert file:///demo-api.crt --key file:///demo-api.key -u https://demo-api.console.ves.volterra.io/api request secrets get-public-key > demo-api-pubkey

Note: For the --cert and --key options, specify the path to the certificate file and key file derived in Step 3 and Step 4 respectively.

The following output capture shows a sample public key:

data:
  keyVersion: 1
  modulusBase64:   rc3DxZa69sWeIn9NRrHGcZlZaXLHWYjc57jIS76Z47AcU0jDmodz3lNEysVO2swNAUn8p6yiuvf8Vj4LUuWB++LdP2yYX5ftEHmMgnHVq4AdKFBp5zbrh15g7mS0lpdX/xG6h0+IdHyrWPoIg/hZwYyV9xmIOcFc1Jk5PZC554hchHbToQ==
  publicExponentBase64: A6ur/Xk=
  tenant: volterra-demo1

Step 6: Obtain a policy-document using vesctl and store the output to a file. This example stores the output to a file named demo-api-policy.

vesctl --cert file:///demo-api.crt --key file:///demo-api.key -u https://demo-api.console.ves.volterra.io/api request secrets get-policy-document --namespace volterra-demo --name demo-secret-policy > demo-secret-policy

Note: For the --cert and --key options, specify the path to the certificate file and key file derived in Step 3 and Step 4 respectively. For the --name field, enter the API credentials object name.

The following output capture shows a sample policy document.

data:
  name: demo-secret-policy
  namespace: volterra-demo
  policyId: "101"
  policyInfo:
    rules:
    - action: ALLOW
      clientSelector:
        expressions:
        - app = demo-tls-server
  tenant: volterrra-demo1

Encrypt your Application Secret Using Blindfold

Step 1: Use vesctl to encrypt secret using Blindfold and store the returned encrypted secret for using it in the application. This example stores the output to a file named secret.enc.

cat > secretfile.data
This is secret data that should only be seen by application pod.


vesctl --cert file:///demo-api.crt --key file:///demo-api.key -u https://demo-api.console.ves.volterra.io/api request secrets encrypt --policy-document demo-secret-policy --public-key demo-api-pubkey secretfile.data > secret.enc

Note: Provide the certificate, key, public key, and policy document obtained in the Prepare Credentials and Policy chapter.

The following output capture shows a sample encrypted key.

sample-output:

Encrypted Secret (Base64 encoded):
AAAACWN1c3RvbWVyMQAAAAEAAAAAAAAAaAIAAAAFA6ur/XkAAAEArc3DxZa69sWeIn9NRrHGcZlZaXLHWYjc57jIS76Z47AcU0jDmodz3lNEysVO2s

This encrypted secret can be provided to the application pod via several means - put the encrypted secret in code, provided via configmap, provided via kubernetes secret, etc.

Decrypt your Application Secret

Application needs to make REST call to Wingman (running a REST server on localhost:8070) to decrypt the secret. API Specification are specified here

Below is the example cURL request and output -

cat > input.json
{
  "type": "blindfold",
  "location": "string:///AAAACWN1c3RvbWVyMQAAAAEAAAAAAAAAaAIAAAAFA6ur/XkAAAEArc3DxZa69sWeIn9NRrHGcZlZaXLHWYjc57jIS76Z47AcU0jDmodz3lNEysVO2s"
}

curl -XPOST http://localhost:8070/secret/unseal -d @input.json
VGhpcyBpcyBzZWNyZXQgZGF0YSB0aGF0IHNob3VsZCBvbmx5IGJlIHNlZW4gYnkgYXBwbGljYXRpb24gcG9kLg==

Output of the REST call is decrypted secret in Base64 encoding format. So, if we get the original secret back if do Base64 decoding of the output string value

echo "VGhpcyBpcyBzZWNyZXQgZGF0YSB0aGF0IHNob3VsZCBvbmx5IGJlIHNlZW4gYnkgYXBwbGljYXRpb24gcG9kLg==" | base64 -D
This is secret data that should only be seen by application pod.