Skip to content

Latest commit

 

History

History
113 lines (106 loc) · 7.36 KB

README-POLICY-SPEC.md

File metadata and controls

113 lines (106 loc) · 7.36 KB
Raw

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 as a Service (VaaS).

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 Parameters

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

Parameter Data Type Description
policy                                  
 domains string array Specifies domain suffixes that are permitted in Common Name (CN) and DNS Subject Alternative Name (SAN) values
 wildcardAllowed boolean Indicates whether CN and DNS SAN values may specify wildcards like "*.example.com"
 autoInstalled boolean TPP Only Indicates whether the requested certificate will be automatically installed (i.e. provisioned)
 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.
 certificateAuthority string TPP: the distinguished name of a CA Template object.
For example, "\VED\Policy\Certificate Authorites\Entrust Advantage"

VaaS: 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"
 subject
  orgs string array Organization (O) values that are permitted
  orgUnits string array Organizational Unit (OU) values that are permitted
  localities string array City/Locality (L) values that are permitted
  states string array State/Province (ST) values that are permitted
  countries string array ISO 3166 2-Alpha Country (C) code values that are permitted
  keyPair
  keyTypes string array Key algorithm: "RSA" and/or "ECDSA" TPP Only
  rsaKeySizes integer array Permitted number of bits for RSA keys: 512, 1024, 2048, 3072, and/or 4096
  ellipticCurves string array TPP Only Permitted elliptic curves: "P256", "P384", and/or "P521"
  serviceGenerated boolean TPP Only Indicates whether key pair and CSR must be generated by the Venafi machine identity service
  reuseAllowed boolean Indicates whether new certificate requests are permitted to reuse a key pair of a known certificate
 subjectAltNames
  dnsAllowed boolean Indicates whether DNS Subject Alternative Names are permitted
  ipAllowed boolean TPP Only Indicates whether IP Address Subject Alternative Names are permitted
  emailAllowed boolean TPP Only Indicates whether Email Address (RFC822) Subject Alternative Names are permitted
  uriAllowed boolean TPP Only 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
defaults
 domain string Domain suffix that should be used by default (e.g. "example.com")
 subject
  org string Organization (O) value that should be used by default (e.g. "Example, Inc.")
  orgUnits string array Organizational Unit (OU) values that should be used by default (e.g. "Quality Assurance")
  locality string City/Locality (L) value that should be used by default (e.g. "Salt Lake City")
  state string State/Province (ST) value that should be used by default (e.g. "Utah")
  country string ISO 3166 2-Alpha Country (C) code value that should be used by default (e.g. "US")
 keyPair
  keyType string Key algorithm that should be used by default, "RSA" or "ECDSA" TPP Only
  rsaKeySize integer Number of bits that should be used by default for RSA keys: 512, 1024, 2048, 3072, or 4096
  ellipticCurve string TPP Only The elliptic curve that should be used by default: "P256", "P384", or "P521"
  serviceGenerated boolean TPP Only Indicates whether keys should be generated by the Venafi machine identity service by default