Encrypting Secrets with apictl¶

WSO2 API Controller (apictl) allows you to encrypt plain-text secrets. You can use this feature to export secrets as environment variables, system properties, Docker secrets, or Kubernetes secrets.

apictl secret supports two encryption modes:

Symmetric encryption using an AES-256 encryption key. You must initialize the key first with apictl secret init symmetric.
Asymmetric encryption using a keystore initialized with apictl secret init.

Note

Use the same encryption mode and algorithm that the target runtime uses to decrypt secrets.

Choose the encryption mode¶

Mode	When to use	Initialization	Supported cipher values
Symmetric	When the target runtime is configured to use AES-based secret encryption. Choose a ciphertext format — normal, `internal` or `external` — to match how the target runtime reads the value back; see Choose a ciphertext format.	Requires `apictl secret init symmetric`.	Defaults to `AES/GCM/NoPadding`. `AES256` is also accepted as an alias.
Asymmetric	When the target runtime uses RSA and a keystore for secret encryption.	Requires `apictl secret init`.	`RSA/ECB/OAEPWithSHA1AndMGF1Padding` or `RSA/ECB/PKCS1Padding`

Encrypt secrets with symmetric encryption¶

Symmetric encryption uses an AES-256 encryption key that must be initialized before creating secrets.

Note

Run apictl secret init symmetric before apictl secret create symmetric. apictl prompts for the symmetric key once, validates it, stores it in encryption-key/encryption_key.yaml, and uses AES/GCM/NoPadding as the default symmetric algorithm during secret creation.

Note

It is recommended to use a 64-character hexadecimal AES-256 key. For example:

openssl rand -hex 32

Initialization
```
apictl secret init symmetric
```

Choose a ciphertext format¶

apictl secret create symmetric accepts an optional second argument that selects the shape of the encrypted value, depending on which system will read it back. In every sub-mode, apictl prints (or writes to a file) a single base64-encoded string that decodes to the JSON shown below. All three sub-modes use the exact same AES-256 key initialized above — only the wrapping around the ciphertext changes.

Sub-mode	Command	Ciphertext shape	Use when
Normal (default)	`apictl secret create symmetric`	`{"cipherText": "...", "iv": "..."}` — the same shape as `external`, and the same format earlier apictl releases produced	The target runtime decrypts secrets via cipher-tool, carbon-secvault, or the current carbon-mediation secure vault, or you want the same output as earlier apictl releases
Internal	`apictl secret create symmetric internal`	`{"c": "<base64 inner>", "t": "AES/GCM/NoPadding", "iv": "..."}`, where the base64-decoded inner value is `{"cipher": "...", "initializationVector": "...", "keyId": "..."}`	The target runtime decrypts secrets via carbon-crypto-service (self-contained ciphertext format)
External	`apictl secret create symmetric external`	`{"cipherText": "...", "iv": "..."}`	The target runtime decrypts secrets via cipher-tool, carbon-secvault, or the current carbon-mediation secure vault

Create encrypted secrets
```
apictl secret create symmetric
apictl secret create symmetric internal
apictl secret create symmetric external
```
Info

Flags:
- Optional :
  --cipher or -c : Optional algorithm override for symmetric encryption. The default is AES/GCM/NoPadding. AES256 is also accepted as an alias
  --output or -o : Get the output in yaml (k8) or properties (file) format. By default the output is printed to the console
  --from-file or -f : Path to the properties file which contains secrets to be encrypted
- Encrypt a secret and get output on console
  Example
```
apictl secret create symmetric
Enter plain alias for secret: db_password
Enter plain text secret:
Repeat plain text secret:
```
  - Response
```
db_password : eyJjaXBoZXJUZXh0IjoidU9UUTNGY0tXSUZnOFlISDkraWNCS1ZuQng1QnpJVT0iLCJpdiI6InU5cGpxU1FtcDFna2tzY1IifQ==
```
- Encrypt secrets defined in a properties file, in the internal (carbon-crypto-service) format
  Example
```
apictl secret create symmetric internal -f ./keys/secrets.properties
```
  - Response (decoded)
```
{"c":"<base64 inner>","t":"AES/GCM/NoPadding","iv":"..."}
```
- Encrypt secrets defined in a properties file, in the external (cipher-tool/carbon-secvault/carbon-mediation) format
  Example
```
apictl secret create symmetric external -f ./keys/secrets.properties
```
  - Response (decoded)
```
{"cipherText":"...","iv":"..."}
```
- Encrypt secrets defined in a properties file and get a .properties file
  Example
```
apictl secret create symmetric internal -o file -f ./keys/secrets.properties
```
- Encrypt secrets defined in a properties file and get a .yaml file
  Example
```
apictl secret create symmetric internal -o k8 -f ./keys/secrets.properties
```
Response

The encrypted value is printed to the console by default. If -o file or -o k8 is used, apictl generates the output file in the security directory of the current working directory.

Encrypt secrets with asymmetric encryption¶

Asymmetric encryption uses the public key from a keystore. The initialized keystore details are stored in keystore/keystore_info.yaml. Before creating secrets, initialize apictl with the keystore used by the target runtime.

Initialize apictl with a keystore¶

Note

Secret encryption supports only JKS keystores for this flow.

Note

The keystore used in this step must be the same keystore that the target runtime uses to decrypt secrets.

Run the following command to initialize apictl with the keystore used to encrypt secrets. It prompts you to enter the following values:

Key Store location	Path to the keystore used by the target runtime to decrypt secrets
Key Store password	The password of the keystore
Key alias	The alias of the key used to encrypt the secrets
Key password	The password of the key used to encrypt the secrets

Command

apictl secret init

Example

apictl secret init
Enter Key Store location: <APIM-HOME>/repository/resources/security/wso2carbon.jks
Enter Key Store password:
Enter Key alias: wso2carbon
Enter Key password:

Response
```
Key Store initialization completed.
```

Create encrypted secrets with asymmetric encryption¶

Run the following command to encrypt secrets with the initialized keystore:

Command
```
apictl secret create
```
Info

Flags:
- Optional :
  --cipher or -c : Encryption algorithm. Use RSA/ECB/OAEPWithSHA1AndMGF1Padding or RSA/ECB/PKCS1Padding for asymmetric encryption
  --output or -o : Get the output in yaml (k8) or properties (file) format. By default the output is printed to the console
  --from-file or -f : Path to the properties file which contains secrets to be encrypted
- Encrypt a secret and get output on console
  Example
```
apictl secret create
Enter plain alias for secret: db_password
Enter plain text secret:
Repeat plain text secret:
```
- Response
```
db_password : <encrypted-secret>
```
- Encrypt secrets defined in a properties file
  Example
```
apictl secret create -f ./keys/secrets.properties
```
- Encrypt secrets defined in a properties file and get a .yaml file
  Example
```
apictl secret create -o k8 -f ./keys/secrets.properties
```