yandex-cloud/api/kms/v1/index.d.ts

Yandex Cloud SDK

// autogenerated file

import * as grpc from 'grpc';
import { util } from 'protobufjs';
import Long = util.Long;
import * as events from 'events';
import { Session } from '../../../index.js';

import * as protobuf from '../../../contrib/google/protobuf';
import * as operation from '../../../api/operation';
import * as access from '../../../api/access';
import * as SymmetricKey from '../../../SymmetricKey';

/**
 * Set of methods that perform symmetric encryption and decryption.
 */
export class SymmetricCryptoService {
    constructor(session?: Session);
    /**
     * Encrypts given plaintext with the specified key.
     */
    encrypt(
        request: SymmetricEncryptRequest
    ): Promise<SymmetricEncryptResponse>;

    /**
     * Decrypts the given ciphertext with the specified key.
     */
    decrypt(
        request: SymmetricDecryptRequest
    ): Promise<SymmetricDecryptResponse>;

    /**
     * Re-encrypts a ciphertext with the specified KMS key.
     */
    reEncrypt(
        request: SymmetricReEncryptRequest
    ): Promise<SymmetricReEncryptResponse>;

    /**
     * Generates a new symmetric data encryption key (not a KMS key) and returns
     * the generated key as plaintext and as ciphertext encrypted with the specified symmetric KMS key.
     */
    generateDataKey(
        request: GenerateDataKeyRequest
    ): Promise<GenerateDataKeyResponse>;
}

export interface SymmetricEncryptRequest {
    /**
     * ID of the symmetric KMS key to use for encryption.
     */
    keyId: string;

    /**
     * ID of the key version to encrypt plaintext with.
     * Defaults to the primary version if not specified.
     */
    versionId?: string;

    /**
     * Additional authenticated data (AAD context), optional.
     * If specified, this data will be required for decryption with the [SymmetricDecryptRequest].
     * Should be encoded with base64.
     */
    aadContext?: Buffer;

    /**
     * Plaintext to be encrypted.
     * Should be encoded with base64.
     */
    plaintext: Buffer;
}

export interface SymmetricEncryptResponse {
    /**
     * ID of the symmetric KMS key that was used for encryption.
     */
    keyId: string;

    /**
     * ID of the key version that was used for encryption.
     */
    versionId?: string;

    /**
     * Resulting ciphertext.
     */
    ciphertext?: Buffer;
}

export interface SymmetricDecryptRequest {
    /**
     * ID of the symmetric KMS key to use for decryption.
     */
    keyId: string;

    /**
     * Additional authenticated data, must be the same as was provided
     * in the corresponding [SymmetricEncryptRequest].
     * Should be encoded with base64.
     */
    aadContext?: Buffer;

    /**
     * Ciphertext to be decrypted.
     * Should be encoded with base64.
     */
    ciphertext: Buffer;
}

export interface SymmetricDecryptResponse {
    /**
     * ID of the symmetric KMS key that was used for decryption.
     */
    keyId?: string;

    /**
     * ID of the key version that was used for decryption.
     */
    versionId?: string;

    /**
     * Decrypted plaintext.
     */
    plaintext?: Buffer;
}

export interface GenerateDataKeyRequest {
    /**
     * ID of the symmetric KMS key that the generated data key should be encrypted with.
     */
    keyId: string;

    /**
     * ID of the key version to encrypt the generated data key with.
     * Defaults to the primary version if not specified.
     */
    versionId?: string;

    /**
     * Additional authenticated data (AAD context), optional.
     * If specified, this data will be required for decryption with the [SymmetricDecryptRequest].
     * Should be encoded with base64.
     */
    aadContext?: Buffer;

    /**
     * Encryption algorithm and key length for the generated data key.
     */
    dataKeySpec?: SymmetricAlgorithm;

    /**
     * If `true`, the method won't return the data key as plaintext.
     * Default value is `false`.
     */
    skipPlaintext?: boolean;
}

export interface GenerateDataKeyResponse {
    /**
     * ID of the symmetric KMS key that was used to encrypt the generated data key.
     */
    keyId?: string;

    /**
     * ID of the key version that was used for encryption.
     */
    versionId?: string;

    /**
     * Generated data key as plaintext.
     * The field is empty, if the [GenerateDataKeyRequest.skip_plaintext] parameter
     * was set to `true`.
     */
    dataKeyPlaintext?: Buffer;

