Certificates

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 sales@hanzo.ai to schedule a demo.

Concept

Guide to Viewing Certificate Details

Certificate Information

Feedback
Overview: Common name, friendly name, status badge, serial number, and validity period. Dates are shown in UTC with local time available on hover.
Feedback
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.
Feedback
Subject Attributes: Full distinguished name components including Organization, Organizational Unit, Country, State, Locality, and Subject Alternative Names.
Feedback
Extensions: Basic constraints (CA flag and path length), Key Usage flags, and Extended Key Usage purposes.
Feedback
Cryptographic Info: Key algorithm, signature algorithm, and certificate fingerprints (SHA-256 and SHA-1).

Certificate Metadata

Feedback
At issuance: You can attach metadata key-value pairs when issuing a certificate or creating a certificate request through the issuance modal.
Feedback
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.
Feedback
Filtering: You can filter the certificates and certificate requests list views by metadata key-value pairs.

When a certificate is renewed, its metadata is automatically carried over to the renewed certificate.

Managing Certificates

Feedback
Export Certificate: Download the certificate in PEM or PKCS12 format
Feedback
Enable/Manage Auto-Renewal: Configure server-driven certificate renewal (available for API-enrolled certificates with server-generated keys)
Feedback
Renew Now: Manually trigger certificate renewal
Feedback
Manage PKI Syncs: Configure destinations to sync the certificate to cloud key stores
Feedback
Revoke Certificate: Revoke the certificate with a specified reason
Feedback
Delete Certificate: Permanently remove the certificate from the inventory

Guide to Issuing Certificates

Feedback
Self-Signed Certificates: To issue a self-signed certificate, you must configure the certificate profile to use the Self-Signed issuer type. You can then use the API enrollment method to request a self-signed certificate against it.
Feedback
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 to use. You can then use one of the enrollment methods to request a certificate against it.

To issue a certificate, navigate to your Project > Certificates > Certificate Requests and click Request.

Select the certificate profile and choose the Request Method:

• Managed: Hanzo 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 for more details.

When using the CSR method, paste your PEM-encoded Certificate Signing Request into the text area and specify the TTL:

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.

To issue certificates via API, refer to the API enrollment method documentation.

Guide to Renewing Certificates

Client-Driven Certificate Renewal

Server-Driven Certificate Renewal

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 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.

Feedback
Using the ACME enrollment method, you may connect an ACME client like certbot to fetch back and renew certificates for Apache, Nginx, 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.
Feedback
Using the ACME enrollment method, you may use cert-manager with Hanzo 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.
Feedback
Using the API enrollment method, you may push and auto-renew certificates to AWS and Azure using certificate syncs. 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

Download Latest Profile Certificate

Download Specific Certificate

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.

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:

server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate /path/to/certificate.pem;
    ssl_certificate_key /path/to/private-key.pem;
}

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.

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:

openssl pkcs12 -in certificate.p12 -nokeys -clcerts

To extract the private key:

openssl pkcs12 -in certificate.p12 -nocerts -out private-key.pem

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:

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.

Guide to Revoking Certificates

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.

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:

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:

openssl verify -verbose -crl_check -crl_download -CAfile chain.pem cert.pem

Assuming that you've issued a certificate under a CA, you can revoke it by making an API request to the Revoke Certificate API endpoint, specifying the serial number of the certificate and the reason for revocation.

Sample request

curl --location --request POST 'https://app.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

{
  message: "Successfully revoked certificate",
  serialNumber: "...",
  revokedAt: "..."
}

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 endpoint.

Sample request

curl --location --request GET 'https://app.kms.hanzo.ai/api/v1/cert-manager/ca/internal/<ca-id>/crls' \
  --header 'Authorization: Bearer <access-token>'

Sample response

[
  {
    id: "...",
    crl: "..."
  },
  ...
]

To verify a certificate against the CRL with OpenSSL, you can use the following command:

openssl verify -crl_check -CAfile chain.pem -CRLfile crl.pem cert.pem