Issue a Certificate with CSR

When to Use CSR-Based Issuance

Feedback
You need to maintain control of your private key
Feedback
Your security policy requires keys to be generated on the target system
Feedback
You're integrating with Hardware Security Modules (HSMs)
Feedback
You want to use a specific key that already exists
Feedback
You're working with systems that generate their own CSRs (e.g., load balancers, network appliances)

Generating a CSR

Generate a New Key and CSR

# Generate a new RSA private key and CSR
openssl req -new -newkey rsa:2048 -nodes \
  -keyout private.key \
  -out request.csr \
  -subj "/CN=service.example.com/O=My Organization/C=US"

Generate CSR from Existing Key

# Generate CSR from an existing private key
openssl req -new -key private.key -out request.csr \
  -subj "/CN=service.example.com"

Generate CSR with Subject Alternative Names

# Generate CSR with SANs
openssl req -new -newkey rsa:2048 -nodes \
  -keyout private.key \
  -out request.csr \
  -subj "/CN=service.example.com" \
  -addext "subjectAltName=DNS:service.example.com,DNS:www.service.example.com,IP:192.168.1.1"

Generate CSR with ECDSA Key

# Generate ECDSA P-256 key and CSR
openssl ecparam -genkey -name prime256v1 -out private.key
openssl req -new -key private.key -out request.csr \
  -subj "/CN=service.example.com"

Verify Your CSR

openssl req -in request.csr -noout -text

CSR Format Requirements

Feedback
Format: PEM-encoded PKCS#10 Certificate Signing Request
Feedback
Required header: -----BEGIN CERTIFICATE REQUEST-----
Feedback
Required footer: -----END CERTIFICATE REQUEST-----

Supported Key Algorithms

Supported Signature Algorithms

Guide

Next, follow the guide here to create a certificate profile that will be referenced when requesting a certificate.

The certificate profile specifies which certificate policy and issuing CA should be used to validate an incoming certificate request and issue a certificate. You should specify the certificate policy from Step 2, the issuing CA from Step 1, and the API option in the Enrollment Method dropdown when creating the certificate profile.

CSR-based issuance requires a Certificate Authority. Self-signed certificates are not supported when using a CSR.

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

Select CSR (Certificate Signing Request) as the Request Method, then choose your certificate profile.

Paste your PEM-encoded CSR into the text area and specify the TTL for the certificate.

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.

To issue a certificate with a CSR, make an API request to the Issue Certificate API endpoint with your PEM-encoded CSR.

Sample request

curl --location --request POST 'https://app.kms.hanzo.ai/api/v1/cert-manager/certificates' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "profileId": "<certificate-profile-id>",
      "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIICvDCCAaQCAQAwdzELMAkGA1UEBhMCVVMxDTALBgNVBAgMBE9oaW8xEDAOBgNV\nBAcMB0NvbHVtYnMxFzAVBgNVBAoMDk15IE9yZ2FuaXphdGlvbjEcMBoGA1UEAwwT\nc2VydmljZS5leGFtcGxlLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC\nggEBAK...\n-----END CERTIFICATE REQUEST-----",
      "attributes": {
          "ttl": "365d"
      }
  }'

Sample response

{
  "certificate": {
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIEpDCCAowCCQD...\n-----END CERTIFICATE-----",
    "certificateChain": "-----BEGIN CERTIFICATE-----\nMIIEpDCCAowCCQD...\n-----END CERTIFICATE-----",
    "issuingCaCertificate": "-----BEGIN CERTIFICATE-----\nMIIEpDCCAowCCQD...\n-----END CERTIFICATE-----",
    "serialNumber": "123456789012345679",
    "certificateId": "990i4567-e29b-41d4-a716-446655440004"
  },
  "certificateRequestId": "..."
}

No private key is returned when using CSR-based issuance since you manage your own key externally.

When sending the CSR via API:

• Replace actual newlines in the PEM content with \n in the JSON string
• Include the full PEM headers (-----BEGIN CERTIFICATE REQUEST-----) and footers (-----END CERTIFICATE REQUEST-----)

Your CSR must comply with the certificate policy attached to the profile. The policy validates subject attributes, SANs, key algorithms, signature algorithms, key usages, and basic constraints. If your CSR doesn't comply with the policy, you'll receive an error message indicating which constraint was violated.

FAQ

Use Managed (recommended for most cases) when:

• You want Hanzo KMS to handle key generation and storage
• You need server-side auto-renewal capabilities
• You're deploying certificates via certificate syncs to cloud providers
• You want the simplest setup with minimal configuration
• You don't have specific requirements for key custody

Use CSR when:

• Your security policy requires private keys to be generated on the target system
• You're using a Hardware Security Module (HSM) that generates and stores keys
• You need to reuse an existing private key
• You have compliance requirements that mandate key generation in a specific location
• You're integrating with systems that generate their own CSRs (e.g., load balancers, appliances)

Certificates issued via CSR are not eligible for server-side auto-renewal since Hanzo KMS doesn't have access to the private key. You'll need to handle renewal by generating a new CSR and requesting a new certificate.

Certificates issued via CSR cannot be automatically renewed by Hanzo KMS since the private key is managed externally. To renew:

1. Generate a new CSR using your existing private key (or generate a new key pair if desired)
2. Request a new certificate using the new CSR
3. Deploy the new certificate before the old one expires

# Generate a new CSR with your existing key
openssl req -new -key private.key -out request.csr \
  -subj "/CN=service.example.com"

Set up alerts for certificate expiration to ensure timely renewal.

Error: "CSR cannot be empty" or invalid format error

Solution: Ensure your CSR:

• Starts with -----BEGIN CERTIFICATE REQUEST-----
• Ends with -----END CERTIFICATE REQUEST-----
• Contains valid base64-encoded content

The UI accepts multiline PEM format directly—you can paste your CSR as-is from the file without any formatting changes.

Verify your CSR is valid:

openssl req -in request.csr -noout -text

Solution: When sending CSR via API JSON:

• Replace actual newlines with \n in the JSON string
• Include full PEM headers and footers
• Ensure proper JSON escaping

Example format:

{
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC...base64content...\n-----END CERTIFICATE REQUEST-----"
}

Policy validation errors occur when your CSR doesn't comply with the certificate policy attached to the profile. Common errors include:

• Subject attributes: "Missing required {attribute} attribute" or "{attribute} value does not match allowed patterns"
• Subject Alternative Names: "{type} SAN is not allowed by template policy" or "Required {type} SAN not found"
• Key algorithm: "Key algorithm is not allowed by template policy"
• Signature algorithm: "Signature algorithm is not allowed by template policy"

Solution:

1. Review your certificate policy configuration in Project > Certificates > Certificate Policies
2. Ensure your CSR includes all required attributes and SANs
3. Ensure values match allowed patterns configured in the policy
4. Verify your key algorithm is in the policy's allowed list (common options: RSA_2048, RSA_4096, ECDSA_P256, ECDSA_P384)

Example generating a CSR with full subject and SANs:

openssl req -new -key key.pem -out request.csr \
  -subj "/CN=service.example.com/O=My Organization/OU=Engineering/C=US/ST=California/L=San Francisco" \
  -addext "subjectAltName=DNS:service.example.com,DNS:api.example.com"

Error: "Self-signed certificates are not supported for CSR signing"

Solution: CSR-based issuance requires a Certificate Authority to sign the certificate.