

Encrypting Passwords in Configuration Files¶

All WSO2 products are shipped with a Secure Vault implementation that allows you to store encrypted passwords in configuration files. By default, the system user passwords, key store passwords, etc. in configuration files are stored in plain text, but storing sensitive data such as passwords in plain text makes the data more susceptible to compromise.

Secure Vault allows you to store encrypted passwords and map them with aliases, which are used in configuration files instead of the actual passwords. These encrypted passwords will be decrypted and resolved during runtime only.

For example, if the admin user password is admin, you can define an alias (such as admin_password) and map that particular alias to the actual password (admin). At runtime, the product will look up this alias in the secure vault, decrypt it, and use the mapped password.

The instructions below explain how plain text passwords in configuration files can be encrypted using the secure vault implementation that is built into WSO2 products.

Encrypting passwords in product configurations¶

Open the <APIM_HOME>/repository/conf/deployment.toml file.
Add the [secrets] configuration section at the bottom of the deployment.toml file and include the passwords that you need to protect.

Important

The [secrets] configuration section should be added at the very end of the deployment.toml file or else this will cause errors in server startup.

Use the <alias>="[<actual_password>]" format, under [secrets] as shown below. The most commonly used passwords in configuration files are listed in the example configuration.
Format
```
[secrets]
<password_1_alias> = "[<password_1>]"
<password_2_alias> = "[<password_2>]"
```
Example
```
[secrets]
admin_password = "[admin]"
keystore_password = "[wso2carbon]"
key_password = "[wso2carbon]"
truststore_password = "[wso2carbon]"
```
Locate the configurations with the plain text passwords in the <APIM_HOME>/repository/conf/deployment.toml configuration file, and replace them with $secret{<alias>} in order to refer to the encrypted password instead of the plain text password.

Note that the alias has to be the alias value that you configured in the above step as the mapping of the actual password.

The sample configuration for the most commonly used passwords is given below.
Format
```
[super_admin]
username="admin"
password="$secret{<admin_password_alias>}"

[keystore.tls]
password = "$secret{<keystore_password_alias>}" 
key_password = "$secret{<key_password_alias>}"  

[truststore]                  
password = "$secret{<truststore_password>}"       
```
Example
```
[super_admin]
username="admin"
password="$secret{admin_password}"

[keystore.tls]
password = "$secret{keystore_password}" 
key_password = "$secret{key_password}"  

[truststore]                  
password = "$secret{truststore_password}"   
```
Note

You can also replace your passwords by referring values passed by environment variables and system properties. For instructions, see Set Passwords using Environment Variables/System Properties
Encrypt the passwords.
1. Open a terminal and navigate to the <APIM_HOME>/bin directory.
2. Execute the following command to encrypt the passwords. (You must first enable the Cipher tool for the product by executing the -Dconfigure command with the cipher tool script as shown below).
  - On Linux: ./ciphertool.sh -Dconfigure
  - On Windows: ./ciphertool.bat -Dconfigure
You will be prompted to enter the internal key store password for the server.
When prompted, enter the primary key password, which is by default wso2carbon and proceed.

If the encryption is successful, you will see the following log.
```
Internal KeyStore of Carbon Server is initialized Successfully

Secret Configurations are written to the property file successfully
```

Open to the <APIM_HOME>/repository/conf/deployment.toml file.

You will see that the alias passwords are encrypted.

