Secrets Management with askmscli

The askmscli tool can be used to securely manage secrets and keys that can pose a security risk when stored on machines in plain-text format.

The askmscli command-line tool provides the following capabilities:

Content protection: Encrypting passphrases used for server-side encryption at rest (SSEAR).
Dynamic token encryption key: The key used for encrypting authorization tokens can be dynamically generated for improved security and time-limited validity.
Master key for Redis database: Encryption of sensitive information in a Redis database, using a secure 256-bit master key set by the system administrator. Sensitive information, for example, could be an access-key-specific content-protection secret or token encryption key.
Redis database password: System administrators can set a secure password for a Redis database to authenticate Redis clients.
Stash file protection for keystores: System administrators can set a stash password to add a stash file-encryption layer to all keystores of a node.

Migration Procedures

The migration steps described below allow you to take full advantage of this security feature. Although not required, Aspera strongly recommends you adopt these measures to ensure the secure usage of Aspera products. The steps consist of running the askmscli tool, which stores secrets in file-system-protected keystore files rather than in the aspera.conf file.

According to which encryption features you're setting up, the askmscli command recognizes three categories of secrets:

`ssear`	Passphrases used for server-side encryption at rest (SSEAR).
`redis-master-key`	Master key for encryption of sensitive data in a Redis database, such as token encryption keys.
`redis-password`	Password for a Redis database to authenticate Redis clients.

The askmscli tool stores secrets in SQLite DBs. It maintains the encrypted secrets in two databases:

`rootkeystore.db`	Functions as a backup and main source of truth for encrypted secrets.
`localkeystore.db`	Resides in user’s home directory (by default). It contains a copy of shared keys like `redis-master-key` and `redis-password` along with a user’s own secrets. This allows every user to use the same shared keys without requiring a shared/world-readable database.

The procedures described below are organized to indicate which steps are for upgrades, which are for new installations, and which are for both.

On Linux systems, the Aspera commands in this topic are located in /opt/aspera/bin. For your convenience, you may want to add /opt/aspera/bin to your PATH environment variable.

Content-Protection Secret

The askmscli tool sets content-protection secrets only for each user, not for groups and not for all users on a node. Each transfer user requires their own content-protection secret for SSEAR. The steps below describe how to migrate content-protection secrets from aspera.conf to a user's local keystore. Two procedures are shown: one for new installations and one for upgrades. Aspera recommends that you do not store content-protection secrets in aspera.conf.

For Upgrades:

Before you start, make a backup copy of your aspera.conf file.

Locate all content_protection_secret settings in aspera.conf, and make a note of the value that's set for each.

Set a content-protection secret for each user:

$ echo -n secret | sudo askmscli -u username -s ssear

Remove all plain-text content-protection secrets from aspera.conf. Use these commands:

$ sudo asconfigurator -x "set_user_data; user_name,user; transfer_encryption_content_protection_secret,AS_NULL"
$ sudo asconfigurator -x "set_group_data; group_name,group; transfer_encryption_content_protection_secret,AS_NULL"
$ sudo asconfigurator -x "set_node_data; transfer_encryption_content_protection_secret,AS_NULL"

For New Installations:

Set the content-protection secret for each transfer user by running this command:
```
$ echo -n secret | sudo askmscli -u username -s ssear
```

Token Encryption Key

The following is a brief summary of the steps for encrypting and using dynamic token encryption keys:

(1) Remove existing plain-text token encryption keys from aspera.conf.
(2) Set token_dynamic_key to true in aspera.conf.
(3) Set a master key for Redis.

Before you proceed, make a backup copy of your aspera.conf file.

For Upgrades and New Installations:

Enable the use of dynamic token encryption keys by setting token_dynamic_key to true in aspera.conf.
```
$ sudo asconfigurator -x "set_node_data; token_dynamic_key,true"
```
NOTE: A dynamic token encryption key can be set for an individual user or a system group.
Set a Redis master key using askmscli. The master key must be a unique random 256-bit key. The example below uses openssl to generate the key. This Redis master key will be used to encrypt the dynamic token encryption key.
```
$ echo -n "`openssl rand -base64 32`" | sudo askmscli -s redis-master-key
```
For each transfer user with a token encryption key, run the commands below to initialize the user's keystore:
```
$ sudo askmscli -i -u username
```
Set the store for the asperadaemon user that runs asperanoded.
```
$ sudo askmscli -i -u asperadaemon
```
Restart asperanoded to apply the new configuration changes. To test transfers, try an upload and download through your Web application.

