Skip to content

feat(key_manager): review wording #1776

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 2 commits into from
Feb 5, 2025
Merged

feat(key_manager): review wording #1776

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c209b1f
feat: update generated APIs
scaleway-bot Feb 5, 2025
3c47b8d
Merge branch 'main' into v1.6072.0
yfodil Feb 5, 2025
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
80 changes: 42 additions & 38 deletions packages/clients/src/api/key_manager/v1alpha1/api.gen.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ import {
urlParams,
validatePathParam,
} from '../../../bridge'
import type { Region } from '../../../bridge'
import type { Region as ScwRegion } from '../../../bridge'
import {
marshalCreateKeyRequest,
marshalDecryptRequest,
Expand Down Expand Up @@ -55,13 +55,17 @@ const jsonContentHeaders = {
*/
export class API extends ParentAPI {
/** Lists the available regions of the API. */
public static readonly LOCALITIES: Region[] = ['fr-par', 'nl-ams', 'pl-waw']
public static readonly LOCALITIES: ScwRegion[] = [
'fr-par',
'nl-ams',
'pl-waw',
]

/**
* 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.
* encrypt or decrypt arbitrary payloads, or to generate data encryption keys.
* **Data encryption keys are not stored in Key Manager**.
*
* @param request - The request {@link CreateKeyRequest}
* @returns A Promise of Key
Expand All @@ -80,7 +84,7 @@ export class API extends ParentAPI {
)

/**
* Get key metadata. Retrieve the metadata of a key specified by the `region`
* Get key metadata. Retrieve metadata for a specified key using the `region`
* and `key_id` parameters.
*
* @param request - The request {@link GetKeyRequest}
Expand All @@ -96,7 +100,7 @@ export class API extends ParentAPI {
)

/**
* Update a key. Update a key's metadata (name, description and tags),
* Update a key. Modify a key's metadata including name, description and tags,
* specified by the `key_id` and `region` parameters.
*
* @param request - The request {@link UpdateKeyRequest}
Expand All @@ -116,10 +120,9 @@ export class API extends ParentAPI {
)

/**
* 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.
* Delete a key. 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 request - The request {@link DeleteKeyRequest}
*/
Expand All @@ -130,10 +133,10 @@ export class API extends ParentAPI {
})

/**
* 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.
* Rotate a key. 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 request - The request {@link RotateKeyRequest}
* @returns A Promise of Key
Expand All @@ -150,7 +153,7 @@ export class API extends ParentAPI {
)

/**
* Apply key protection. Apply key protection to a given key specified by the
* Apply key protection. 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.
*
Expand Down Expand Up @@ -207,9 +210,9 @@ export class API extends ParentAPI {
)

/**
* 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 key. 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 request - The request {@link DisableKeyRequest}
* @returns A Promise of Key
Expand Down Expand Up @@ -247,9 +250,9 @@ export class API extends ParentAPI {
)

/**
* 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`.
* List keys. 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 request - The request {@link ListKeysRequest}
* @returns A Promise of ListKeysResponse
Expand All @@ -258,16 +261,15 @@ export class API extends ParentAPI {
enrichForPagination('keys', this.pageOfListKeys, request)

/**
* 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
* 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. The data encryption key's plaintext is returned in the response
* object, for immediate usage.
* 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 request - The request {@link GenerateDataKeyRequest}
* @returns A Promise of DataKey
Expand All @@ -286,10 +288,10 @@ export class API extends ParentAPI {
)

/**
* 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 request - The request {@link EncryptRequest}
* @returns A Promise of EncryptResponse
Expand All @@ -308,9 +310,10 @@ export class API extends ParentAPI {
)

/**
* 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 request - The request {@link DecryptRequest}
* @returns A Promise of DecryptResponse
Expand All @@ -329,8 +332,9 @@ export class API extends ParentAPI {
)

/**
* Import key material. Import key material to use to derive a new
* cryptographic key. The key's origin must be `external`.
* Import key material. Import externally generated key material into Key
* Manager to derive a new cryptographic key. The key's origin must be
* `external`.
*
* @param request - The request {@link ImportKeyMaterialRequest}
* @returns A Promise of Key
Expand Down
61 changes: 31 additions & 30 deletions packages/clients/src/api/key_manager/v1alpha1/types.gen.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
// This file was automatically generated. DO NOT EDIT.
// If you have any remark or suggestion do not hesitate to open an issue.
import type { Region } from '../../../bridge'
import type { Region as ScwRegion } from '../../../bridge'

export type DataKeyAlgorithmSymmetricEncryption =
| 'unknown_symmetric_encryption'
Expand Down Expand Up @@ -28,11 +28,11 @@ export type ListKeysRequestOrderBy =

export interface KeyRotationPolicy {
/**
* 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).
*/
rotationPeriod?: string
/** Date at which the key will be rotated next. */
/** Timestamp indicating the next scheduled rotation. */
nextRotationAt?: Date
}

Expand All @@ -54,14 +54,14 @@ export interface Key {
/** Name of the key. */
name: string
/**
* 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`.
*/
usage?: KeyUsage
/** See the `Key.State` enum for a description of values. */
/** See the `Key.State` enum for a description of possible values. */
state: KeyState
/** 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. */
rotationCount: number
/** Key creation date. */
createdAt?: Date
Expand All @@ -81,16 +81,16 @@ export interface Key {
rotationPolicy?: KeyRotationPolicy
/** Refer to the `Key.Origin` enum for a description of values. */
origin: KeyOrigin
/** Region of the key. */
region: Region
/** Region where the key is stored. */
region: ScwRegion
}

export type CreateKeyRequest = {
/**
* Region to target. If none is passed will use default region from the
* config.
*/
region?: Region
region?: ScwRegion
/** ID of the Project containing the key. */
projectId?: string
/** (Optional) Name of the key. */
Expand All @@ -115,7 +115,7 @@ export type CreateKeyRequest = {
export interface DataKey {
/** ID of the data encryption key. */
keyId: string
/** Symmetric encryption algorithm of the data encryption key. */
/** Symmetric encryption algorithm of the data encryption key (`AES-256-GCM`). */
algorithm: DataKeyAlgorithmSymmetricEncryption
/**
* Your data encryption key's ciphertext can be stored safely. It can only be
Expand All @@ -137,7 +137,7 @@ export type DecryptRequest = {
* Region to target. If none is passed will use default region from the
* config.
*/
region?: Region
region?: ScwRegion
/** ID of the key to decrypt. */
keyId: string
/** Data size must be between 1 and 131071 bytes. */
Expand All @@ -163,7 +163,7 @@ export type DeleteKeyMaterialRequest = {
* Region to target. If none is passed will use default region from the
* config.
*/
region?: Region
region?: ScwRegion
/** ID of the key of which to delete the key material. */
keyId: string
}
Expand All @@ -173,7 +173,7 @@ export type DeleteKeyRequest = {
* Region to target. If none is passed will use default region from the
* config.
*/
region?: Region
region?: ScwRegion
/** ID of the key to delete. */
keyId: string
}
Expand All @@ -183,7 +183,7 @@ export type DisableKeyRequest = {
* Region to target. If none is passed will use default region from the
* config.
*/
region?: Region
region?: ScwRegion
/** ID of the key to disable. */
keyId: string
}
Expand All @@ -193,7 +193,7 @@ export type EnableKeyRequest = {
* Region to target. If none is passed will use default region from the
* config.
*/
region?: Region
region?: ScwRegion
/** ID of the key to enable. */
keyId: string
}
Expand All @@ -203,7 +203,7 @@ export type EncryptRequest = {
* Region to target. If none is passed will use default region from the
* config.
*/
region?: Region
region?: ScwRegion
/** ID of the key to encrypt. */
keyId: string
/** Data size must be between 1 and 65535 bytes. */
Expand All @@ -227,7 +227,7 @@ export type GenerateDataKeyRequest = {
* Region to target. If none is passed will use default region from the
* config.
*/
region?: Region
region?: ScwRegion
/** ID of the key. */
keyId: string
/**
Expand All @@ -248,7 +248,7 @@ export type GetKeyRequest = {
* Region to target. If none is passed will use default region from the
* config.
*/
region?: Region
region?: ScwRegion
/** ID of the key to target. */
keyId: string
}
Expand All @@ -258,17 +258,18 @@ export type ImportKeyMaterialRequest = {
* Region to target. If none is passed will use default region from the
* config.
*/
region?: Region
/** The key's origin must be 'external'. */
region?: ScwRegion
/** The key's origin must be `external`. */
keyId: string
/**
* The key material The key material is a random sequence of bytes used to
* derive a cryptographic key.
*/
keyMaterial: string
/**
* 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).
*/
salt?: string
}
Expand All @@ -278,7 +279,7 @@ export type ListKeysRequest = {
* Region to target. If none is passed will use default region from the
* config.
*/
region?: Region
region?: ScwRegion
/** (Optional) Filter by Organization ID. */
organizationId?: string
/** (Optional) Filter by Project ID. */
Expand All @@ -304,7 +305,7 @@ export type ProtectKeyRequest = {
* Region to target. If none is passed will use default region from the
* config.
*/
region?: Region
region?: ScwRegion
/** ID of the key to apply key protection to. */
keyId: string
}
Expand All @@ -314,7 +315,7 @@ export type RotateKeyRequest = {
* Region to target. If none is passed will use default region from the
* config.
*/
region?: Region
region?: ScwRegion
/** ID of the key to rotate. */
keyId: string
}
Expand All @@ -324,7 +325,7 @@ export type UnprotectKeyRequest = {
* Region to target. If none is passed will use default region from the
* config.
*/
region?: Region
region?: ScwRegion
/** ID of the key to remove key protection from. */
keyId: string
}
Expand All @@ -334,7 +335,7 @@ export type UpdateKeyRequest = {
* Region to target. If none is passed will use default region from the
* config.
*/
region?: Region
region?: ScwRegion
/** ID of the key to update. */
keyId: string
/** (Optional) Updated name of the key. */
Expand Down
Loading