    /**
     * The encrypted data key.
     */
    dataKeyCiphertext?: Buffer;
}

export interface SymmetricReEncryptRequest {
    /**
     * ID of the new key to be used for encryption.
     */
    keyId: string;

    /**
     * ID of the version of the new key to be used for encryption.
     * Defaults to the primary version if not specified.
     */
    versionId?: string;

    /**
     * Additional authenticated data to be required for decryption.
     * Should be encoded with base64.
     */
    aadContext?: Buffer;

    /**
     * ID of the key that the ciphertext is currently encrypted with. May be the same as for the new key.
     */
    sourceKeyId: string;

    /**
     * Additional authenticated data provided with the initial encryption request.
     * Should be encoded with base64.
     */
    sourceAadContext?: Buffer;

    /**
     * Ciphertext to re-encrypt.
     * Should be encoded with base64.
     */
    ciphertext: Buffer;
}

export interface SymmetricReEncryptResponse {
    /**
     * ID of the key that the ciphertext is encrypted with now.
     */
    keyId?: string;

    /**
     * ID of key version that was used for encryption.
     */
    versionId?: string;

    /**
     * ID of the key that the ciphertext was encrypted with previously.
     */
    sourceKeyId?: string;

    /**
     * ID of the key version that was used to decrypt the re-encrypted ciphertext.
     */
    sourceVersionId?: string;

    /**
     * Resulting re-encrypted ciphertext.
     */
    ciphertext?: Buffer;
}

/**
 * Supported symmetric encryption algorithms.
 */
export enum SymmetricAlgorithm {
    SYMMETRIC_ALGORITHM_UNSPECIFIED = 0,

    /**
     * AES algorithm with 128-bit keys.
     */
    AES_128 = 1,

    /**
     * AES algorithm with 192-bit keys.
     */
    AES_192 = 2,

    /**
     * AES algorithm with 256-bit keys.
     */
    AES_256 = 3,
}

/**
 * A symmetric KMS key that may contain several versions of the cryptographic material.
 */
export interface SymmetricKey {
    /**
     * ID of the key.
     */
    id?: string;

    /**
     * ID of the folder that the key belongs to.
     */
    folderId?: string;

    /**
     * Time when the key was created.
     */
    createdAt?: protobuf.Timestamp;

    /**
     * Name of the key.
     */
    name?: string;

    /**
     * Description of the key.
     */
    description?: string;

    /**
     * Custom labels for the key as `key:value` pairs. Maximum 64 per key.
     */
    labels?: { [s: string]: string };

    /**
     * Current status of the key.
     */
    status?: SymmetricKey.Status;

    /**
     * Primary version of the key, used as the default for all encrypt/decrypt operations,
     * when no version ID is specified.
     */
    primaryVersion?: SymmetricKeyVersion;

    /**
     * Default encryption algorithm to be used with new versions of the key.
     */
    defaultAlgorithm?: SymmetricAlgorithm;

    /**
     * Time of the last key rotation (time when the last version was created).
     * Empty if the key does not have versions yet.
     */
    rotatedAt?: protobuf.Timestamp;

    /**
     * Time period between automatic key rotations.
     */
    rotationPeriod?: protobuf.Duration;
}

export namespace SymmetricKey {
    export enum Status {
        STATUS_UNSPECIFIED = 0,

        /**
         * The key is being created.
         */
        CREATING = 1,

        /**
         * The key is active and can be used for encryption and decryption.
         * Can be set to INACTIVE using the [SymmetricKeyService.Update] method.
         */
        ACTIVE = 2,

        /**
         * The key is inactive and unusable.
         * Can be set to ACTIVE using the [SymmetricKeyService.Update] method.
         */
        INACTIVE = 3,
    }
}

/**
 * Symmetric KMS key version: metadata about actual cryptographic data.
 */
export interface SymmetricKeyVersion {
    /**
     * ID of the key version.
     */
    id?: string;

    /**
     * ID of the symmetric KMS key that the version belongs to.
     */
    keyId?: string;

    /**
     * Status of the key version.
     */
    status?: SymmetricKeyVersion.Status;

    /**
     * Encryption algorithm that should be used when using the key version to encrypt plaintext.
     */
    algorithm?: SymmetricAlgorithm;

