Secrets management with askmscli

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 that is used for encrypting authorization tokens can be dynamically generated for improved security and time-limited validity.
Primary key for Redis database: Encryption of sensitive information in a Redis database, by using a secure 256-bit primary key set by the system administrator. Sensitive information, for example, might 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 following migration steps allow you to take full advantage of this security feature. Although not required, adopting these measures help ensure the secure use of Aspera products. The steps involve running the askmscli tool, which stores secrets in file-system-protected keystore files instead of in the aspera.conf file.

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

Secrets Category	Description
`ssear`	Passphrases used for server-side encryption at rest (SSEAR).
`redis-primary-key`	Primary 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:


Database	Description
`rootkeystore.db`	Functions as a backup and main source of truth for encrypted secrets.
`localkeystore.db`	Resides in the user’s home directory (by default). It contains a copy of shared keys like `redis-primary-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 following procedures 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 might want to add /opt/aspera/bin to your PATH environment variable.

Content-protection secret

The askmscli tool sets content-protection secrets for individual users only. It does not support setting them for user groups or all users on a system. Each transfer user requires their own content-protection secret for SSEAR.

The following steps 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. 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 data that use dynamic token encryption keys:

Remove existing plain-text token encryption keys from aspera.conf.
Set token_dynamic_key to true in aspera.conf.
Set a primary 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 primary key by using askmscli. The primary key must be a unique random 256-bit key. The following example uses openssl to generate the key. This Redis primary key is used to encrypt the dynamic token encryption key.
```
$ echo -n "`openssl rand -base64 32`" | sudo askmscli -s redis-primary-key
```
For each transfer user with a token encryption key, run the following commands to initialize the user's keystore:
```
$ sudo askmscli -i -u username
```
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 that are created from the old token encryption keys 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 primary key

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

For new installations only:

Attention: Not applicable to upgrades.

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

Set a Redis primary key by using askmscli.
The primary key must be a unique, random 256-bit key. The following example uses openssl to generate the key. This Redis primary key is used to encrypt both the dynamic token encryption key and access keys in Redis.
```
$ echo -n "`openssl rand -base64 32`" | sudo askmscli -s redis-primary-key
```
For the transfer user associated with the access key, run askmscli to initialize the user's keystore (if not done previously):
```
$ sudo askmscli -i -u username
```
For the user that runs asperanoded, set the keystore. The default user is asperadaemon. The username might change if you are not using the default user.
```
$ sudo askmscli -i -u asperadaemon
```
If you are using your server as a tethered node with IBM® Aspera® On Cloud, or if you use the access key authentication feature and have sensitive data in your access key, such as storage secrets, you must encrypt it.
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
```
Restart asperanoded to apply the new configuration changes.

Redis password

System administrators can configure a secure password to control client access to the Redis database. When the authorization layer is enabled, Redis rejects all commands from unauthenticated clients. Clients must authenticate by issuing the AUTH command followed by the correct password.

For new installations only:

Attention: Not applicable to upgrades.

(V.4.4.2) Set a Redis password.
Local Redis
If you are connecting to a local Redis, run these commands:
```
$ export redis_pass=password
$ echo -n $redis_pass | sudo askmscli -s redis-password
```
External Redis
If you are connecting to an external Redis, specify the username and the password for the authentication. Run these commands:
```
$ export redis_pass=password redis-user=redis_user
$ echo -n $redis_pass | sudo askmscli -s redis-password --redis_user=$redis_user
```
For transfer users accessing Redis with the asnodeadmin tool, run askmscli to set up their keystore using the new Redis password.
You must initialize the askmscli keystore for the user running alee-admin (usually root), just as you do for the asperadaemon user. This allows the asperanoded service to access the Redis password.

Important: Running askmscli to initialize an existing user keystore also updates the keystore with the new shared secret (--redis-user and redis-password in this case).
```
$ sudo askmscli -i -u username
```

To keep the Redis password persistent across restarts, follow these steps:

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
```

Update the configuration file to save the password across restarts:

$ 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

Restore aspera_31415.conf file 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 by using either standard input, or a file. For example, by using the 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, reinitialize any existing user keystores (use 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 reinitializing the existing keystores are automatically encrypted by 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 makes all keystore records inaccessible (root and user).
Changing or rotating a stash password is not currently supported.