For Upgrades Only:

Once all the outstanding tokens created from the old token encryption keys have expired, remove the token_encryption_key settings from aspera.conf:

$ sudo asconfigurator -x "set_user_data; user_name,user; token_encryption_key,AS_NULL"
$ sudo asconfigurator -x "set_group_data; group_name,group; token_encryption_key,AS_NULL"
$ sudo asconfigurator -x "set_node_data; token_encryption_key,AS_NULL"

Redis Master Key

System administrators can now set a unique 256-bit Redis master key to encrypt local access-key configuration and dynamic token encryption keys.

For New Installations Only: (Not applicable to upgrades.)

If you have not already created a Redis master key as part of enabling dynamic token encryption keys (as in "Token Encryption Key" above), then:

Set a Redis master key using askmscli. The master key must be a unique, random 256-bit key. The example below uses openssl to generate the key. This Redis master key will be used to encrypt both the dynamic token encryption key and access keys in Redis.
```
$ echo -n "`openssl rand -base64 32`" | sudo askmscli -s redis-master-key
```
For the transfer user associated with the an access key, run askmscli to initialize the user's keystore (if not done previously):
```
$ sudo askmscli -i -u username
```
If you are using your server as a tethered node with Aspera on Cloud, or if you are using the access key authentication feature, then you must encrypt your access key.
1. List your node user and password with the command:
```
#/opt/aspera/bin/asnodeadmin -l
```
2. Retrieve your access key with this command syntax:
```
curl -kiu node_user:password https://localhost:9092/access_keys
```
  (For more information, see Node API Reference.)
3. Encrypt your access key data with this command syntax:
```
asnodeadmin --encrypt-access-key --access-key access_key
```

Redis Password

System administrators can set a secure password for clients to authenticate with a Redis database. When the authorization layer is enabled, Redis refuses any query by unauthenticated clients. A client can authenticate itself by sending the AUTH command followed by the password.

For New Installations Only: (Not applicable to upgrades.)

Set a Redis password:

$ export redis_pass="password"
$ echo -n $redis_pass | sudo askmscli -s redis-password

For transfer users who will query Redis using the asnodeadmin tool, run askmscli to initialize the user's keystore with the new Redis password:
```
$ sudo askmscli -i -u username
```
NOTE: Running askmscli to initialize an existing user keystore also updates the keystore with the new shared secret (redis-password in this case)
In order for the Redis password to persist across reboots, perform the following steps:
1. Temporarily change the ownership of the Redis configuration file aspera_31415.conf to the user asperadaemon.
```
$ chown asperadaemon /opt/aspera/etc/redis/aspera_31415.conf
```
2. Update the configuration file to save the password across reboots:
```
$ asredis -p 31415
127.0.0.1:31415> CONFIG SET REQUIREPASS redis_passwd
OK
127.0.0.1:31415> AUTH redis_passwd
OK
127.0.0.1:31415> CONFIG REWRITE
OK
127.0.0.1:31415> quit
```
3. Restore aspera_31415.conf ownership to root
```
$ chown root /opt/aspera/etc/redis/aspera_31415.conf
```
  .

Stash File Protection for Keystores

You can set a stash password to add a stash file-encryption layer to all keystores of a node:

Use the askmscli tool to set a stash password for the node.
The stash password is used to derive a unique key for every keystore.
The unique keystore key is then used to encrypt and decrypt the keystore secrets.

The askmscli tool can be used to set a stash password using either standard input, or a file. For example, using standard input:

$ echo -n "r@nd0ms3curepassw0rd" | sudo /opt/aspera/bin/askmscli -P-
Stash password set successfully

Or, using a file that contains a stash password:

$ echo -n "r@nd0ms3curepassw0rd" >> /tmp/random-stash-password.txt
$ sudo /opt/aspera/bin/askmscli -P /tmp/random-stash-password.txt
Stash password set successfully

Note: Setting a stash password automatically upgrades the rootkeystore.db (or creates one if it does not exist).

After setting a stash password, re-initialize any existing user keystores (using the -i option) so that encryption uses the keystore key.

$ sudo /opt/aspera/bin/askmscli -i -u $USER
Keystore initialized successfully

All secrets added after re-initializing the existing keystores are automatically encrypted using the keystore key.

The limitations on using stash-file protection are:

Once a stash password is set, and user keystores are initialized, deleting a stash file will make all keystore records inaccessible (root and user).
Changing or rotating a stash password is not currently supported.