    /**
     * Time when the key version was created.
     */
    createdAt?: protobuf.Timestamp;

    /**
     * Indication of a primary version, that is to be used by default for all cryptographic
     * operations that don't have a key version explicitly specified.
     */
    primary?: boolean;

    /**
     * Time when the key version is going to be destroyed. Empty unless the status
     * is `SCHEDULED_FOR_DESTRUCTION`.
     */
    destroyAt?: protobuf.Timestamp;
}

export namespace SymmetricKeyVersion {
    /**
     * Possible version status.
     */
    export enum Status {
        STATUS_UNSPECIFIED = 0,

        /**
         * The version is active and can be used for encryption and decryption.
         */
        ACTIVE = 1,

        /**
         * The version is scheduled for destruction, the time when it will be destroyed
         * is specified in the [SymmetricKeyVersion.destroy_at] field.
         */
        SCHEDULED_FOR_DESTRUCTION = 2,

        /**
         * The version is destroyed and cannot be recovered.
         */
        DESTROYED = 3,
    }
}

/**
 * Set of methods for managing symmetric KMS keys.
 */
export class SymmetricKeyService {
    constructor(session?: Session);
    /**
     * Creates a symmetric KMS key in the specified folder.
     */
    create(request: CreateSymmetricKeyRequest): Promise<operation.Operation>;

    /**
     * Returns the specified symmetric KMS key.
     *
     * To get the list of available symmetric KMS keys, make a [SymmetricKeyService.List] request.
     */
    get(request: GetSymmetricKeyRequest): Promise<SymmetricKey>;

    /**
     * Returns the list of symmetric KMS keys in the specified folder.
     */
    list(request: ListSymmetricKeysRequest): Promise<ListSymmetricKeysResponse>;

    /**
     * Returns the list of versions of the specified symmetric KMS key.
     */
    listVersions(
        request: ListSymmetricKeyVersionsRequest
    ): Promise<ListSymmetricKeyVersionsResponse>;

    /**
     * Updates the specified symmetric KMS key.
     */
    update(request: UpdateSymmetricKeyRequest): Promise<operation.Operation>;

    /**
     * Deletes the specified symmetric KMS key. This action also automatically schedules
     * the destruction of all of the key's versions in 72 hours.
     *
     * The key and its versions appear absent in [SymmetricKeyService.Get] and [SymmetricKeyService.List]
     * requests, but can be restored within 72 hours with a request to tech support.
     */
    delete(request: DeleteSymmetricKeyRequest): Promise<operation.Operation>;

    /**
     * Sets the primary version for the specified key. The primary version is used
     * by default for all encrypt/decrypt operations where no version ID is specified.
     */
    setPrimaryVersion(
        request: SetPrimarySymmetricKeyVersionRequest
    ): Promise<operation.Operation>;

    /**
     * Schedules the specified key version for destruction.
     *
     * Scheduled destruction can be cancelled with the [SymmetricKeyService.CancelVersionDestruction] method.
     */
    scheduleVersionDestruction(
        request: ScheduleSymmetricKeyVersionDestructionRequest
    ): Promise<operation.Operation>;

    /**
     * Cancels previously scheduled version destruction, if the version hasn't been destroyed yet.
     */
    cancelVersionDestruction(
        request: CancelSymmetricKeyVersionDestructionRequest
    ): Promise<operation.Operation>;

    /**
     * Rotates the specified key: creates a new key version and makes it the primary version.
     * The old version remains available for decryption of ciphertext encrypted with it.
     */
    rotate(request: RotateSymmetricKeyRequest): Promise<operation.Operation>;

    /**
     * Lists operations for the specified symmetric KMS key.
     */
    listOperations(
        request: ListSymmetricKeyOperationsRequest
    ): Promise<ListSymmetricKeyOperationsResponse>;

    /**
     * Lists existing access bindings for the specified key.
     */
    listAccessBindings(
        request: access.ListAccessBindingsRequest
    ): Promise<access.ListAccessBindingsResponse>;

    /**
     * Sets access bindings for the key.
     */
    setAccessBindings(
        request: access.SetAccessBindingsRequest
    ): Promise<operation.Operation>;

    /**
     * Updates access bindings for the specified key.
     */
    updateAccessBindings(
        request: access.UpdateAccessBindingsRequest
    ): Promise<operation.Operation>;
}

