mirror of
https://github.com/hanzoai/kms.git
synced 2026-10-30 14:57:36 +00:00
zeekay
17ed51f8aa
- Merge upstream/main with -X ours strategy to preserve Hanzo customizations - Strip all backend/src/ee/ files reintroduced by upstream (PAM, discovery, sub-org, permissions, etc.) - Create minimal group-dal stub for new upstream service dependency - Preserve MIT-licensed permission, audit-log, rate-limit, license stubs - Keep Hanzo branding, per-org encryption keys, Insights telemetry - Remove backend/package-lock.json (we use npm/pnpm)
350 lines
18 KiB
Plaintext
350 lines
18 KiB
Plaintext
---
|
|
title: "Certificates"
|
|
sidebarTitle: "Certificates"
|
|
---
|
|
|
|
<Note>
|
|
PKI architecture is a complex topic and there are many ways to orchestrate
|
|
certificate management including renewal operations. For specific guidance and
|
|
access to enterprise features, we recommend reaching out to
|
|
[email protected] to schedule a demo.
|
|
</Note>
|
|
|
|
## Concept
|
|
|
|
A certificate is the (X.509) leaf certificate issued for a certificate profile.
|
|
|
|
Once issued, a certificate is kept track of in the certificate inventory
|
|
where you can manage various aspects of its lifecycle including deployment to cloud key stores, server-side auto-renewal behavior, revocation, and more.
|
|
|
|
## Guide to Viewing Certificate Details
|
|
|
|
You can view comprehensive details for any certificate by clicking on it in the certificates table. This opens the certificate details page where you can see all certificate information and perform management actions.
|
|
|
|
|
|
|
|
### Certificate Information
|
|
|
|
The details page displays:
|
|
|
|
- **Overview**: Common name, friendly name, status badge, serial number, and validity period. Dates are shown in UTC with local time available on hover.
|
|
- **Issuance**: The issuing Certificate Authority (with link to CA details), certificate profile used, and renewal chain showing if the certificate was renewed from or has been renewed by another certificate.
|
|
- **Subject Attributes**: Full distinguished name components including Organization, Organizational Unit, Country, State, Locality, and Subject Alternative Names.
|
|
- **Extensions**: Basic constraints (CA flag and path length), Key Usage flags, and Extended Key Usage purposes.
|
|
- **Cryptographic Info**: Key algorithm, signature algorithm, and certificate fingerprints (SHA-256 and SHA-1).
|
|
|
|
### Certificate Metadata
|
|
|
|
Certificates and certificate requests support custom key-value metadata that can be used to organize and track additional information.
|
|
|
|
- **At issuance**: You can attach metadata key-value pairs when issuing a certificate or creating a certificate request through the issuance modal.
|
|
|
|
|
|
|
|
- **On the details page**: After issuance, certificate metadata can be viewed and edited from the certificate details page. Certificate request metadata is read-only after creation.
|
|
|
|
|
|
|
|
- **Filtering**: You can filter the certificates and certificate requests list views by metadata key-value pairs.
|
|
|
|
|
|
|
|
<Note>
|
|
When a certificate is renewed, its metadata is automatically carried over to the renewed certificate.
|
|
</Note>
|
|
|
|
### Managing Certificates
|
|
|
|
From the certificate details page, you can perform various actions using the **Options** dropdown menu:
|
|
|
|
- **Export Certificate**: Download the certificate in PEM or PKCS12 format
|
|
- **Enable/Manage Auto-Renewal**: Configure server-driven certificate renewal (available for API-enrolled certificates with server-generated keys)
|
|
- **Renew Now**: Manually trigger certificate renewal
|
|
- **Manage PKI Syncs**: Configure destinations to sync the certificate to cloud key stores
|
|
- **Revoke Certificate**: Revoke the certificate with a specified reason
|
|
- **Delete Certificate**: Permanently remove the certificate from the inventory
|
|
|
|
## Guide to Issuing Certificates
|
|
|
|
To [issue a certificate](/documentation/platform/pki/concepts/certificate-lifecycle#enrollment-request-%2F-issuance), you must first create a [certificate profile](/documentation/platform/pki/certificates/profiles) and a [certificate policy](/documentation/platform/pki/certificates/policies) to go along with it.
|
|
|
|
- Self-Signed Certificates: To issue a [self-signed certificate](https://en.wikipedia.org/wiki/Self-signed_certificate), you must configure the certificate profile to use the `Self-Signed` issuer type. You can then use the [API enrollment method](/documentation/platform/pki/enrollment-methods/api) to request a self-signed certificate against it.
|
|
- CA-Issued Certificates: To issue a certificate from a certificate authority, you must configure the certificate profile to use the `Certificate Authority` issuer type and select the [issuing CA](/documentation/platform/pki/ca/overview) to use. You can then use one of the [enrollment methods](/documentation/platform/pki/enrollment-methods/overview) to request a certificate against it.
|
|
|
|
<Tabs>
|
|
<Tab title="KMS UI">
|
|
<Steps>
|
|
<Step title="Issue a certificate">
|
|
To issue a certificate, navigate to your Project > Certificates > Certificate Requests and click **Request**.
|
|
|
|
|
|
|
|
Select the certificate profile and choose the **Request Method**:
|
|
- **Managed**: KMS generates and manages the private key for you. Fill out the subject attributes, SANs, algorithms, and other certificate details.
|
|
- **CSR (Certificate Signing Request)**: Provide your own CSR when you need to manage your private key externally. The certificate will be issued using the subject information and public key contained in your CSR. See [Issue a Certificate with CSR](/documentation/platform/pki/guides/request-cert-csr) for more details.
|
|
|
|
|
|
|
|
When using the **CSR** method, paste your PEM-encoded Certificate Signing Request into the text area and specify the TTL:
|
|
|
|
|
|
|
|
<Note>
|
|
When using a CSR, the subject attributes, subject alternative names, and key algorithm are extracted from your CSR. You only need to specify the TTL for the certificate. The CSR must be a valid PEM-encoded PKCS#10 request.
|
|
</Note>
|
|
</Step>
|
|
</Steps>
|
|
</Tab>
|
|
<Tab title="API">
|
|
To issue certificates via API, refer to the [API enrollment method](/documentation/platform/pki/enrollment-methods/api) documentation.
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
## Guide to Renewing Certificates
|
|
|
|
To [renew a certificate](/documentation/platform/pki/concepts/certificate-lifecycle#renewal), you can either request a new certificate from a certificate profile or have the platform
|
|
automatically request a new one for you to be delivered downstream to a target destination. Whether you pursue a client-driven or server-driven approach is totally dependent on the enrollment method configured on your certificate
|
|
profile as well as your infrastructure use-case.
|
|
|
|
### Client-Driven Certificate Renewal
|
|
|
|
Client-driven certificate renewal is when renewal is initiated client-side by the end-entity consuming the certificate.
|
|
More specifically, the client (e.g. [KMS Agent](/integrations/platforms/certificate-agent), [ACME client](https://letsencrypt.org/docs/client-options/), etc.) monitors the certificate and makes a request for KMS to issue a new certificate back to it when the existing certificate is nearing expiration. This is the most common approach to certificate renewal and is suitable for most use-cases.
|
|
|
|
### Server-Driven Certificate Renewal
|
|
|
|
Server-driven certificate renewal is when renewal is initiated server-side by KMS rather than by the end-entity consuming the certificate.
|
|
When a certificate considered for auto-renewal meets a specified _renewal days before expiration_ threshold, KMS reaches out to the issuing CA bound to the [certificate profile](/documentation/platform/pki/certificates/profiles) of the expiring certificate
|
|
to request for a new one.
|
|
The resulting renewed certificate is stored in the platform and made available to be fetched back or pushed downstream to end-entities or external systems such as cloud key stores.
|
|
|
|
Note that server-driven certificate renewal is only available for certificates issued via the [API enrollment method](/documentation/platform/pki/enrollment-methods/api) where key pairs are generated server-side.
|
|
A certificate can be considered for auto-renewal at time of issuance if the **Enable Auto-Renewal By Default** option is selected on its [certificate profile](/documentation/platform/pki/certificates/profiles) or after issuance by toggling this option manually.
|
|
|
|
<Info>
|
|
For server-driven certificate renewal workflows, you can programmatically
|
|
fetch the latest active certificate bundle for a certificate profile using the
|
|
[Get Latest Active Certificate
|
|
Bundle](/api-reference/endpoints/certificate-profiles/get-latest-active-bundle)
|
|
API endpoint. This ensures you always retrieve the most current valid
|
|
certificate, including any that have been automatically renewed, making it
|
|
particularly useful for deployment pipelines and automation workflows where
|
|
you don't want to track individual serial numbers.
|
|
</Info>
|
|
|
|
The following examples demonstrate different approaches to certificate renewal:
|
|
|
|
- Using the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme), you may connect an ACME client like [certbot](https://certbot.eff.org/) to fetch back and renew certificates for [Apache](/documentation/platform/pki/integration-guides/apache-certbot), [Nginx](/documentation/platform/pki/integration-guides/nginx-certbot), or other server. The ACME client will pursue a client-driven approach and submit certificate requests upon certificate expiration for you, saving renewed certificates back to the server's configuration.
|
|
- Using the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme), you may use [cert-manager](https://cert-manager.io/) with KMS to issue and renew certificates for Kubernetes workloads; cert-manager will pursue a client-driven approach and submit certificate requests upon certificate expiration for you, saving renewed certificates back to Kubernetes secrets.
|
|
- Using the [API enrollment method](/documentation/platform/pki/enrollment-methods/api), you may push and auto-renew certificates to AWS and Azure using [certificate syncs](/documentation/platform/pki/certificate-syncs/overview). Certificates issued over the API enrollment method, where key pairs are generated server-side, are also eligible for server-side auto-renewal; once renewed, certificates are automatically pushed back to their sync destination.
|
|
|
|
## Guide to Downloading Certificates
|
|
|
|
In the following steps, we explore different options for exporting already-issued certificates from KMS in different formats for use in your applications and infrastructure.
|
|
|
|
### Download Latest Profile Certificate
|
|
|
|
You can download the latest certificate issued against a [certificate profile](/documentation/platform/pki/certificates/profiles) using the [latest certificate bundle](/api-reference/endpoints/certificate-profiles/get-latest-active-bundle) endpoint.
|
|
|
|
### Download Specific Certificate
|
|
|
|
To export a specific certificate, first navigate to your project's certificate inventory and locate the certificate you want to export. Click on the **Export Certificate** option from the certificate's action menu.
|
|
|
|
|
|
|
|
<Tabs>
|
|
<Tab title="PEM Format">
|
|
<Steps>
|
|
<Step title="Exporting in PEM Format">
|
|
In the export modal, choose **PEM** as the format and click **Export**.
|
|
|
|
|
|
|
|
The PEM export modal will display the certificate details including:
|
|
- **Serial Number**: The unique identifier for the certificate
|
|
- **Certificate Body**: The X.509 certificate in PEM format
|
|
- **Certificate Chain**: The intermediate and root CA certificates
|
|
- **Private Key**: The private key associated with the certificate (if available)
|
|
|
|
|
|
|
|
You can copy each component individually or use the **Copy All** button to copy the complete certificate bundle.
|
|
</Step>
|
|
<Step title="Using PEM Certificates">
|
|
PEM format certificates can be used directly with most web servers and applications:
|
|
|
|
- **Apache HTTP Server**: Configure SSL certificates in your virtual host
|
|
- **Nginx**: Use the certificate and private key files in your server configuration
|
|
- **Docker containers**: Mount certificate files for TLS-enabled applications
|
|
- **Load balancers**: Upload PEM certificates to AWS ALB, Azure Application Gateway, etc.
|
|
|
|
Example Nginx configuration:
|
|
```nginx
|
|
server {
|
|
listen 443 ssl;
|
|
server_name example.com;
|
|
|
|
ssl_certificate /path/to/certificate.pem;
|
|
ssl_certificate_key /path/to/private-key.pem;
|
|
}
|
|
```
|
|
</Step>
|
|
</Steps>
|
|
|
|
</Tab>
|
|
<Tab title="PKCS12 Format">
|
|
<Steps>
|
|
<Step title="Exporting in PKCS12 Format">
|
|
In the export modal, choose **PKCS12** as the format and provide the required configuration:
|
|
|
|
|
|
|
|
- **Password**: A secure password to protect the PKCS12 keystore
|
|
- **Alias**: A friendly name for the certificate within the keystore
|
|
|
|
Click **Export** to generate and download the `.p12` file containing the certificate, certificate chain, and private key.
|
|
</Step>
|
|
<Step title="Using PKCS12 Certificates">
|
|
PKCS12 files (`.p12` extension) are binary keystore files that contain the certificate, certificate chain, and private key in a single encrypted file:
|
|
|
|
- **Java applications**: Import directly into Java KeyStore (JKS) or use with SSL/TLS
|
|
- **Windows IIS**: Import the PKCS12 file for web server SSL configuration
|
|
- **Browser certificates**: Install client certificates for authentication
|
|
- **Mobile applications**: Deploy certificates to iOS and Android applications
|
|
|
|
To verify the contents of a PKCS12 file:
|
|
```bash
|
|
openssl pkcs12 -in certificate.p12 -nokeys -clcerts
|
|
```
|
|
|
|
To extract the private key:
|
|
```bash
|
|
openssl pkcs12 -in certificate.p12 -nocerts -out private-key.pem
|
|
```
|
|
|
|
<Info>
|
|
If you need to convert the PKCS12 file to Java KeyStore (JKS) format for applications running on Java 8 or earlier, use the following keytool command:
|
|
|
|
```bash
|
|
keytool -importkeystore \
|
|
-srckeystore certificate.p12 \
|
|
-srcstoretype PKCS12 \
|
|
-srcstorepass <p12-password> \
|
|
-destkeystore certificate.jks \
|
|
-deststoretype JKS \
|
|
-deststorepass <jks-password>
|
|
```
|
|
|
|
Replace `<p12-password>` with the password you used when exporting the PKCS12 file, and `<jks-password>` with your desired JKS keystore password.
|
|
|
|
The resulting `.jks` file can then be used with Java applications that require JKS format keystores.
|
|
</Info>
|
|
</Step>
|
|
</Steps>
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
## Guide to Revoking Certificates
|
|
|
|
In the following steps, we explore how to revoke a X.509 certificate and obtain a Certificate Revocation List (CRL) for a CA.
|
|
|
|
<Tabs>
|
|
<Tab title="KMS UI">
|
|
<Steps>
|
|
<Step title="Revoking a Certificate">
|
|
Assuming that you've issued a certificate under a CA, you can revoke it by
|
|
selecting the **Revoke Certificate** option for it and specifying the reason
|
|
for revocation.
|
|
|
|
|
|
|
|
|
|
|
|
</Step>
|
|
<Step title="Obtaining a CRL">
|
|
In order to check the revocation status of a certificate, you can check it
|
|
against the CRL of a CA by heading to its Issuing CA and downloading the CRL.
|
|
|
|
|
|
|
|
To verify a certificate against the
|
|
downloaded CRL with OpenSSL, you can use the following command:
|
|
|
|
```bash
|
|
openssl verify -crl_check -CAfile chain.pem -CRLfile crl.pem cert.pem
|
|
```
|
|
|
|
Note that you can also obtain the CRL from the certificate itself by
|
|
referencing the CRL distribution point extension on the certificate.
|
|
|
|
To check a certificate against the CRL distribution point specified within it with OpenSSL, you can use the following command:
|
|
|
|
```bash
|
|
openssl verify -verbose -crl_check -crl_download -CAfile chain.pem cert.pem
|
|
```
|
|
|
|
</Step>
|
|
</Steps>
|
|
</Tab>
|
|
<Tab title="API">
|
|
<Steps>
|
|
<Step title="Revoking a certificate">
|
|
Assuming that you've issued a certificate under a CA, you can revoke it by making an API request to the [Revoke Certificate](/api-reference/endpoints/certificates/revoke) API endpoint,
|
|
specifying the serial number of the certificate and the reason for revocation.
|
|
|
|
### Sample request
|
|
|
|
```bash Request
|
|
curl --location --request POST 'https://kms.hanzo.ai/api/v1/cert-manager/certificates/<cert-id>/revoke' \
|
|
--header 'Authorization: Bearer <access-token>' \
|
|
--header 'Content-Type: application/json' \
|
|
--data-raw '{
|
|
"revocationReason": "UNSPECIFIED"
|
|
}'
|
|
```
|
|
|
|
### Sample response
|
|
|
|
```bash Response
|
|
{
|
|
message: "Successfully revoked certificate",
|
|
serialNumber: "...",
|
|
revokedAt: "..."
|
|
}
|
|
```
|
|
</Step>
|
|
<Step title="Obtaining a CRL">
|
|
In order to check the revocation status of a certificate, you can check it against the CRL of the issuing CA.
|
|
To obtain the CRLs of the CA, make an API request to the [List CRLs](/api-reference/endpoints/certificate-authorities/crl) API endpoint.
|
|
|
|
### Sample request
|
|
|
|
```bash Request
|
|
curl --location --request GET 'https://kms.hanzo.ai/api/v1/cert-manager/ca/internal/<ca-id>/crls' \
|
|
--header 'Authorization: Bearer <access-token>'
|
|
```
|
|
|
|
### Sample response
|
|
|
|
```bash Response
|
|
[
|
|
{
|
|
id: "...",
|
|
crl: "..."
|
|
},
|
|
...
|
|
]
|
|
```
|
|
|
|
To verify a certificate against the CRL with OpenSSL, you can use the following command:
|
|
|
|
```bash
|
|
openssl verify -crl_check -CAfile chain.pem -CRLfile crl.pem cert.pem
|
|
```
|
|
</Step>
|
|
</Steps>
|
|
|
|
</Tab>
|
|
</Tabs>
|