Skip to main content

Quick Start - CEL in PKI

Before writing a CEL program for custom certificate issuance policies you should understand:

  • the expected output object (ValidationOutput)
  • the embedded certificate template (CertTemplate)
  • the custom functions available in the CEL environment

Table of contents​

ValidationOutput​

Every CelProgram outputs an object of type ValidationOutput when the evaluation is successful.

Parameters​

  • template (CertTemplate: required) - Mirrors x509.Certificate.

  • issuer_ref (string: optional) - The name of the issuer.

  • use_pss (bool: optional) - Whether the token is renewable.

  • signature_bits (uint32: optional) - Specifies the number of bits to use in the signature algorithm.

  • generate_lease (bool: optional) - Specifies if certificates issued/signed against this role will have OpenBao leases attached to them.

  • no_store (bool: optional) - If set, certificates issued/signed against this role will not be stored in the storage backend.

  • warnings ([]string: optional) - Warnings about the request or adjustments made by the CEL policy engine.

  • subject_key_id (bytes: optional) - Provide when signing a CSR if you want to override the SKID that would normally be copied or derived from the CSR’s public-key.

  • key_type (string: optional) - The private key type.

  • key_bits (uint64: optional) - The private key length.

CertTemplate​

The CertTemplate object mirrors an x509 certificate and each parameter can be a CEL expression.

Parameters​

  • Version (int64: optional)

  • Subject (PKIX.Name: optional)

  • NotBefore (google.protobuf.Timestamp: optional)

  • NotAfter (google.protobuf.Timestamp: optional)

  • KeyUsage (KeyUsage: optional)

  • ExtraExtensions ([]PKIX.Extension: optional)

  • ExtKeyUsage (int64: optional)

  • UnknownExtKeyUsage (int64: optional)

  • BasicConstraintsValid (int64: optional)

  • IsCA (int64: optional)

  • MaxPathLen (int64: optional)

  • MaxPathLenZero (int64: optional)

  • SubjectKeyId (int64: optional)

  • DNSNames (int64: optional)

  • EmailAddresses (int64: optional)

  • IPAddresses (int64: optional)

  • URIs (int64: optional)

  • PermittedDNSDomainsCritical (int64: optional)

  • PermittedDNSDomains (int64: optional)

  • ExcludedDNSDomains (int64: optional)

  • PermittedIPRanges (int64: optional)

  • ExcludedIPRanges (int64: optional)

  • PermittedEmailAddresses (int64: optional)

  • ExcludedEmailAddresses (int64: optional)

  • PermittedURIDomains (int64: optional)

  • ExcludedURIDomains (int64: optional)

  • PolicyIdentifiers (int64: optional)

  • Policies (int64: optional)

  • InhibitAnyPolicy (int64: optional)

  • InhibitAnyPolicyZero (int64: optional)

  • InhibitPolicyMapping (int64: optional)

  • InhibitPolicyMappingZero (int64: optional)

  • RequireExplicitPolicy (int64: optional)

  • RequireExplicitPolicyZero (int64: optional)

  • PolicyMappings ([]PolicyMappings: optional)

Custom CEL functions​

OpenBao injects a handful of helper functions into every PKI CEL environment. They behave like regular CEL functions and can be called anywhere an expression is expected.

  • checkValidEmail(value ref.Val) bool - returns true if the value is a syntactically valid e-mail address.

  • Additional helper functions will be documented here as they are added.

Example Usage​

"cel_program": map[string]interface{}{
    "variables": []map[string]interface{}{
        {
            "name": "valid_emails",
            "expression": `check_valid_email(request.alt_names)`,
        },
        {
            "name": "cert",
            "expression": `CertTemplate{
                Subject: PKIX.Name{                   
                CommonName: request.common_name,
            },
            NotAfter: now + duration(request.ttl),
            EmailAddresses: [request.alt_names],		
        }`,
        },
        {
            "name": "output",
            "expression": `ValidationOutput{
                template: cert,						
            }`,
        },
        {
            "name": "err",
            "expression": "'common_name should be a valid email.'",
        },
    },
    "expression": "valid_emails ? output : err",
},