Policy Rules Reference¶
This page describes every rule type available when configuring a certificate policy. Each rule is added to a policy's rule set with a failure mode (hard or soft) and, where required, a values configuration.
For guidance on when to use hard vs soft fail, see Setting Up Certificate Policies — Choosing Failure Modes.
Subject Field Rules¶
enforce_values¶
Enforces specific values for certificate subject fields (Organisation, OU, Country, State, Locality).
Values:
| Field | Description |
|---|---|
organization |
Required Organisation (O) value |
organizational_unit |
Required Organisational Unit (OU) value |
country |
Required Country (C) value — ISO 3166-1 alpha-2 code |
state |
Required State or Province (ST) value |
locality |
Required Locality (L) value |
All fields are optional — include only the fields you want to enforce. If a field is left empty in the certificate request, the policy value is applied automatically. If the field is already set, it must match the policy value exactly.
Common use cases: Enforce consistent organisation name across all certificates; ensure corporate country code is always set.
enforce_key_usage¶
Requires specific Key Usage and Extended Key Usage extensions to be present in the certificate.
Values:
| Field | Description |
|---|---|
key_usage |
Array of required Key Usage values |
extended_key_usage |
Array of required Extended Key Usage values |
Supported Key Usage values:
digitalSignature, keyEncipherment, nonRepudiation, dataEncipherment, keyAgreement, keyCertSign, cRLSign
Supported Extended Key Usage values:
serverAuth, clientAuth, codeSigning, emailProtection, timeStamping
The certificate may include additional key usage values beyond those required — the rule checks for presence, not exact match.
Common use cases: Ensure all TLS server certificates include serverAuth; prevent dual-purpose certificates.
Domain and Scope Rules¶
disable_wildcard¶
Blocks certificate requests where the Common Name or any Subject Alternative Name contains a wildcard (*).
No values required.
Common use cases: Enforce specific hostname certificates rather than wildcards; comply with internal policies that prohibit wildcard issuance.
block_subdomains¶
Prevents certificate issuance for subdomains of the policy's domain scope. Only exact matches to the policy domains are permitted.
No values required.
Example: For a policy scoped to example.com, this rule blocks www.example.com and api.example.com but allows example.com.
Common use cases: Restrict a domain to a single certificate; enforce domain ownership verification.
block_other_domains¶
Alerts or blocks when a certificate request includes domains outside the policy's domain scope.
No values required.
Typically used with Soft Fail to generate visibility into multi-domain certificates rather than to block them outright.
Common use cases: Monitor certificates that span multiple domains; detect unexpected cross-domain certificate requests.
enforce_domain_suffix¶
Requires all names in the certificate (Common Name and SANs) to end with a specified suffix.
Values:
| Field | Description |
|---|---|
suffix |
The required domain suffix (for example, .internal.example.com) |
Common use cases: Restrict certificate issuance to corporate domain names only; prevent external or third-party domain names from being included.
enforce_common_name_pattern¶
Enforces a regular expression pattern against the certificate's Common Name.
Values:
| Field | Description |
|---|---|
pattern |
A regular expression the Common Name must match (case-insensitive) |
Pattern examples:
| Pattern | Matches |
|---|---|
^[a-z0-9-]+\.example\.com$ |
Lowercase hostnames under example.com |
^(www\|api\|mail)\.example\.com$ |
Only www, api, or mail subdomains |
^prod-[a-z0-9]+\.example\.com$ |
Hostnames with a prod- prefix |
Common use cases: Enforce naming conventions; prevent certificates for names that don't conform to corporate standards.
Cryptographic Rules¶
enforce_minimum_key_size¶
Enforces a minimum cryptographic key size. For RSA keys, the size is specified directly in bits. For EC keys, the platform converts EC sizes to RSA equivalents for comparison.
Values:
| Field | Description |
|---|---|
minimum_bits |
Minimum key size in bits |
Common values:
| Value | Notes |
|---|---|
2048 |
Minimum for most current use cases |
3072 |
Recommended for keys protecting data through 2030 (NIST SP 800-57) |
4096 |
High-security environments |
EC key size equivalents:
| EC Key Size | RSA Equivalent |
|---|---|
| EC-256 | ≈ RSA-3072 |
| EC-384 | ≈ RSA-7680 |
| EC-521 | ≈ RSA-15360 |
Common use cases: Phase out weak RSA-1024 keys; comply with PCI-DSS or NIST key strength requirements.
enforce_algorithm¶
Restricts certificates to a specific key algorithm.
Values:
| Field | Options |
|---|---|
algorithm |
rsa — RSA keys only; ecdsa — EC keys only; any — no restriction |
Common use cases: Mandate ECDSA for modern deployments; maintain RSA for legacy compatibility requirements; standardise algorithm across an environment.
enforce_digest¶
Enforces a minimum digest (signature hash) algorithm strength. Stronger digests satisfy the requirement — specifying sha256 allows sha384 and sha512 as well.
Digest strength order (weakest to strongest): sha256 → sha384 → sha512
Values:
| Field | Options |
|---|---|
digest |
sha256, sha384, or sha512 |
Common use cases: Phase out SHA-1; enforce a minimum hash strength for compliance.
Validity Rules¶
enforce_max_validity¶
Limits the maximum certificate validity period in days.
Values:
| Field | Description |
|---|---|
max_days |
Maximum validity in days |
Common values:
| Value | Context |
|---|---|
398 |
CA/Browser Forum maximum for publicly-trusted TLS certificates |
365 |
One-year maximum |
90 |
Short-lived certificates (strong rotation posture) |
Common use cases: Comply with CA/Browser Forum baseline requirements; enforce short-lived certificate policies; reduce the exposure window for compromised certificates.
enforce_min_validity¶
Warns or blocks certificate requests with a validity period shorter than the specified minimum.
Values:
| Field | Description |
|---|---|
min_days |
Minimum validity in days |
Typically used with Soft Fail to catch accidental short validity configurations rather than to block them.
Common use cases: Detect configuration errors; warn when certificates would expire too quickly for operational comfort.
enforce_renewal_window¶
Restricts renewal operations to a specific window before the existing certificate expires. Applies only to certificate.renew actions — skipped for new issuance.
Values:
| Field | Description |
|---|---|
days_before_expiry |
How many days before expiry renewal is permitted |
Typically used with Soft Fail to alert on premature renewal attempts.
Common use cases: Prevent certificates from being renewed months early; standardise renewal timing across automated renewal workflows.
SAN Rules¶
require_san¶
Requires at least one Subject Alternative Name entry to be present.
No values required.
CN-only certificates are deprecated in modern browsers and TLS implementations. Typically used with Soft Fail to encourage compliance without blocking.
Common use cases: Enforce modern certificate standards; prepare for eventual CN deprecation.
enforce_max_san_count¶
Limits the total number of Subject Alternative Names in a certificate.
Values:
| Field | Description |
|---|---|
max_count |
Maximum number of SAN entries |
Common use cases: Prevent unwieldy multi-SAN certificates; manage CA processing limits; control certificate complexity.
block_ip_in_san¶
Prevents IP addresses from appearing in Subject Alternative Names.
No values required.
Detects both IPv4 and IPv6 addresses across all SAN entries.
Common use cases: Enforce DNS-based certificates; comply with public CA requirements that prohibit IP SANs for publicly-trusted certificates.
block_email_in_san¶
Prevents email addresses from appearing in Subject Alternative Names.
No values required.
Common use cases: Enforce certificate purpose separation between server and email certificates; comply with certificate profile requirements.
require_domain_names¶
Requires the Common Name and every Subject Alternative Name to be a domain name. Blocks (or alerts on) short hostnames such as web01, IP addresses, URIs including SPIFFE IDs, email addresses, MAC addresses and phone numbers. Domain names must still belong to a registered domain.
This rule has no values. It is normally used in a policy scoped to a specific certificate authority, so that one certificate authority stays domain-only while others can issue non-domain names:
{
"name": "Prod TLS - domain names only",
"matching_criteria": {
"action": "certificate.generate",
"certificate_authorities": ["<Prod TLS certificate authority uuid>"]
},
"rules": [{ "action": "require_domain_names", "fail": "hard" }]
}
Common use cases: Keep a certificate authority used for public-facing TLS restricted to DNS names; allow SPIFFE and device certificates only from an internal workload certificate authority.
Purpose and CA Rules¶
enforce_certificate_purpose¶
Restricts certificates to a specific purpose, validated via Extended Key Usage.
Values:
| Field | Options |
|---|---|
purpose |
server (server auth only), client (client auth only), code_signing, email |
Common use cases: Prevent dual-purpose certificates; enforce separation between server and client authentication certificates.
block_ca_flag¶
Blocks the issuance of certificates with the CA (isCA) flag set or with keyCertSign in the Key Usage extension.
No values required.
Common use cases: Prevent unauthorised intermediate CA certificate issuance; ensure only leaf certificates are issued through normal certificate request pathways.
require_certificate_transparency¶
Requires Certificate Transparency (CT) logging to be enabled on the certificate request.
No values required.
Common use cases: Comply with public CA requirements (mandatory for all publicly-trusted TLS certificates since 2018); enable external monitoring for mis-issuance.
enforce_integration_ca¶
Requires the certificate to be issued by a specific CA integration, identified by name.
Values:
| Field | Description |
|---|---|
integration_ca |
The name of the required CA integration (case-sensitive) |
Common use cases: Route internal certificates to an internal CA; ensure publicly-trusted certificates are only issued through approved public CA integrations.
set_certificate_authority¶
Automatically sets the CA for matching certificate requests. If no CA is specified in the request, the policy CA is used. If a CA is specified, it must match the policy value.
Values:
| Field | Description |
|---|---|
certificate_authority_id |
The ID of the CA integration to use |
intermediate_cert_id |
Optional, Local PKI certificate authorities only. The intermediate certificate to sign with. It must be issued by the certificate authority's root; the picker only lists those intermediates. |
Common use cases: Automate CA selection so users do not need to choose; ensure certificates for specific domains always use a specific CA.
Operational Rules¶
rate_limit_per_domain¶
Limits the number of certificates that can be issued for a domain within a rolling time window.
Values:
| Field | Description |
|---|---|
max_certificates |
Maximum number of certificates allowed in the period |
period_days |
Length of the rolling window in days |
Typically used with Soft Fail to alert on unusual activity rather than to block legitimate requests.
Common use cases: Detect compromised accounts or runaway automation; monitor certificate issuance rates for compliance.