From c4c065ea9e34121d0bea01136bf5d8e54b75209a Mon Sep 17 00:00:00 2001 From: Daniel Hougaard Date: Thu, 3 Apr 2025 08:17:35 +0400 Subject: [PATCH] docs(kms): signing api endpoints --- backend/src/lib/api-docs/constants.ts | 2 +- backend/src/server/routes/v1/cmek-router.ts | 8 ++++---- .../kms/{keys => encryption}/decrypt.mdx | 0 .../kms/{keys => encryption}/encrypt.mdx | 0 .../endpoints/kms/signing/public-key.mdx | 4 ++++ .../endpoints/kms/signing/sign.mdx | 4 ++++ .../kms/signing/signing-algorithms.mdx | 4 ++++ .../endpoints/kms/signing/verify.mdx | 4 ++++ docs/mint.json | 20 ++++++++++++++++--- 9 files changed, 38 insertions(+), 8 deletions(-) rename docs/api-reference/endpoints/kms/{keys => encryption}/decrypt.mdx (100%) rename docs/api-reference/endpoints/kms/{keys => encryption}/encrypt.mdx (100%) create mode 100644 docs/api-reference/endpoints/kms/signing/public-key.mdx create mode 100644 docs/api-reference/endpoints/kms/signing/sign.mdx create mode 100644 docs/api-reference/endpoints/kms/signing/signing-algorithms.mdx create mode 100644 docs/api-reference/endpoints/kms/signing/verify.mdx diff --git a/backend/src/lib/api-docs/constants.ts b/backend/src/lib/api-docs/constants.ts index ac9acf3d1..f60b4223d 100644 --- a/backend/src/lib/api-docs/constants.ts +++ b/backend/src/lib/api-docs/constants.ts @@ -1641,7 +1641,7 @@ export const KMS = { }, VERIFY: { keyId: "The ID of the key to verify the data with.", - data: "The data in string format to be verified (base64 encoded).", + data: "The data in string format to be verified (base64 encoded). For data larger than 4096 bytes you must first create a digest of the data and then pass the digest in the data parameter.", signature: "The signature to be verified (base64 encoded)." } }; diff --git a/backend/src/server/routes/v1/cmek-router.ts b/backend/src/server/routes/v1/cmek-router.ts index 5ad568fd3..0ade455ec 100644 --- a/backend/src/server/routes/v1/cmek-router.ts +++ b/backend/src/server/routes/v1/cmek-router.ts @@ -414,7 +414,7 @@ export const registerCmekRouter = async (server: FastifyZodProvider) => { rateLimit: readLimit }, schema: { - description: "Get public key for a KMS key", + description: "Get the public key for a KMS key that is used for signing and verifying data.", params: z.object({ keyId: z.string().uuid().describe(KMS.GET_PUBLIC_KEY.keyId) }), @@ -444,7 +444,7 @@ export const registerCmekRouter = async (server: FastifyZodProvider) => { rateLimit: readLimit }, schema: { - description: "List signing algorithms for a KMS key", + description: "List all available signing algorithms for a KMS key", params: z.object({ keyId: z.string().uuid().describe(KMS.LIST_SIGNING_ALGORITHMS.keyId) }), @@ -472,7 +472,7 @@ export const registerCmekRouter = async (server: FastifyZodProvider) => { rateLimit: writeLimit }, schema: { - description: "Sign data with KMS key", + description: "Sign data with a KMS key.", params: z.object({ keyId: z.string().uuid().describe(KMS.SIGN.keyId) }), @@ -519,7 +519,7 @@ export const registerCmekRouter = async (server: FastifyZodProvider) => { rateLimit: writeLimit }, schema: { - description: "Verify data with KMS key", + description: "Verify data signatures with a KMS key.", params: z.object({ keyId: z.string().uuid().describe(KMS.VERIFY.keyId) }), diff --git a/docs/api-reference/endpoints/kms/keys/decrypt.mdx b/docs/api-reference/endpoints/kms/encryption/decrypt.mdx similarity index 100% rename from docs/api-reference/endpoints/kms/keys/decrypt.mdx rename to docs/api-reference/endpoints/kms/encryption/decrypt.mdx diff --git a/docs/api-reference/endpoints/kms/keys/encrypt.mdx b/docs/api-reference/endpoints/kms/encryption/encrypt.mdx similarity index 100% rename from docs/api-reference/endpoints/kms/keys/encrypt.mdx rename to docs/api-reference/endpoints/kms/encryption/encrypt.mdx diff --git a/docs/api-reference/endpoints/kms/signing/public-key.mdx b/docs/api-reference/endpoints/kms/signing/public-key.mdx new file mode 100644 index 000000000..4c8e1fda5 --- /dev/null +++ b/docs/api-reference/endpoints/kms/signing/public-key.mdx @@ -0,0 +1,4 @@ +--- +title: "Retrieve Public Key" +openapi: "GET /api/v1/kms/keys/{keyId}/public-key" +--- diff --git a/docs/api-reference/endpoints/kms/signing/sign.mdx b/docs/api-reference/endpoints/kms/signing/sign.mdx new file mode 100644 index 000000000..ebeca5924 --- /dev/null +++ b/docs/api-reference/endpoints/kms/signing/sign.mdx @@ -0,0 +1,4 @@ +--- +title: "Sign Data" +openapi: "POST /api/v1/kms/keys/{keyId}/sign" +--- diff --git a/docs/api-reference/endpoints/kms/signing/signing-algorithms.mdx b/docs/api-reference/endpoints/kms/signing/signing-algorithms.mdx new file mode 100644 index 000000000..0a09ef9e0 --- /dev/null +++ b/docs/api-reference/endpoints/kms/signing/signing-algorithms.mdx @@ -0,0 +1,4 @@ +--- +title: "List Signing Algorithms" +openapi: "GET /api/v1/kms/keys/{keyId}/signing-algorithms" +--- diff --git a/docs/api-reference/endpoints/kms/signing/verify.mdx b/docs/api-reference/endpoints/kms/signing/verify.mdx new file mode 100644 index 000000000..a76270fc3 --- /dev/null +++ b/docs/api-reference/endpoints/kms/signing/verify.mdx @@ -0,0 +1,4 @@ +--- +title: "Verify Signature" +openapi: "POST /api/v1/kms/keys/{keyId}/verify" +--- diff --git a/docs/mint.json b/docs/mint.json index 478db0276..b455967ba 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -1176,9 +1176,23 @@ "api-reference/endpoints/kms/keys/get-by-name", "api-reference/endpoints/kms/keys/create", "api-reference/endpoints/kms/keys/update", - "api-reference/endpoints/kms/keys/delete", - "api-reference/endpoints/kms/keys/encrypt", - "api-reference/endpoints/kms/keys/decrypt" + "api-reference/endpoints/kms/keys/delete" + ] + }, + { + "group": "Encryption", + "pages": [ + "api-reference/endpoints/kms/encryption/encrypt", + "api-reference/endpoints/kms/encryption/decrypt" + ] + }, + { + "group": "Signing", + "pages": [ + "api-reference/endpoints/kms/signing/sign", + "api-reference/endpoints/kms/signing/verify", + "api-reference/endpoints/kms/signing/public-key", + "api-reference/endpoints/kms/signing/signing-algorithms" ] } ]