Skip to main content

Templates for root CA certificates

See Create a certificate template for step by step instructions on creating templates.

The following example lists all the common parameters used in a root CA certificate template. You can customize them as needed for your organization.

Example JSON

{
  "cert_type": "root",
  "issue_types": ["all"],
  "key_gen": {
    "enabled": true,
    "key_type": {
      "allowed_types": ["rsa", "ecdsa"],
      "default_key_type": "rsa"
    },
    "rsa_key_size": {
      "min_bits": 2048,
      "max_bits": 8192,
      "default_bits": 4096
    },
    "ecdsa_curve": {
      "allowed_curves": ["P-256", "P-384", "P-521"],
      "default_curve": "P-256"
    }
  },
  "signature_algorithm": {
    "allowed_algorithms": [
      "sha256WithRSA",
      "sha384WithRSA",
      "sha512WithRSA",
      "ecdsaWithSHA256",
      "ecdsaWithSHA384",
      "ecdsaWithSHA512"
    ],
    "default_algorithm": "sha256WithRSA"
  },
  "subject": {
    "attributes": [
      { "type": "common_name" },
      { "type": "organization_name" },
      { "type": "country", "include": "optional" },
      { "type": "state", "include": "optional" },
      { "type": "locality", "include": "optional" },
      { "type": "organization_unit", "include": "optional" }
    ]
  },
  "validity": {
    "unit": "years",
    "min_duration": 5,
    "max_duration": 50,
    "default_duration": 25
  },
  "extensions": {
    "key_usage": {
      "critical": true,
      "allow_critical_override": false,
      "required_usages": {
        "rsa": ["key_cert_sign", "crl_sign"],
        "ecdsa": ["key_cert_sign", "crl_sign"]
      },
      "optional_usages": {
        "rsa": ["digital_signature"],
        "ecdsa": ["digital_signature"]
      }
    },
    "extended_key_usage": {
      "include": "yes",
      "usages": {
        "rsa": [],
        "ecdsa": []
      }
    },
    "basic_constraints": {
      "critical": true,
      "is_ca": true,
      "path_length": 1
    },
    "authority_key_identifier": {
      "include": "yes"
    },
    "subject_key_identifier": {
      "include": "yes"
    },
    "certificate_policies": {
      "include": "optional",
      "source": ["request"]
    }
  }
}

Important considerations

  • Key usage extension:

    • Required usages:

      • key_cert_sign - needed to issue subordinate certificates (intermediates or end-entity).

      • crl_sign - required for signing CRLs (certificate revocation lists).

    • Optional usages:

      • digital_signature - allows signing control-plane data, like OCSP responses, or for future-proof flexibility.

    Anmerkung

    Root CAs usually have a minimal key usage. Adding digital_signature is safe but optional.

  • Extended key usage extension:

    • Set to include: yes but leave the usage lists empty for both RSA and ECDSA. This ensures the root CA is broadly usable as a trust anchor without restricting it to a specific use case, like TLS/SSL or email.

    Anmerkung

    Avoid adding Extended key usage to root CAs unless you're building a constrained PKI.

  • Basic constraints:

    • Set is_ca: true to explicitly mark the certificate as a CA.

    • Set path_length: 1 to enforce issuance of only one level of intermediate CA, ensuring a bounded CA hierarchy.

    • Set path_length: 0 to enforce a flat hierarchy.

    Anmerkung

    Skip path_length entirely if you want to allow an unconstrained CA hierarchy.

  • Validity:

    • Default: 25 years, Max: 50 years.

    • Long validity aligns with root CA lifecycles but can be tuned for shorter or staged root rollouts.

  • Other extensions:

    • Set to include: yes for authority_key_identifier and subject_key_identifier.

    • Set to Include: optional and/or source: request for certificate_policies.

    Anmerkung

    These extensions ensure proper chaining, identification, and policy documentation, but do not impose hard validation rules unless specified by relying parties.

In diesem Abschnitt: