Skip to content

Latest commit

 

History

History
148 lines (124 loc) · 14.7 KB

README-POLICY-SPEC.md

File metadata and controls

148 lines (124 loc) · 14.7 KB

Venafi Certificate and Key Policy Specification

The Venafi Certificate and Key Policy Specification is a standard for defining constraints and recommendations that govern key generation and certificate issuance. The specification is consumable by the VCert CLI and VCert-based integrations like the Venafi Collection for Ansible and the Venafi Provider for HashiCorp Terraform that support Certificate Policy Management for Trust Protection Platform (TPP) and Venafi Control Plane (VCP).

Policy-as-Code Structure (JSON)

The structure of the Venafi Certificate and Key Policy Specification is shown below and is the same starter policy that can be output by executing the vcert getpolicy --starter command. The specification has two sections, policy and defaults. The policy section specifies values with which new certificate requests must comply and the defaults section specifies values that are recommended for use in certificate requests when those values are not specified or overridden. VCert also supports YAML formatted input specifications.

{
  "policy": {
    "domains": [ "" ],
    "wildcardAllowed": false,
    "autoInstalled": false,
    "maxValidDays": 0,
    "certificateAuthority": "",
    "subject": {
      "orgs": [ "" ],
      "orgUnits": [ "" ],
      "localities": [ "" ],
      "states": [ "" ],
      "countries": [ "" ]
    },
    "keyPair": {
      "keyTypes": [ "" ],
      "rsaKeySizes": [ 0 ],
      "ellipticCurves": [ "" ],
      "serviceGenerated": false,
      "reuseAllowed": false
    },
    "subjectAltNames": {
      "dnsAllowed": false,
      "ipAllowed": false,
      "emailAllowed": false,
      "uriAllowed": false,
      "upnAllowed": false
    }
  },
  "defaults": {
    "domain": "",
    "subject": {
      "org": "",
      "orgUnits": [ "" ],
      "locality": "",
      "state": "",
      "country": ""
    },
    "keyPair": {
      "keyType": "",
      "rsaKeySize": 0,
      "ellipticCurve": "",
      "serviceGenerated": false
    }
  }
}

Policy-as-Code structure

All parameters in a specification are optional thus {} is the simplest valid specification and results in a policy that uses TPP or VCP defaults.

Policy Specification

Parameter Description Data Type
defaults Defaults object Default values used when Certificate Signing Request does not specify one. Must be a subset of values defined in Policy
policy Policy object Values allowed for certificates requested using this policy

Defaults

Parameter Description Data Type
domain string Domain suffix that should be used by default (e.g. "example.com")
keyPair DefaultKeyPair object The private key type, size and length that should be used by default (e.g. RSA 2048)
subject DefaultSubject object The subject values that should be used by default

DefaultKeyPair

Parameter Description Data Type
ellipticCurve string The elliptic curve that should be used by default: "P256", "P384", "P521"
or "ED25519" VCP Only
keyType string Key algorithm that should be used by default, "RSA" or "ECDSA"
rsaKeySize integer Number of bits that should be used by default for RSA keys: 512, 1024, 2048, 3072, or 4096
serviceGenerated boolean Indicates whether keys should be generated by the Venafi machine identity service by default

DefaultSubject

Parameter Description Data Type
country string ISO 3166 2-Alpha Country (C) code value that should be used by default (e.g. "US")
locality string City/Locality (L) value that should be used by default (e.g. "Salt Lake City")
org string Organization (O) value that should be used by default (e.g. "Example, Inc.")
orgUnits array of string Organizational Unit (OU) values that should be used by default (e.g. "Quality Assurance")
state string State/Province (ST) value that should be used by default (e.g. "Utah")

Policy

Parameter Data Type Description
autoInstalled boolean TPP Only Indicates whether the requested certificate will be automatically installed (i.e. provisioned)
certificateAuthority string TPP The distinguished name of a CA Template object.
For example, "\VED\Policy\Certificate Authorites\Entrust Advantage"

VCP CA Account Type ("DIGICERT", "ENTRUST", "GLOBALSIGN", or "BUILTIN"), CA Account Name (as it appears in the web console), and CA Product Type delimited by backslash characters.
For example, "DIGICERT\My DigiCert Account\ssl_plus"
domains array of string Specifies domain suffixes that are permitted in Common Name (CN) and DNS Subject Alternative Name (SAN) values
keyPair KeyPair object The private key settings allowed for certificates requested using this policy
maxValidDays integer Number of days for which the requested certificate will be valid. May be ignored if the integration with the issuing CA does not support specific end dates.
subject Subject object The subject values allowed for certificates requested using this policy
subjectAltNames SubjectAltNames object The SANs values allowed for certificates requested using this policy
wildcardAllowed boolean Indicates whether CN and DNS SAN values may specify wildcards like "*.example.com"

KeyPair

Parameter Data Type Description
ellipticCurves array of string Permitted elliptic curves: P256, P384, and/or P521
keyTypes array of string Key algorithm: RSA and/or ECDSA
reuseAllowed boolean Indicates whether new certificate requests are permitted to reuse a key pair of a known certificate
rsaKeySizes array of integer Permitted number of bits for RSA keys: 512, 1024, 2048, 3072, and/or 4096
serviceGenerated boolean Indicates whether key pair and CSR must be generated by the Venafi machine identity service

Subject

Parameter Data Type Description
countries array of string ISO 3166 2-Alpha Country (C) code values that are permitted
localities array of string City/Locality (L) values that are permitted
orgs array of string Organization (O) values that are permitted
orgUnits array of string Organizational Unit (OU) values that are permitted
states array of string State/Province (ST) values that are permitted

SubjectAltNames

Parameter Data Type Description
dnsAllowed boolean Indicates whether DNS Subject Alternative Names are permitted
ipAllowed boolean Indicates whether IP Address Subject Alternative Names are permitted
emailAllowed boolean Indicates whether Email Address (RFC822) Subject Alternative Names are permitted
uriAllowed boolean Indicates whether Uniform Resource Indicator (URI) Subject Alternative Names are permitted
upnAllowed boolean TPP Only Indicates whether User Principal Name (UPN) Subject Alternative Names are permitted