diff --git a/backend/src/lib/api-docs/constants.ts b/backend/src/lib/api-docs/constants.ts index ef5c22a23..3dbf02f99 100644 --- a/backend/src/lib/api-docs/constants.ts +++ b/backend/src/lib/api-docs/constants.ts @@ -728,11 +728,10 @@ export const AUDIT_LOG_STREAMS = { } }; -// TODO export const CERTIFICATE_AUTHORITIES = { CREATE: { projectSlug: "Slug of the project to create the CA in.", - type: "The type of CA to create (root or intermediate)", + type: "The type of CA to create", friendlyName: "A friendly name for the CA", organization: "The organization (O) for the CA", ou: "The organization unit (OU) for the CA", @@ -745,23 +744,27 @@ export const CERTIFICATE_AUTHORITIES = { maxPathLength: "The maximum number of intermediate CAs that may follow this CA in the certificate / CA chain. A maxPathLength of -1 implies no path limit on the chain.", keyAlgorithm: - "The type of public key algorithm and size, in bits, of the key pair for the CA; when you create an intermediate CA, you must use a key algorithm supported by the parent CA. This should be one of RSA_2048, RSA_4096, EC_prime256v1, or EC_secp384r1." + "The type of public key algorithm and size, in bits, of the key pair for the CA; when you create an intermediate CA, you must use a key algorithm supported by the parent CA." }, GET: { caId: "The ID of the CA to get" }, UPDATE: { - caId: "The ID of the CA to get", + caId: "The ID of the CA to update", status: "The status of the CA to update to. This can be one of active or disabled" }, DELETE: { caId: "The ID of the CA to delete" }, GET_CSR: { - caId: "The ID of the CA to generate CSR from" + caId: "The ID of the CA to generate CSR from", + csr: "The generated CSR from the CA" }, GET_CERT: { - caId: "The ID of the CA to get the certificate body and certificate chain from" + caId: "The ID of the CA to get the certificate body and certificate chain from", + certificate: "The certificate body of the CA", + certificateChain: "The certificate chain of the CA", + serialNumber: "The serial number of the CA certificate" }, SIGN_INTERMEDIATE: { caId: "The ID of the CA to sign the intermediate certificate with", @@ -769,7 +772,11 @@ export const CERTIFICATE_AUTHORITIES = { notBefore: "The date and time when the intermediate CA becomes valid in YYYY-MM-DDTHH:mm:ss.sssZ format", notAfter: "The date and time when the intermediate CA expires in YYYY-MM-DDTHH:mm:ss.sssZ format", maxPathLength: - "The maximum number of intermediate CAs that may follow this CA in the certificate / CA chain. A maxPathLength of -1 implies no path limit on the chain." + "The maximum number of intermediate CAs that may follow this CA in the certificate / CA chain. A maxPathLength of -1 implies no path limit on the chain.", + certificate: "The signed intermediate certificate", + certificateChain: "The certificate chain of the intermediate certificate", + issuingCaCertificate: "The certificate of the issuing CA", + serialNumber: "The serial number of the intermediate certificate" }, IMPORT_CERT: { caId: "The ID of the CA to import the certificate for", @@ -782,10 +789,16 @@ export const CERTIFICATE_AUTHORITIES = { commonName: "The common name (CN) for the certificate", ttl: "The time to live for the certificate such as 1m, 1h, 1d, 1y, ...", notBefore: "The date and time when the certificate becomes valid in YYYY-MM-DDTHH:mm:ss.sssZ format", - notAfter: "The date and time when the certificate expires in YYYY-MM-DDTHH:mm:ss.sssZ format" + notAfter: "The date and time when the certificate expires in YYYY-MM-DDTHH:mm:ss.sssZ format", + certificate: "The issued certificate", + issuingCaCertificate: "The certificate of the issuing CA", + certificateChain: "The certificate chain of the issued certificate", + privateKey: "The private key of the issued certificate", + serialNumber: "The serial number of the issued certificate" }, GET_CRL: { - caId: "The ID of the CA to get the certificate revocation list (CRL) for" + caId: "The ID of the CA to get the certificate revocation list (CRL) for", + crl: "The certificate revocation list (CRL) of the CA" } }; @@ -796,14 +809,18 @@ export const CERTIFICATES = { REVOKE: { serialNumber: "The serial number of the certificate to revoke. The revoked certificate will be added to the certificate revocation list (CRL) of the CA.", - revocationReason: - "The reason for revoking the certificate. This can be one of UNSPECIFIED, KEY_COMPROMISE, CA_COMPROMISE, AFFILIATION_CHANGED, SUPERSEDED, CESSATION_OF_OPERATION, CERTIFICATE_HOLD, PRIVILEGE_WITHDRAWN, or A_A_COMPROMISE." + revocationReason: "The reason for revoking the certificate.", + revokedAt: "The date and time when the certificate was revoked", + serialNumberRes: "The serial number of the revoked certificate." }, DELETE: { serialNumber: "The serial number of the certificate to delete" }, GET_CERT: { - serialNumber: "The serial number of the certificate to get the certificate body and certificate chain for" + serialNumber: "The serial number of the certificate to get the certificate body and certificate chain for", + certificate: "The certificate body of the certificate", + certificateChain: "The certificate chain of the certificate", + serialNumberRes: "The serial number of the certificate" } }; diff --git a/backend/src/server/routes/v1/certificate-authority-router.ts b/backend/src/server/routes/v1/certificate-authority-router.ts index 7bbaa8373..b0d39df6a 100644 --- a/backend/src/server/routes/v1/certificate-authority-router.ts +++ b/backend/src/server/routes/v1/certificate-authority-router.ts @@ -237,11 +237,11 @@ export const registerCaRouter = async (server: FastifyZodProvider) => { schema: { description: "Get CA CSR", params: z.object({ - caId: z.string().trim() + caId: z.string().trim().describe(CERTIFICATE_AUTHORITIES.GET_CSR.caId) }), response: { 200: z.object({ - csr: z.string() + csr: z.string().describe(CERTIFICATE_AUTHORITIES.GET_CSR.csr) }) } }, @@ -286,9 +286,9 @@ export const registerCaRouter = async (server: FastifyZodProvider) => { }), response: { 200: z.object({ - certificate: z.string(), - certificateChain: z.string(), - serialNumber: z.string() + certificate: z.string().describe(CERTIFICATE_AUTHORITIES.GET_CERT.certificate), + certificateChain: z.string().describe(CERTIFICATE_AUTHORITIES.GET_CERT.certificateChain), + serialNumber: z.string().describe(CERTIFICATE_AUTHORITIES.GET_CERT.serialNumber) }) } }, @@ -341,10 +341,13 @@ export const registerCaRouter = async (server: FastifyZodProvider) => { }), response: { 200: z.object({ - certificate: z.string().trim(), - certificateChain: z.string().trim(), - issuingCaCertificate: z.string().trim(), - serialNumber: z.string().trim() + certificate: z.string().trim().describe(CERTIFICATE_AUTHORITIES.SIGN_INTERMEDIATE.certificate), + certificateChain: z.string().trim().describe(CERTIFICATE_AUTHORITIES.SIGN_INTERMEDIATE.certificateChain), + issuingCaCertificate: z + .string() + .trim() + .describe(CERTIFICATE_AUTHORITIES.SIGN_INTERMEDIATE.issuingCaCertificate), + serialNumber: z.string().trim().describe(CERTIFICATE_AUTHORITIES.SIGN_INTERMEDIATE.serialNumber) }) } }, @@ -468,11 +471,11 @@ export const registerCaRouter = async (server: FastifyZodProvider) => { ), response: { 200: z.object({ - certificate: z.string().trim(), - issuingCaCertificate: z.string().trim(), - certificateChain: z.string().trim(), - privateKey: z.string().trim(), - serialNumber: z.string().trim() + certificate: z.string().trim().describe(CERTIFICATE_AUTHORITIES.ISSUE_CERT.certificate), + issuingCaCertificate: z.string().trim().describe(CERTIFICATE_AUTHORITIES.ISSUE_CERT.issuingCaCertificate), + certificateChain: z.string().trim().describe(CERTIFICATE_AUTHORITIES.ISSUE_CERT.certificateChain), + privateKey: z.string().trim().describe(CERTIFICATE_AUTHORITIES.ISSUE_CERT.privateKey), + serialNumber: z.string().trim().describe(CERTIFICATE_AUTHORITIES.ISSUE_CERT.serialNumber) }) } }, @@ -524,7 +527,7 @@ export const registerCaRouter = async (server: FastifyZodProvider) => { }), response: { 200: z.object({ - crl: z.string() + crl: z.string().describe(CERTIFICATE_AUTHORITIES.GET_CRL.crl) }) } }, diff --git a/backend/src/server/routes/v1/certificate-router.ts b/backend/src/server/routes/v1/certificate-router.ts index 056cc74b9..938fbf7fe 100644 --- a/backend/src/server/routes/v1/certificate-router.ts +++ b/backend/src/server/routes/v1/certificate-router.ts @@ -73,8 +73,8 @@ export const registerCertRouter = async (server: FastifyZodProvider) => { response: { 200: z.object({ message: z.string().trim(), - serialNumber: z.string().trim(), - revokedAt: z.date() + serialNumber: z.string().trim().describe(CERTIFICATES.REVOKE.serialNumberRes), + revokedAt: z.date().describe(CERTIFICATES.REVOKE.revokedAt) }) } }, @@ -169,9 +169,9 @@ export const registerCertRouter = async (server: FastifyZodProvider) => { }), response: { 200: z.object({ - certificate: z.string().trim(), - certificateChain: z.string().trim(), - serialNumber: z.string().trim() + certificate: z.string().trim().describe(CERTIFICATES.GET_CERT.certificate), + certificateChain: z.string().trim().describe(CERTIFICATES.GET_CERT.certificateChain), + serialNumber: z.string().trim().describe(CERTIFICATES.GET_CERT.serialNumberRes) }) } }, diff --git a/docs/api-reference/endpoints/certificate-authority/cert.mdx b/docs/api-reference/endpoints/certificate-authorities/cert.mdx similarity index 100% rename from docs/api-reference/endpoints/certificate-authority/cert.mdx rename to docs/api-reference/endpoints/certificate-authorities/cert.mdx diff --git a/docs/api-reference/endpoints/certificate-authority/create.mdx b/docs/api-reference/endpoints/certificate-authorities/create.mdx similarity index 100% rename from docs/api-reference/endpoints/certificate-authority/create.mdx rename to docs/api-reference/endpoints/certificate-authorities/create.mdx diff --git a/docs/api-reference/endpoints/certificate-authority/crl.mdx b/docs/api-reference/endpoints/certificate-authorities/crl.mdx similarity index 100% rename from docs/api-reference/endpoints/certificate-authority/crl.mdx rename to docs/api-reference/endpoints/certificate-authorities/crl.mdx diff --git a/docs/api-reference/endpoints/certificate-authority/csr.mdx b/docs/api-reference/endpoints/certificate-authorities/csr.mdx similarity index 100% rename from docs/api-reference/endpoints/certificate-authority/csr.mdx rename to docs/api-reference/endpoints/certificate-authorities/csr.mdx diff --git a/docs/api-reference/endpoints/certificate-authority/delete.mdx b/docs/api-reference/endpoints/certificate-authorities/delete.mdx similarity index 100% rename from docs/api-reference/endpoints/certificate-authority/delete.mdx rename to docs/api-reference/endpoints/certificate-authorities/delete.mdx diff --git a/docs/api-reference/endpoints/certificate-authority/import-cert.mdx b/docs/api-reference/endpoints/certificate-authorities/import-cert.mdx similarity index 100% rename from docs/api-reference/endpoints/certificate-authority/import-cert.mdx rename to docs/api-reference/endpoints/certificate-authorities/import-cert.mdx diff --git a/docs/api-reference/endpoints/certificate-authority/issue-cert.mdx b/docs/api-reference/endpoints/certificate-authorities/issue-cert.mdx similarity index 100% rename from docs/api-reference/endpoints/certificate-authority/issue-cert.mdx rename to docs/api-reference/endpoints/certificate-authorities/issue-cert.mdx diff --git a/docs/api-reference/endpoints/certificate-authority/read.mdx b/docs/api-reference/endpoints/certificate-authorities/read.mdx similarity index 100% rename from docs/api-reference/endpoints/certificate-authority/read.mdx rename to docs/api-reference/endpoints/certificate-authorities/read.mdx diff --git a/docs/api-reference/endpoints/certificate-authority/sign-intermediate.mdx b/docs/api-reference/endpoints/certificate-authorities/sign-intermediate.mdx similarity index 100% rename from docs/api-reference/endpoints/certificate-authority/sign-intermediate.mdx rename to docs/api-reference/endpoints/certificate-authorities/sign-intermediate.mdx diff --git a/docs/api-reference/endpoints/certificate-authority/update.mdx b/docs/api-reference/endpoints/certificate-authorities/update.mdx similarity index 100% rename from docs/api-reference/endpoints/certificate-authority/update.mdx rename to docs/api-reference/endpoints/certificate-authorities/update.mdx diff --git a/docs/api-reference/endpoints/certificates/cert-body.mdx b/docs/api-reference/endpoints/certificates/cert-body.mdx new file mode 100644 index 000000000..e4c3b0123 --- /dev/null +++ b/docs/api-reference/endpoints/certificates/cert-body.mdx @@ -0,0 +1,4 @@ +--- +title: "Get Certificate Body / Chain" +openapi: "GET /api/v1/pki/certificates/{serialNumber}/certificate" +--- diff --git a/docs/api-reference/endpoints/certificates/delete.mdx b/docs/api-reference/endpoints/certificates/delete.mdx new file mode 100644 index 000000000..27042af42 --- /dev/null +++ b/docs/api-reference/endpoints/certificates/delete.mdx @@ -0,0 +1,4 @@ +--- +title: "Delete" +openapi: "DELETE /api/v1/pki/certificates/{serialNumber}" +--- diff --git a/docs/api-reference/endpoints/certificates/read.mdx b/docs/api-reference/endpoints/certificates/read.mdx new file mode 100644 index 000000000..ce6463dde --- /dev/null +++ b/docs/api-reference/endpoints/certificates/read.mdx @@ -0,0 +1,4 @@ +--- +title: "Retrieve" +openapi: "GET /api/v1/pki/certificates/{serialNumber}" +--- diff --git a/docs/api-reference/endpoints/certificates/revoke.mdx b/docs/api-reference/endpoints/certificates/revoke.mdx new file mode 100644 index 000000000..e4da73a19 --- /dev/null +++ b/docs/api-reference/endpoints/certificates/revoke.mdx @@ -0,0 +1,4 @@ +--- +title: "Revoke" +openapi: "POST /api/v1/pki/certificates/{serialNumber}/revoke" +--- diff --git a/docs/mint.json b/docs/mint.json index d9914f373..840649d03 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -565,6 +565,30 @@ { "group": "Audit Logs", "pages": ["api-reference/endpoints/audit-logs/export-audit-log"] + }, + { + "group": "Certificate Authorities", + "pages": [ + "api-reference/endpoints/certificate-authorities/create", + "api-reference/endpoints/certificate-authorities/read", + "api-reference/endpoints/certificate-authorities/update", + "api-reference/endpoints/certificate-authorities/delete", + "api-reference/endpoints/certificate-authorities/csr", + "api-reference/endpoints/certificate-authorities/cert", + "api-reference/endpoints/certificate-authorities/sign-intermediate", + "api-reference/endpoints/certificate-authorities/import-cert", + "api-reference/endpoints/certificate-authorities/issue-cert", + "api-reference/endpoints/certificate-authorities/crl" + ] + }, + { + "group": "Certificates", + "pages": [ + "api-reference/endpoints/certificates/read", + "api-reference/endpoints/certificates/revoke", + "api-reference/endpoints/certificates/delete", + "api-reference/endpoints/certificates/cert-body" + ] } ] },