[secrets]
admin_password  = "gss3W6fPqm5YdCCBUxTJsFAONjt4NvnLK8ab5Ob5sgRXWMFEQW8mvVxnpnKlMKwqgV9dlUwG4RCzT9hcc2TKkbkxZDDQnGczgwMnlTaiviGkm/D4FIuuGqhh1i1KBNIShUMCPGIFBpqGbvTe4R4CQjZc3kw9FEOBZni7EJFkKCKeSI4d9bDZUmGpNsMzIsqXSqklxQ+zq/ZAcx3ctQZU9QsfXaknqHSWr0sFNzlyMc/o70kOcUyFb3UYxE1knrGvPMMHaVK7ZbI40c0G4vPxsDnliOv/KvpMhTd6AIuY9gzP9lChzmWq7SgLrBVrqDMBWsteKOvAgaQNri6vXmDykQ=="
keystore_password  = "cGsMesQfdbElQusfsc7FxXdc89Ak88rwtcW7jaHtGqCNZFYUJpyJ+551xXTWhSXZP/CS7mqTmPYWOOKfeIalSlv1ULSsH5JIpOROsTsJgZ3Bu4RpsypMan9UMpc5xjoMaNr955WD03DfDZ2PSZFSx78GoKEr8RSzNSBlr2q3hxaujHfGzjXMhkuZmIsnI77zFxVXb5iDz/n6oh9Mz7xRheXy3CsxLxm2sNGsr9+GL4ZrKWlQ7dZdbWk0N3HtpJbyDGa58yHaswxJHe8eVnTn66c3C9QlRDNL9JSHppzk+03xTzStb9v9Y4a+Fdz9ckBY1zQ3NPVUOjMToPKEaNPVoA=="
key_password  = "hCmOjvWOmCCH8qsIhSecVewvgtStrM+QeZFKWfLqo1Mui2TuDpX4PKm4M2XQ/gRAH7GFP8AZStKN9QwjdyhGU3O6KuwhyIoKNH0Wkf/2jafShChLQj7jmd2fFxWYZLgnd9h36LEQEYgYGhyoyfZWmJknn6c4RxxNrSk3PJbWl8pft3ylRpYRIPhPUXegTI1XMuLgTiUMmB2wLF12QBFLOHLJhFWZx2E1ngpSoWsxdEcluQeJiTwR1ltrk23WY8N54xaZOsVN8zSniEGpwt6Jo8eij9Rjl+5r8wgErdYvX16xKQxBiQxjuEazzH4h29Ey/pf5S4y2oFX1WElIo51knw=="
truststore_password  = "FEQvzFCYpJfuD9XYb0H4KW/lZICu7vaPMzC02kIIbMy47q1q68QxIdOAwQxv+wiRAI/fQIxX6ygTjWV+3bjYmP1Mj0qrhx6CeH6L467ISIHT8oTdecqq5kcGqMEBanexQ7Wu/ULeiiaGLA4x9OXHgJsKd9x3yf6Vm56FzmVkUM5+HAX6pYpBSEFuDKJprhlJtvrEN//nGb0p342g4CqG9VqW3UFbkQaawmItSd9pMnBlDM6+STmiDBUFrV7gdJfrCzGnJs7QBl20Kxg5aznNkwnpJ3bEwj3Trkzsxujk1wMOnhk5XvwdeKRevkX8MyHrnUICyXZ6TK0po1wrYZjYvw=="

To resolve the passwords during different modes of server startup, see Resolving already encrypted passwords during server startup.

Encrypting secured endpoint passwords¶

When exposing an API backend, which is secured with Digest or Basic Authentication, the backend user credentials have to be provided under endpoint configuration. These credentials are encoded in base64 and stored in the API configuration as Basic Authorization header (Authorization: Basic base64Encode(<username>:password)). By default, the Authorization header value is stored in plain text.

Follow the instructions below to secure the endpoint's password that is given in plain-text in the UI.

Shut down the server if it is already running.
Open the <APIM_HOME>/repository/conf/deployment.toml file and add the following configuration to enable secure vault in API Manager.
```
[apim]
enable_secure_vault=true
```
Important

This configuration should be added before all the other [apim] elements or this will result in an error.
Run the Cipher tool script, which is available in the <API-M_HOME>/bin directory.
- On Linux/Mac OS: ./ciphertool.sh -Dconfigure
- On Windows: ./ciphertool.bat -Dconfigure
You will be prompted to enter the internal key store password for the server.
When prompted, enter the primary key password, which is by default wso2carbon.

If the encryption is successful, you will see the following log.
```
Internal KeyStore of Carbon Server is initialized Successfully

Secret Configurations are written to the property file successfully
```
Restart the server.
- On Linux/Mac OS: ./api-manager.sh
- On Windows: ./api-manager.bat