export interface CreateSymmetricKeyRequest {
    /**
     * ID of the folder to create a symmetric KMS key in.
     */
    folderId: string;

    /**
     * Name of the key.
     */
    name?: string;

    /**
     * Description of the key.
     */
    description?: string;

    /**
     * Custom labels for the symmetric KMS key as `key:value` pairs. Maximum 64 per key.
     * For example, `"project": "mvp"` or `"source": "dictionary"`.
     */
    labels?: { [s: string]: string };

    /**
     * Encryption algorithm to be used with a new key version, generated with the next rotation.
     */
    defaultAlgorithm?: SymmetricAlgorithm;

    /**
     * Interval between automatic rotations. To disable automatic rotation, don't include
     * this field in the creation request.
     */
    rotationPeriod?: protobuf.Duration;
}

export interface CreateSymmetricKeyMetadata {
    /**
     * ID of the key being created.
     */
    keyId?: string;

    /**
     * ID of the primary version of the key being created.
     */
    primaryVersionId?: string;
}

export interface GetSymmetricKeyRequest {
    /**
     * ID of the symmetric KMS key to return.
     * To get the ID of a symmetric KMS key use a [SymmetricKeyService.List] request.
     */
    keyId: string;
}

export interface ListSymmetricKeysRequest {
    /**
     * ID of the folder to list symmetric KMS keys in.
     */
    folderId: string;

    /**
     * The maximum number of results per page to return. If the number of available
     * results is larger than [page_size], the service returns a [ListSymmetricKeysResponse.next_page_token]
     * that can be used to get the next page of results in subsequent list requests.
     * Default value: 100.
     */
    pageSize?: Long;

    /**
     * Page token. To get the next page of results, set [page_token] to the
     * [ListSymmetricKeysResponse.next_page_token] returned by a previous list request.
     */
    pageToken?: string;
}

export interface ListSymmetricKeysResponse {
    /**
     * List of symmetric KMS keys in the specified folder.
     */
    keys?: SymmetricKey[];

    /**
     * This token allows you to get the next page of results for list requests. If the number
     * of results is greater than the specified [ListSymmetricKeysRequest.page_size], use
     * the [next_page_token] as the value for the [ListSymmetricKeysRequest.page_token] query parameter
     * in the next list request. Each subsequent list request will have its own
     * [next_page_token] to continue paging through the results.
     */
    nextPageToken?: string;
}

export interface ListSymmetricKeyVersionsRequest {
    /**
     * ID of the symmetric KMS key to list versions for.
     */
    keyId: string;

    /**
     * The maximum number of results per page to return. If the number of available
     * results is larger than [page_size], the service returns a [ListSymmetricKeyVersionsResponse.next_page_token]
     * that can be used to get the next page of results in subsequent list requests.
     * Default value: 100.
     */
    pageSize?: Long;

    /**
     * Page token. To get the next page of results, set [page_token] to the
     * [ListSymmetricKeyVersionsResponse.next_page_token] returned by a previous list request.
     */
    pageToken?: string;
}

export interface ListSymmetricKeyVersionsResponse {
    /**
     * List of versions for the specified symmetric KMS key.
     */
    keyVersions?: SymmetricKeyVersion[];

    /**
     * This token allows you to get the next page of results for list requests. If the number
     * of results is greater than the specified [ListSymmetricKeyVersionsRequest.page_size], use
     * the [next_page_token] as the value for the [ListSymmetricKeyVersionsRequest.page_token] query parameter
     * in the next list request. Each subsequent list request will have its own
     * [next_page_token] to continue paging through the results.
     */
    nextPageToken?: string;
}

export interface UpdateSymmetricKeyRequest {
    /**
     * ID of the symmetric KMS key to update.
     * To get the ID of a symmetric KMS key use a [SymmetricKeyService.List] request.
     */
    keyId: string;

    /**
     * Field mask that specifies which attributes of the symmetric KMS key are going to be updated.
     */
    updateMask: protobuf.FieldMask;

    /**
     * New name for the symmetric KMS key.
     */
    name?: string;

    /**
     * New description for the symmetric KMS key.
     */
    description?: string;

    /**
     * New status for the symmetric KMS key.
     * Using the [SymmetricKeyService.Update] method you can only set ACTIVE or INACTIVE status.
     */
    status?: SymmetricKey.Status;

