feat(key_manager): add sign and verify methods (#2116)

Co-authored-by: Jonathan R. <[email protected]>

Author: scaleway-bot

packages_generated/key_manager/src/v1alpha1/api.gen.ts

@@ -13,13 +13,17 @@ import {
   marshalEncryptRequest,
   marshalGenerateDataKeyRequest,
   marshalImportKeyMaterialRequest,
+  marshalSignRequest,
   marshalUpdateKeyRequest,
+  marshalVerifyRequest,
   unmarshalDataKey,
   unmarshalDecryptResponse,
   unmarshalEncryptResponse,
   unmarshalKey,
   unmarshalListKeysResponse,
   unmarshalPublicKey,
+  unmarshalSignResponse,
+  unmarshalVerifyResponse,
 } from './marshalling.gen'
 import type {
   CreateKeyRequest,
@@ -42,8 +46,12 @@ import type {
   ProtectKeyRequest,
   PublicKey,
   RotateKeyRequest,
+  SignRequest,
+  SignResponse,
   UnprotectKeyRequest,
   UpdateKeyRequest,
+  VerifyRequest,
+  VerifyResponse,
 } from './types.gen'
 
 const jsonContentHeaders = {
@@ -316,6 +324,42 @@ The data encryption key is returned in plaintext and ciphertext but it should on
       unmarshalDecryptResponse,
     )
 
+  /**
+   * Sign a message digest. Use a given key to sign a message digest. The key must have its usage set to `asymmetric_signing`. The digest must be created using the same digest algorithm that is defined in the key's algorithm configuration.
+   *
+   * @param request - The request {@link SignRequest}
+   * @returns A Promise of SignResponse
+   */
+  sign = (request: Readonly<SignRequest>) =>
+    this.client.fetch<SignResponse>(
+      {
+        body: JSON.stringify(marshalSignRequest(request, this.client.settings)),
+        headers: jsonContentHeaders,
+        method: 'POST',
+        path: `/key-manager/v1alpha1/regions/${validatePathParam('region', request.region ?? this.client.settings.defaultRegion)}/keys/${validatePathParam('keyId', request.keyId)}/sign`,
+      },
+      unmarshalSignResponse,
+    )
+
+  /**
+   * Verify a message signature. Use a given key to verify a message signature against a message digest. The key must have its usage set to `asymmetric_signing`. The message digest must be generated using the same digest algorithm that is defined in the key's algorithm configuration.
+   *
+   * @param request - The request {@link VerifyRequest}
+   * @returns A Promise of VerifyResponse
+   */
+  verify = (request: Readonly<VerifyRequest>) =>
+    this.client.fetch<VerifyResponse>(
+      {
+        body: JSON.stringify(
+          marshalVerifyRequest(request, this.client.settings),
+        ),
+        headers: jsonContentHeaders,
+        method: 'POST',
+        path: `/key-manager/v1alpha1/regions/${validatePathParam('region', request.region ?? this.client.settings.defaultRegion)}/keys/${validatePathParam('keyId', request.keyId)}/verify`,
+      },
+      unmarshalVerifyResponse,
+    )
+
   /**
    * Import key material. Import externally generated key material into Key Manager to derive a new cryptographic key. The key's origin must be `external`.
    *

packages_generated/key_manager/src/v1alpha1/index.gen.ts

@@ -19,6 +19,8 @@ export type {
   GetPublicKeyRequest,
   ImportKeyMaterialRequest,
   Key,
+  KeyAlgorithmAsymmetricEncryption,
+  KeyAlgorithmAsymmetricSigning,
   KeyAlgorithmSymmetricEncryption,
   KeyOrigin,
   KeyRotationPolicy,
@@ -30,6 +32,10 @@ export type {
   ProtectKeyRequest,
   PublicKey,
   RotateKeyRequest,
+  SignRequest,
+  SignResponse,
   UnprotectKeyRequest,
   UpdateKeyRequest,
+  VerifyRequest,
+  VerifyResponse,
 } from './types.gen'

packages_generated/key_manager/src/v1alpha1/marshalling.gen.ts

@@ -21,7 +21,11 @@ import type {
   KeyUsage,
   ListKeysResponse,
   PublicKey,
+  SignRequest,
+  SignResponse,
   UpdateKeyRequest,
+  VerifyRequest,
+  VerifyResponse,
 } from './types.gen'
 
 const unmarshalKeyRotationPolicy = (data: unknown): KeyRotationPolicy => {
@@ -45,6 +49,12 @@ const unmarshalKeyUsage = (data: unknown): KeyUsage => {
   }
 
   return {
+    asymmetricEncryption: data.asymmetric_encryption
+      ? data.asymmetric_encryption
+      : undefined,
+    asymmetricSigning: data.asymmetric_signing
+      ? data.asymmetric_signing
+      : undefined,
     symmetricEncryption: data.symmetric_encryption
       ? data.symmetric_encryption
       : undefined,
@@ -148,6 +158,32 @@ export const unmarshalPublicKey = (data: unknown): PublicKey => {
   } as PublicKey
 }
 
+export const unmarshalSignResponse = (data: unknown): SignResponse => {
+  if (!isJSONObject(data)) {
+    throw new TypeError(
+      `Unmarshalling the type 'SignResponse' failed as data isn't a dictionary.`,
+    )
+  }
+
+  return {
+    keyId: data.key_id,
+    signature: data.signature,
+  } as SignResponse
+}
+
+export const unmarshalVerifyResponse = (data: unknown): VerifyResponse => {
+  if (!isJSONObject(data)) {
+    throw new TypeError(
+      `Unmarshalling the type 'VerifyResponse' failed as data isn't a dictionary.`,
+    )
+  }
+
+  return {
+    keyId: data.key_id,
+    valid: data.valid,
+  } as VerifyResponse
+}
+
 const marshalKeyRotationPolicy = (
   request: KeyRotationPolicy,
   defaults: DefaultValues,
@@ -162,6 +198,8 @@ const marshalKeyUsage = (
 ): Record<string, unknown> => ({
   ...resolveOneOf([
     { param: 'symmetric_encryption', value: request.symmetricEncryption },
+    { param: 'asymmetric_encryption', value: request.asymmetricEncryption },
+    { param: 'asymmetric_signing', value: request.asymmetricSigning },
   ]),
 })
 
@@ -217,6 +255,13 @@ export const marshalImportKeyMaterialRequest = (
   salt: request.salt,
 })
 
+export const marshalSignRequest = (
+  request: SignRequest,
+  defaults: DefaultValues,
+): Record<string, unknown> => ({
+  digest: request.digest,
+})
+
 export const marshalUpdateKeyRequest = (
   request: UpdateKeyRequest,
   defaults: DefaultValues,
@@ -229,3 +274,11 @@ export const marshalUpdateKeyRequest = (
       : undefined,
   tags: request.tags,
 })
+
+export const marshalVerifyRequest = (
+  request: VerifyRequest,
+  defaults: DefaultValues,
+): Record<string, unknown> => ({
+  digest: request.digest,
+  signature: request.signature,
+})

packages_generated/key_manager/src/v1alpha1/types.gen.ts

@@ -6,6 +6,23 @@ export type DataKeyAlgorithmSymmetricEncryption =
   | 'unknown_symmetric_encryption'
   | 'aes_256_gcm'
 
+export type KeyAlgorithmAsymmetricEncryption =
+  | 'unknown_asymmetric_encryption'
+  | 'rsa_oaep_2048_sha256'
+  | 'rsa_oaep_3072_sha256'
+  | 'rsa_oaep_4096_sha256'
+
+export type KeyAlgorithmAsymmetricSigning =
+  | 'unknown_asymmetric_signing'
+  | 'ec_p256_sha256'
+  | 'ec_p384_sha384'
+  | 'rsa_pss_2048_sha256'
+  | 'rsa_pss_3072_sha256'
+  | 'rsa_pss_4096_sha256'
+  | 'rsa_pkcs1_2048_sha256'
+  | 'rsa_pkcs1_3072_sha256'
+  | 'rsa_pkcs1_4096_sha256'
+
 export type KeyAlgorithmSymmetricEncryption =
   | 'unknown_symmetric_encryption'
   | 'aes_256_gcm'
@@ -41,9 +58,19 @@ export interface KeyUsage {
   /**
    * See the `Key.Algorithm.SymmetricEncryption` enum for a description of values.
    *
-   * One-of ('usage'): at most one of 'symmetricEncryption' could be set.
+   * One-of ('usage'): at most one of 'symmetricEncryption', 'asymmetricEncryption', 'asymmetricSigning' could be set.
    */
   symmetricEncryption?: KeyAlgorithmSymmetricEncryption
+  /**
+   *
+   * One-of ('usage'): at most one of 'symmetricEncryption', 'asymmetricEncryption', 'asymmetricSigning' could be set.
+   */
+  asymmetricEncryption?: KeyAlgorithmAsymmetricEncryption
+  /**
+   *
+   * One-of ('usage'): at most one of 'symmetricEncryption', 'asymmetricEncryption', 'asymmetricSigning' could be set.
+   */
+  asymmetricSigning?: KeyAlgorithmAsymmetricSigning
 }
 
 export interface Key {
@@ -181,15 +208,15 @@ export type DecryptRequest = {
    */
   region?: ScwRegion
   /**
-   * ID of the key to decrypt.
+   * The key must have an usage set to `symmetric_encryption` or `asymmetric_encryption`.
    */
   keyId: string
   /**
    * Data size must be between 1 and 131071 bytes.
    */
   ciphertext: string
   /**
-   * The additional data must match the value passed in the encryption request.
+   * The additional data must match the value passed in the encryption request. Only supported by keys with a usage set to `symmetric_encryption`.
    */
   associatedData?: string
 }
@@ -259,15 +286,15 @@ export type EncryptRequest = {
    */
   region?: ScwRegion
   /**
-   * ID of the key to encrypt.
+   * The key must have an usage set to `symmetric_encryption` or `asymmetric_encryption`.
    */
   keyId: string
   /**
    * Data size must be between 1 and 65535 bytes.
    */
   plaintext: string
   /**
-   * Additional data which will not be encrypted, but authenticated and appended to the encrypted payload.
+   * Additional data which will not be encrypted, but authenticated and appended to the encrypted payload. Only supported by keys with a usage set to `symmetric_encryption`.
    */
   associatedData?: string
 }
@@ -407,6 +434,32 @@ export type RotateKeyRequest = {
   keyId: string
 }
 
+export type SignRequest = {
+  /**
+   * Region to target. If none is passed will use default region from the config.
+   */
+  region?: ScwRegion
+  /**
+   * ID of the key to use for signing.
+   */
+  keyId: string
+  /**
+   * The digest must be generated using the same algorithm defined in the key’s algorithm settings.
+   */
+  digest: string
+}
+
+export interface SignResponse {
+  /**
+   * ID of the key used to generate the signature.
+   */
+  keyId: string
+  /**
+   * The message signature.
+   */
+  signature: string
+}
+
 export type UnprotectKeyRequest = {
   /**
    * Region to target. If none is passed will use default region from the config.
@@ -444,3 +497,33 @@ export type UpdateKeyRequest = {
    */
   rotationPolicy?: KeyRotationPolicy
 }
+
+export type VerifyRequest = {
+  /**
+   * Region to target. If none is passed will use default region from the config.
+   */
+  region?: ScwRegion
+  /**
+   * ID of the key to use for signature verification.
+   */
+  keyId: string
+  /**
+   * Must be generated using the same algorithm specified in the key’s configuration.
+   */
+  digest: string
+  /**
+   * The message signature to verify.
+   */
+  signature: string
+}
+
+export interface VerifyResponse {
+  /**
+   * ID of the key used for verification.
+   */
+  keyId: string
+  /**
+   * Returns `true` if the signature is valid for the digest and key, `false` otherwise.
+   */
+  valid: boolean
+}