After enabling the backend secure vault for backend credentials, the Basic Authentication header, which is written in the API Gateway configuration file, will be encrypted. If there were APIs that were already created and published before these instructions were performed, an update to the particular API would trigger the encryption process of the credentials.

Example:

The following example depicts the same API when the endpoint password is not encrypted and encrypted:

Here, the Basic authentication header is in base64 encoded format and can be decoded to get the actual credentials of the endpoint.

<property name="Authorization" expression="fn:concat('Basic ', 'dGVzdDp0ZXN0MTIz')" scope="transport"/>

Here, the password is first looked up from the secret repository, and then set as a transport header.

<property name="password" expression="wso2:vault-lookup('<api-identifier>')"/>
<property name="unpw" expression="fn:concat('test',':',get-property('password'))"/>
<property name="Authorization" expression="fn:concat('Basic ', base64Encode(get-property('unpw')))" scope="transport"/>

Changing already encrypted passwords¶

Follow the instructions below to change any password that you have already encrypted:

Shut down the server.
Open a command prompt and go to the <API-M_HOME>/bin/ directory, where the Cipher tool scripts (for Windows and Linux) are stored.
Execute the following command for your OS:
- On Linux: ./ciphertool.sh -Dchange
- On Windows: ./ciphertool.bat -Dchange You will be prompted to enter the internal keystore password.
Enter the keystore password (which is "wso2carbon" for the default keystore).

The alias values of all the passwords that you encrypted will now be shown in a numbered list as follows.
```
Internal KeyStore of Carbon Server is initialized Successfully

[1] keystore_password
[2] key_password
[3] admin_password
[4] truststore_password
[Please enter the Number which is corresponding to the Password that is needed be changed [Press Enter to Skip] : ]
```
The system will then prompt you to select the alias of the password which you want to change.
Enter the list number of the password alias.

For example, if you want to change the password for admin_password, enter 3.

The system will then prompt you (twice) to enter the new password.
Enter your new password.

If the encryption is successful, you will get the Encryption is done Successfully message.

Resolving already encrypted passwords during server startup¶

Secure Vault provides two options of resolving the encrypted passwords during server startup

Enter password in command-line
Start server as a background job

Note

If you have secured the plain text passwords in configuration files using Secure Vault, the keystore password and private key password of the product's primary keystore will serve as the root passwords for Secure Vault. This is because the keystore passwords are needed to initialize the values encrypted by the Secret Manager in the Secret Repository. Therefore, the Secret Callback handler is used to resolve these passwords. The default secret CallbackHandler provides the two options given below. For more information on secure vault concepts, see Secure Vault concepts.

Enter password in command-line¶

Start the server by running the product start up script from the <APIM_HOME>/bin directory as shown below.
- On Linux: ./api-manager.sh
- On Windows: ./api-manager.bat
When you run the startup script, the following message will be prompted before starting the server: [Enter KeyStore and Private Key Password:].
When prompted, you as the administrator who is starting the server must provide the private key password and the keystore password using the command-line to proceed.

Note that passwords are hidden from the terminal and log files.

Info

During the server startup, it tries to connect to the default user store. In order to connect to the default user store, the encrypted passwords should be decrypted. Therefore, the server admin will be prompted with the key store password in order to proceed with the decryption.

Start server as a background job¶

If you start the WSO2 API Manager as a background job, you will not be able to provide password values on the command line. Therefore, you must start the server in daemon mode as explained below.

Create a new file in the directory. The file should be named according to your OS as explained below.
- For Linux: The file name should be password-tmp
- For Windows: The file name should be password-tmp.txt
Note

When you start the server, the keystore password will be picked from this new file. Note that this file is automatically deleted from the file system after the server starts. Therefore, the admin has to create a new text file every time the server starts.

Alternatively, if you want to retain the password file after the server starts, the file should be named as follows:
- For Linux: The file name should be password-persist
- For Windows: The file name should be password-persist.txt
Add the primary keystore password (which is wso2carbon by default) to the new file and save it.

By default, the password provider assumes that both the private key password and keystore password are the same. If not, the private key password must be entered in the second line of the file.
Start the server as a background process by running the following command.
- On Linux: ./api-manager.sh start
- On Windows: ./api-manager.bat start

Top