feat(key_manager): review wording (scaleway#4492)

Co-authored-by: Yacine Fodil <[email protected]>

cmd/scw/testdata/test-all-usage-keymanager-key-create-usage.golden

@@ -1,19 +1,20 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Create a key in a given region specified by the `region` parameter. Keys only support symmetric encryption. You can use keys to encrypt or decrypt arbitrary payloads, or to generate data encryption keys that can be used without being stored in Key Manager.
+Create a key in a given region specified by the `region` parameter. Keys only support symmetric encryption. You can use keys to encrypt or decrypt arbitrary payloads, or to generate data encryption keys. **Data encryption keys are not stored in Key Manager**.
 
 USAGE:
   scw keymanager key create [arg=value ...]
 
 ARGS:
   [project-id]                         Project ID to use. If none is passed the default project ID will be used
   [name]                               (Optional) Name of the key
-  [usage.symmetric-encryption]          (unknown_symmetric_encryption | aes_256_gcm)
+  [usage.symmetric-encryption]         Algorithm used to encrypt and decrypt arbitrary payloads. (unknown_symmetric_encryption | aes_256_gcm)
   [description]                        (Optional) Description of the key
   [tags.{index}]                       (Optional) List of the key's tags
   [rotation-policy.rotation-period]    Rotation period
   [rotation-policy.next-rotation-at]   Key next rotation date
   [unprotected]                        (Optional) Defines whether key protection is applied to a key. Protected keys can be used but not deleted
+  [origin]                             Key origin (unknown_origin | scaleway_kms | external)
   [region=fr-par]                      Region to target. If none is passed will use default region from the config (fr-par | nl-ams | pl-waw)
 
 FLAGS:

cmd/scw/testdata/test-all-usage-keymanager-key-decrypt-usage.golden

@@ -1,9 +1,9 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Decrypt data using an existing key, specified by the `key_id` parameter. The maximum payload size that can be decrypted is the result of the encryption of 64KB of data (around 131KB).
+Decrypt an encrypted payload using an existing key, specified by the `key_id` parameter. The maximum payload size that can be decrypted is equivalent to the encrypted output of 64 KB of data (around 131 KB).
 
 USAGE:
-  scw keymanager key decrypt [arg=value ...]
+  scw keymanager key decrypt <key-id ...> [arg=value ...]
 
 ARGS:
   key-id              ID of the key to decrypt

cmd/scw/testdata/test-all-usage-keymanager-key-delete-key-material-usage.golden

@@ -0,0 +1,19 @@
+🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
+🟥🟥🟥 STDERR️️ 🟥🟥🟥️
+Delete previously imported key material. This renders the associated cryptographic key unusable for any operation. The key's origin must be `external`.
+
+USAGE:
+  scw keymanager key delete-key-material <key-id ...> [arg=value ...]
+
+ARGS:
+  key-id            ID of the key of which to delete the key material
+  [region=fr-par]   Region to target. If none is passed will use default region from the config (fr-par | nl-ams | pl-waw)
+
+FLAGS:
+  -h, --help   help for delete-key-material
+
+GLOBAL FLAGS:
+  -c, --config string    The path to the config file
+  -D, --debug            Enable debug mode
+  -o, --output string    Output format: json or human, see 'scw help output' for more info (default "human")
+  -p, --profile string   The config profile to use

cmd/scw/testdata/test-all-usage-keymanager-key-delete-usage.golden

@@ -1,9 +1,9 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Delete an existing key specified by the `region` and `key_id` parameters. Deleting a key is permanent and cannot be undone. All data encrypted using this key, including data encryption keys, will become unusable.
+Permanently delete a key specified by the `region` and `key_id` parameters. This action is irreversible. Any data encrypted with this key, including data encryption keys, will no longer be decipherable.
 
 USAGE:
-  scw keymanager key delete [arg=value ...]
+  scw keymanager key delete <key-id ...> [arg=value ...]
 
 ARGS:
   key-id            ID of the key to delete

cmd/scw/testdata/test-all-usage-keymanager-key-disable-usage.golden

@@ -1,9 +1,9 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Disable a given key to be used for cryptographic operations. Disabling a key renders it unusable. You must specify the `region` and `key_id` parameters.
+Disable a given key, preventing it to be used for cryptographic operations. Disabling a key renders it unusable. You must specify the `region` and `key_id` parameters.
 
 USAGE:
-  scw keymanager key disable [arg=value ...]
+  scw keymanager key disable <key-id ...> [arg=value ...]
 
 ARGS:
   key-id            ID of the key to disable

cmd/scw/testdata/test-all-usage-keymanager-key-enable-usage.golden

@@ -3,7 +3,7 @@
 Enable a given key to be used for cryptographic operations. Enabling a key allows you to make a disabled key usable again. You must specify the `region` and `key_id` parameters.
 
 USAGE:
-  scw keymanager key enable [arg=value ...]
+  scw keymanager key enable <key-id ...> [arg=value ...]
 
 ARGS:
   key-id            ID of the key to enable

cmd/scw/testdata/test-all-usage-keymanager-key-encrypt-usage.golden

@@ -1,9 +1,9 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Encrypt data using an existing key, specified by the `key_id` parameter. Only keys with a usage set to **symmetric_encryption** are supported by this method. The maximum payload size that can be encrypted is 64KB of plaintext.
+Encrypt a payload using an existing key, specified by the `key_id` parameter. Only keys with a usage set to `symmetric_encryption` are supported by this method. The maximum payload size that can be encrypted is 64 KB of plaintext.
 
 USAGE:
-  scw keymanager key encrypt [arg=value ...]
+  scw keymanager key encrypt <key-id ...> [arg=value ...]
 
 ARGS:
   key-id              ID of the key to encrypt

cmd/scw/testdata/test-all-usage-keymanager-key-generate-data-key-usage.golden

@@ -1,17 +1,17 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Generate a new data encryption key to use for cryptographic operations outside of Key Manager. Note that Key Manager does not store your data encryption key. The data encryption key is encrypted and must be decrypted using the key you have created in Key Manager. The data encryption key's plaintext is returned in the response object, for immediate usage.
+Create a new data encryption key for cryptographic operations outside of Key Manager. The data encryption key is encrypted and must be decrypted using the key you have created in Key Manager.
 
-Always store the data encryption key's ciphertext, rather than its plaintext, which must not be stored. To retrieve your key's plaintext, call the Decrypt endpoint with your key's ID and ciphertext.
+The data encryption key is returned in plaintext and ciphertext but it should only be stored in its encrypted form (ciphertext). Key Manager does not store your data encryption key. To retrieve your key's plaintext, use the `Decrypt` method with your key's ID and ciphertext.
 
 USAGE:
-  scw keymanager key generate-data-key [arg=value ...]
+  scw keymanager key generate-data-key <key-id ...> [arg=value ...]
 
 ARGS:
-  key-id                ID of the key
-  [algorithm]           Symmetric encryption algorithm of the data encryption key (unknown_symmetric_encryption | aes_256_gcm)
-  [without-plaintext]   (Optional) Defines whether to return the data encryption key's plaintext in the response object
-  [region=fr-par]       Region to target. If none is passed will use default region from the config (fr-par | nl-ams | pl-waw)
+  key-id                    ID of the key
+  [algorithm=aes_256_gcm]   Algorithm with which the data encryption key will be used to encrypt and decrypt arbitrary payloads (unknown_symmetric_encryption | aes_256_gcm)
+  [without-plaintext]       (Optional) Defines whether to return the data encryption key's plaintext in the response object
+  [region=fr-par]           Region to target. If none is passed will use default region from the config (fr-par | nl-ams | pl-waw)
 
 FLAGS:
   -h, --help   help for generate-data-key

cmd/scw/testdata/test-all-usage-keymanager-key-get-usage.golden

@@ -1,9 +1,9 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Retrieve the metadata of a key specified by the `region` and `key_id` parameters.
+Retrieve metadata for a specified key using the `region` and `key_id` parameters.
 
 USAGE:
-  scw keymanager key get [arg=value ...]
+  scw keymanager key get <key-id ...> [arg=value ...]
 
 ARGS:
   key-id            ID of the key to target

cmd/scw/testdata/test-all-usage-keymanager-key-import-key-material-usage.golden

@@ -0,0 +1,21 @@
+🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
+🟥🟥🟥 STDERR️️ 🟥🟥🟥️
+Import externally generated key material into Key Manager to derive a new cryptographic key. The key's origin must be `external`.
+
+USAGE:
+  scw keymanager key import-key-material <key-id ...> [arg=value ...]
+
+ARGS:
+  key-id            ID of the key in which to import key material
+  [key-material]    The key material The key material is a random sequence of bytes used to derive a cryptographic key.
+  [salt]            (Optional) Salt value to pass the key derivation function
+  [region=fr-par]   Region to target. If none is passed will use default region from the config (fr-par | nl-ams | pl-waw)
+
+FLAGS:
+  -h, --help   help for import-key-material
+
+GLOBAL FLAGS:
+  -c, --config string    The path to the config file
+  -D, --debug            Enable debug mode
+  -o, --output string    Output format: json or human, see 'scw help output' for more info (default "human")
+  -p, --profile string   The config profile to use

cmd/scw/testdata/test-all-usage-keymanager-key-list-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Retrieve the list of keys created within all Projects of an Organization or in a given Project. You must specify the `region`, and either the `organization_id` or the `project_id`.
+Retrieve a list of keys across all Projects in an Organization or within a specific Project. You must specify the `region`, and either the `organization_id` or the `project_id`.
 
 USAGE:
   scw keymanager key list [arg=value ...]

cmd/scw/testdata/test-all-usage-keymanager-key-protect-usage.golden

@@ -1,9 +1,9 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Apply key protection to a given key specified by the `key_id` parameter. Applying key protection means that your key can be used and modified, but it cannot be deleted.
+Apply protection to a given key specified by the `key_id` parameter. Applying key protection means that your key can be used and modified, but it cannot be deleted.
 
 USAGE:
-  scw keymanager key protect [arg=value ...]
+  scw keymanager key protect <key-id ...> [arg=value ...]
 
 ARGS:
   key-id            ID of the key to apply key protection to

cmd/scw/testdata/test-all-usage-keymanager-key-rotate-usage.golden

@@ -1,9 +1,9 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Generate a new version of an existing key with randomly generated key material. Rotated keys can still be used to decrypt previously encrypted data. The key's new material will be used for subsequent encryption operations and data key generation.
+Generate a new version of an existing key with new key material. Previous key versions remain usable to decrypt previously encrypted data, but the key's new version will be used for subsequent encryption operations and data key generation.
 
 USAGE:
-  scw keymanager key rotate [arg=value ...]
+  scw keymanager key rotate <key-id ...> [arg=value ...]
 
 ARGS:
   key-id            ID of the key to rotate

cmd/scw/testdata/test-all-usage-keymanager-key-unprotect-usage.golden

@@ -3,7 +3,7 @@
 Remove key protection from a given key specified by the `key_id` parameter. Removing key protection means that your key can be deleted anytime.
 
 USAGE:
-  scw keymanager key unprotect [arg=value ...]
+  scw keymanager key unprotect <key-id ...> [arg=value ...]
 
 ARGS:
   key-id            ID of the key to remove key protection from

cmd/scw/testdata/test-all-usage-keymanager-key-update-usage.golden

@@ -1,9 +1,9 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Update a key's metadata (name, description and tags), specified by the `key_id` and `region` parameters.
+Modify a key's metadata including name, description and tags, specified by the `key_id` and `region` parameters.
 
 USAGE:
-  scw keymanager key update [arg=value ...]
+  scw keymanager key update <key-id ...> [arg=value ...]
 
 ARGS:
   key-id                               ID of the key to update

cmd/scw/testdata/test-all-usage-keymanager-key-usage.golden

@@ -6,19 +6,21 @@ USAGE:
   scw keymanager key <command>
 
 AVAILABLE COMMANDS:
-  create            Create a key
-  decrypt           Decrypt data
-  delete            Delete a key
-  disable           Disable key
-  enable            Enable key
-  encrypt           Encrypt data
-  generate-data-key Generate a data encryption key
-  get               Get key metadata
-  list              List keys
-  protect           Apply key protection
-  rotate            Rotate a key
-  unprotect         Remove key protection
-  update            Update a key
+  create              Create a key
+  decrypt             Decrypt an encrypted payload
+  delete              Delete a key
+  delete-key-material Delete key material
+  disable             Disable key
+  enable              Enable key
+  encrypt             Encrypt a payload
+  generate-data-key   Create a data encryption key
+  get                 Get key metadata
+  import-key-material Import key material
+  list                List keys
+  protect             Apply key protection
+  rotate              Rotate a key
+  unprotect           Remove key protection
+  update              Update a key
 
 FLAGS:
   -h, --help   help for key