Managing Security Keys in the Qumulo File System Key Store

This section explains how to manage security keys in the Qumulo file system key store by using the qq CLI.

In Qumulo Core 6.1.0 (and higher), you can store multiple ECDSA public keys in the Qumulo file system key store and use these keys to protect file system resources.

Important

Currently, Qumulo Core supports only 256-bit ECDSA keys in .pem and .der formats. Qumulo Core doesn't support storing ECDSA keys of other lengths and formats.
Qumulo Core retains only the public key. We strongly recommend storing the corresponding private key safely, outside of your Qumulo cluster and according to your organization's security policy.

For information about protecting your snapshots by using a key from the Qumulo file system key store, see Locking and Unlocking Snapshots.

Tip
The response of the qq fs_security_add_key command includes the key identifier. When you use qq fs_security commands, you can specify either the key identifier (by using the --id flag) or the key name (by using the --name flag).

Adding a Public Key

This section explains how to add a public key to the Qumulo file system key store. To store a public key in the key store, you must have a pair of asymmetric keys. For more information, see Generating an ECDSA Private Key.

If You Have Access to the Private Key

Note
To use this method, you must install the Python cryptography library.

Run the qq fs_security_add_key command and specify the key name, the path to the private key file, and an optional comment. For example:

qq fs_security_add_key \
  --name my-key-name \
  --private-key-file /path/to-my-file.pem \
  --comment "This is an optional comment."

If You Don’t Have Direct Access to the Private Key

Run the qq fs_security_add_key command and specify the key name, the public key contents, the Base64-encoded verification signature (the key name signed with the private key), and an optional comment. For example:

qq fs_security_add_key \
  --name my-key-name \
  --public-key "VGhpcyBpcyBteSBwdWJsaWMga2V5IGNvbnRlbnRzLg==" \
  --verification-signature "VGhpcyBpcyBteSB1bmxvY2sgY2hhbGxlbmdlLg==" \
  --comment "This is an optional comment."

For more information, see Extracting the Public Key from an ECDSA Private Key and Signing a Security Challenge by Using an ECDSA Private Key.

Retrieving Public Key Information

To retrieve information for a single public key, run the qq fs_security_get_key command and specify the key identifier or name.
To retrieve information for all public keys, run the qq fs_security_list_keys command.

The output displays information in a table format. To view the output in JSON format, use the --json flag.

Retrieving Public Key Usage Information

Run the qq fs_security_get_usage command and specify the key identifier or name.

The output displays information in a table format. To view the output in JSON format, use the --json flag.

Modifying a Public Key

To modify the name or comment for a public key, run the qq fs_security_modify_key command and specify the key identifier or name and the flags for the fields to modify.

Rotating a Public Key

This section explains how to rotate a public key in the Qumulo file system key store.

Note

Key rotation doesn't affect the resources that the key protects or change the identifier or name of the public key.
When the key rotation is complete, only the replacement public key can unlock the protected resources.

If You Have Access to the Existing and Replacement Private Keys

Note
To use this method, you must install the Python cryptography library.

Run the qq fs_security_replace_key command and specify the key identifier or name, the path to the existing private key, and the path to the replacement private key. For example:

qq fs_security_replace_key \
  --name my-key-name \
  --old-private-key-file /path/to-existing-key.pem \
  --replacement-private-key-file /path/to-replacement-key.pem

If You Don’t Have Direct Access to the Existing and Replacement Private Keys

To receive the key replacement challenge, run the qq fs_security_get_key_replace_challenge command and specify the identifier or name of the key to replace.
To generate a verification signature, use the response from the challenge with the existing private key and another verification signature by using the challenge and the replacement private key.

For more information, see Signing a Security Challenge by Using an ECDSA Private Key.
To rotate the key, run the qq fs_security_replace_key command and specify the key identifier or name, the replacement public key contents, the replacement key verification signature (Base64-encoded key replacement challenge signed with the replacement private key), and the existing key verification signature (Base64-encoded key replacement challenge signed with the existing private key). For example:
```
qq fs_security_replace_key \
  --name my-key-name \
  --replacement-public-key "VGhpcyBpcyBteSByZXBsYWNlbWVudCBwdWJsaWMga2V5Lg==" \
  --replacement-key-verification-signature "UmVwbGFjZW1lbnQga2V5IHZlcmlmaWNhdGlvbiBzaWduYXR1cmU=" \
  --old-key-verification-signature "RXhpc3Rpbmcga2V5IHZlcmlmaWNhdGlvbiBzaWduYXR1cmU="
```
For more information, see Extracting the Public Key from an ECDSA Private Key.

Important
Because the key version is part of the challenge message, and this version changes when a user writes or modifies the key, any change to the key name or comment after you receive the challenge message makes the message stale.

Disabling a Public Key

When you add a key to the Qumulo file system key store, Qumulo Core enables it automatically.

To disable a key, run the qq fs_security_modify_key command and specify the key identifier or name and the --disable flag.
To re-enable a key, use the --enable flag.