Skip to content

feat(key_manager): review wording #851

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 5, 2025
Merged

feat(key_manager): review wording #851

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 19 additions & 19 deletions scaleway-async/scaleway_async/key_manager/v1alpha1/api.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ async def create_key(
) -> Key:
"""
Create a key.
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**.
:param unprotected: Default value is `false`.
:param region: Region to target. If none is passed will use default region from the config.
:param project_id: ID of the Project containing the key.
Expand Down Expand Up @@ -118,7 +118,7 @@ async def get_key(
) -> Key:
"""
Get key metadata.
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.
:param key_id: ID of the key to target.
:param region: Region to target. If none is passed will use default region from the config.
:return: :class:`Key <Key>`
Expand Down Expand Up @@ -156,7 +156,7 @@ async def update_key(
) -> Key:
"""
Update a key.
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.
:param key_id: ID of the key to update.
:param region: Region to target. If none is passed will use default region from the config.
:param name: (Optional) Updated name of the key.
Expand Down Expand Up @@ -205,7 +205,7 @@ async def delete_key(
) -> None:
"""
Delete a key.
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.
:param key_id: ID of the key to delete.
:param region: Region to target. If none is passed will use default region from the config.

Expand Down Expand Up @@ -237,7 +237,7 @@ async def rotate_key(
) -> Key:
"""
Rotate a key.
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.
:param key_id: ID of the key to rotate.
:param region: Region to target. If none is passed will use default region from the config.
:return: :class:`Key <Key>`
Expand Down Expand Up @@ -272,7 +272,7 @@ async def protect_key(
) -> Key:
"""
Apply key protection.
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.
:param key_id: ID of the key to apply key protection to.
:param region: Region to target. If none is passed will use default region from the config.
:return: :class:`Key <Key>`
Expand Down Expand Up @@ -377,7 +377,7 @@ async def disable_key(
) -> Key:
"""
Disable key.
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.
:param key_id: ID of the key to disable.
:param region: Region to target. If none is passed will use default region from the config.
:return: :class:`Key <Key>`
Expand Down Expand Up @@ -418,7 +418,7 @@ async def list_keys(
) -> ListKeysResponse:
"""
List keys.
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`.
:param region: Region to target. If none is passed will use default region from the config.
:param organization_id: (Optional) Filter by Organization ID.
:param project_id: (Optional) Filter by Project ID.
Expand Down Expand Up @@ -471,7 +471,7 @@ async def list_keys_all(
) -> List[Key]:
"""
List keys.
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`.
:param region: Region to target. If none is passed will use default region from the config.
:param organization_id: (Optional) Filter by Organization ID.
:param project_id: (Optional) Filter by Project ID.
Expand Down Expand Up @@ -513,10 +513,10 @@ async def generate_data_key(
algorithm: Optional[DataKeyAlgorithmSymmetricEncryption] = None,
) -> DataKey:
"""
Generate a data encryption key.
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 data encryption key.
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.
:param key_id: ID of the key.
:param without_plaintext: Default value is `false`, meaning that the plaintext is returned.
Set it to `true` if you do not wish the plaintext to be returned in the response object.
Expand Down Expand Up @@ -564,8 +564,8 @@ async def encrypt(
associated_data: Optional[str] = None,
) -> EncryptResponse:
"""
Encrypt data.
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.
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.
:param key_id: ID of the key to encrypt.
:param plaintext: Data size must be between 1 and 65535 bytes.
:param region: Region to target. If none is passed will use default region from the config.
Expand Down Expand Up @@ -612,8 +612,8 @@ async def decrypt(
associated_data: Optional[str] = None,
) -> DecryptResponse:
"""
Decrypt data.
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.
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).
:param key_id: ID of the key to decrypt.
:param ciphertext: Data size must be between 1 and 131071 bytes.
:param region: Region to target. If none is passed will use default region from the config.
Expand Down Expand Up @@ -661,11 +661,11 @@ async def import_key_material(
) -> Key:
"""
Import key material.
Import key material to use to derive a new cryptographic key. The key's origin must be `external`.
:param key_id: The key's origin must be 'external'.
Import externally generated key material into Key Manager to derive a new cryptographic key. The key's origin must be `external`.
:param key_id: The key's origin must be `external`.
:param key_material: The key material The key material is a random sequence of bytes used to derive a cryptographic key.
:param region: Region to target. If none is passed will use default region from the config.
:param salt: A salt can be used to improve the quality of randomness when the key material is generated from a low entropy source.
:param salt: A salt is random data added to key material to ensure unique derived keys, even if the input is similar. It helps strengthen security when the key material has low randomness (low entropy).
:return: :class:`Key <Key>`

Usage:
Expand Down
18 changes: 9 additions & 9 deletions scaleway-async/scaleway_async/key_manager/v1alpha1/types.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,12 +66,12 @@ def __str__(self) -> str:
class KeyRotationPolicy:
rotation_period: Optional[str]
"""
Duration between two key rotations. The minimum duration is 24 hours and the maximum duration is 876000 hours (1 year).
Time interval between two key rotations. The minimum duration is 24 hours and the maximum duration is 1 year (876000 hours).
"""

next_rotation_at: Optional[datetime]
"""
Date at which the key will be rotated next.
Timestamp indicating the next scheduled rotation.
"""


Expand Down Expand Up @@ -99,17 +99,17 @@ class Key:

state: KeyState
"""
See the `Key.State` enum for a description of values.
See the `Key.State` enum for a description of possible values.
"""

rotation_count: int
"""
The rotation count tracks the amount of times that the key was rotated.
The rotation count tracks the number of times the key has been rotated.
"""

usage: Optional[KeyUsage]
"""
Keys with a usage set to `symmetric_encryption` are used to encrypt and decrypt data. The only key algorithm currently supported by Key Manager is AES-256-GCM.
Keys with a usage set to `symmetric_encryption` can encrypt and decrypt data using the `AES-256-GCM` key algorithm. Key Manager currently only supports `AES-256-GCM`.
"""

created_at: Optional[datetime]
Expand Down Expand Up @@ -144,7 +144,7 @@ class Key:

region: ScwRegion
"""
Region of the key.
Region where the key is stored.
"""

description: Optional[str]
Expand Down Expand Up @@ -220,7 +220,7 @@ class DataKey:

algorithm: DataKeyAlgorithmSymmetricEncryption
"""
Symmetric encryption algorithm of the data encryption key.
Symmetric encryption algorithm of the data encryption key (`AES-256-GCM`).
"""

ciphertext: str
Expand Down Expand Up @@ -409,7 +409,7 @@ class GetKeyRequest:
class ImportKeyMaterialRequest:
key_id: str
"""
The key's origin must be 'external'.
The key's origin must be `external`.
"""

key_material: str
Expand All @@ -424,7 +424,7 @@ class ImportKeyMaterialRequest:

salt: Optional[str]
"""
A salt can be used to improve the quality of randomness when the key material is generated from a low entropy source.
A salt is random data added to key material to ensure unique derived keys, even if the input is similar. It helps strengthen security when the key material has low randomness (low entropy).
"""


Expand Down
Loading