    /**
     * Custom labels for the symmetric KMS key as `key:value` pairs. Maximum 64 per key.
     */
    labels?: { [s: string]: string };

    /**
     * Default encryption algorithm to be used with new versions of the symmetric KMS key.
     */
    defaultAlgorithm?: SymmetricAlgorithm;

    /**
     * Time period between automatic symmetric KMS key rotations.
     */
    rotationPeriod?: protobuf.Duration;
}

export interface UpdateSymmetricKeyMetadata {
    /**
     * ID of the key being updated.
     */
    keyId?: string;
}

export interface DeleteSymmetricKeyRequest {
    /**
     * ID of the key to be deleted.
     */
    keyId: string;
}

export interface DeleteSymmetricKeyMetadata {
    /**
     * ID of the key being deleted.
     */
    keyId?: string;
}

export interface SetPrimarySymmetricKeyVersionRequest {
    /**
     * ID of the key to set a primary version for.
     */
    keyId: string;

    /**
     * ID of the version that should become primary for the specified key.
     */
    versionId: string;
}

export interface SetPrimarySymmetricKeyVersionMetadata {
    /**
     * ID of the key that the primary version if being changed for.
     */
    keyId?: string;

    /**
     * ID of the version that is being made primary for the key.
     */
    versionId?: string;
}

export interface RotateSymmetricKeyRequest {
    /**
     * ID of the key to be rotated.
     */
    keyId: string;
}

export interface RotateSymmetricKeyMetadata {
    /**
     * ID of the key being rotated.
     */
    keyId?: string;

    /**
     * ID of the version generated as a result of key rotation.
     */
    newPrimaryVersionId?: string;
}

export interface ScheduleSymmetricKeyVersionDestructionRequest {
    /**
     * ID of the key whose version should be scheduled for destruction.
     */
    keyId: string;

    /**
     * ID of the version to be destroyed.
     */
    versionId: string;

    /**
     * Time interval between the version destruction request and actual destruction.
     * Default value: 7 days.
     */
    pendingPeriod?: protobuf.Duration;
}

export interface ScheduleSymmetricKeyVersionDestructionMetadata {
    /**
     * ID of the key whose version is being scheduled for destruction.
     */
    keyId?: string;

    /**
     * ID of the version that is being scheduled for destruction.
     */
    versionId?: string;

    /**
     * Time when the version is scheduled to be destroyed.
     */
    destroyAt?: protobuf.Timestamp;
}

export interface CancelSymmetricKeyVersionDestructionRequest {
    /**
     * ID of the key to cancel a version's destruction for.
     */
    keyId: string;

    /**
     * ID of the version whose scheduled destruction should be cancelled.
     */
    versionId: string;
}

export interface CancelSymmetricKeyVersionDestructionMetadata {
    /**
     * ID of the key whose version's destruction is being cancelled.
     */
    keyId?: string;

    /**
     * ID of the version whose scheduled destruction is being cancelled.
     */
    versionId?: string;
}

export interface ListSymmetricKeyOperationsRequest {
    /**
     * ID of the symmetric KMS key to get operations for.
     *
     * To get the key ID, use a [SymmetricKeyService.List] request.
     */
    keyId: string;

    /**
     * The maximum number of results per page that should be returned. If the number of available
     * results is larger than [page_size], the service returns a [ListSymmetricKeyOperationsResponse.next_page_token]
     * that can be used to get the next page of results in subsequent list requests.
     * Default value: 100.
     */
    pageSize?: Long;

    /**
     * Page token. To get the next page of results, set [page_token] to the
     * [ListSymmetricKeyOperationsResponse.next_page_token] returned by a previous list request.
     */
    pageToken?: string;
}

export interface ListSymmetricKeyOperationsResponse {
    /**
     * List of operations for the specified key.
     */
    operations?: operation.Operation[];

    /**
     * This token allows you to get the next page of results for list requests. If the number of results
     * is larger than [ListSymmetricKeyOperationsRequest.page_size], use the [next_page_token] as the value
     * for the [ListSymmetricKeyOperationsRequest.page_token] query parameter in the next list request.
     * Each subsequent list request will have its own [next_page_token] to continue paging through the results.
     */
    nextPageToken?: string;
}