github.com/Venafi/vcert/v5@v5.10.2/README-POLICY-SPEC.md (about) 1 # Venafi Certificate and Key Policy Specification 2 3 The _Venafi Certificate and Key Policy Specification_ is a standard for defining constraints and recommendations that 4 govern key generation and certificate issuance. The specification is consumable by the VCert CLI and VCert-based 5 integrations like the [Venafi Collection for Ansible](https://github.com/Venafi/ansible-collection-venafi) and the 6 [Venafi Provider for HashiCorp Terraform](https://github.com/Venafi/terraform-provider-venafi) that support _Certificate 7 Policy Management_ for Trust Protection Platform (TPP) and Venafi Control Plane (VCP). 8 9 ## Policy-as-Code Structure (JSON) 10 11 The structure of the _Venafi Certificate and Key Policy Specification_ is shown below and is the same starter policy 12 that can be output by executing the `vcert getpolicy --starter` command. The specification has two sections, `policy` 13 and `defaults`. The `policy` section specifies values with which new certificate requests must comply and the `defaults` 14 section specifies values that are recommended for use in certificate requests when those values are not specified or 15 overridden. VCert also supports YAML formatted input specifications. 16 17 ```json 18 { 19 "policy": { 20 "domains": [ "" ], 21 "wildcardAllowed": false, 22 "autoInstalled": false, 23 "maxValidDays": 0, 24 "certificateAuthority": "", 25 "subject": { 26 "orgs": [ "" ], 27 "orgUnits": [ "" ], 28 "localities": [ "" ], 29 "states": [ "" ], 30 "countries": [ "" ] 31 }, 32 "keyPair": { 33 "keyTypes": [ "" ], 34 "rsaKeySizes": [ 0 ], 35 "ellipticCurves": [ "" ], 36 "serviceGenerated": false, 37 "reuseAllowed": false 38 }, 39 "subjectAltNames": { 40 "dnsAllowed": false, 41 "ipAllowed": false, 42 "emailAllowed": false, 43 "uriAllowed": false, 44 "upnAllowed": false 45 } 46 }, 47 "defaults": { 48 "domain": "", 49 "subject": { 50 "org": "", 51 "orgUnits": [ "" ], 52 "locality": "", 53 "state": "", 54 "country": "" 55 }, 56 "keyPair": { 57 "keyType": "", 58 "rsaKeySize": 0, 59 "ellipticCurve": "", 60 "serviceGenerated": false 61 } 62 } 63 } 64 ``` 65 66 ## Policy-as-Code structure 67 68 All parameters in a specification are optional thus `{}` is the simplest valid specification and results in a policy 69 that uses TPP or VCP defaults. 70 71 ### Policy Specification 72 73 | Parameter | Description | Data Type | 74 |------------|------------------------------|------------------------------------------------------------------------------------------------------------------------------------| 75 | `defaults` | [Defaults](#defaults) object | Default values used when Certificate Signing Request does not specify one. Must be a subset of values defined in [Policy](#policy) | 76 | `policy` | [Policy](#policy) object | Values allowed for certificates requested using this policy | 77 78 ### Defaults 79 80 | Parameter | Description | Data Type | 81 |-----------|------------------------------------------|--------------------------------------------------------------------------------------| 82 | `domain` | string | Domain suffix that should be used by default (e.g. "example.com") | 83 | `keyPair` | [DefaultKeyPair](#defaultkeypair) object | The private key type, size and length that should be used by default (e.g. RSA 2048) | 84 | `subject` | [DefaultSubject](#defaultsubject) object | The `subject` values that should be used by default | 85 86 87 ### DefaultKeyPair 88 89 | Parameter | Description | Data Type | 90 |--------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------| 91 | `ellipticCurve` | string | The elliptic curve that should be used by default: "P256", "P384", "P521"<br/>or _"ED25519"_  | 92 | `keyType` | string | Key algorithm that should be used by default, "RSA" or "ECDSA" | 93 | `rsaKeySize` | integer | Number of bits that should be used by default for RSA keys: 512, 1024, 2048, 3072, or 4096 | 94 | `serviceGenerated` | boolean | Indicates whether keys should be generated by the Venafi machine identity service by default | 95 96 ### DefaultSubject 97 98 | Parameter | Description | Data Type | 99 |------------|-----------------|--------------------------------------------------------------------------------------------------------------------------------| 100 | `country` | string | [ISO 3166 2-Alpha](https://www.iso.org/obp/ui/#search/code/) Country (C) code value that should be used by default (e.g. "US") | 101 | `locality` | string | City/Locality (L) value that should be used by default (e.g. "Salt Lake City") | 102 | `org` | string | Organization (O) value that should be used by default (e.g. "Example, Inc.") | 103 | `orgUnits` | array of string | Organizational Unit (OU) values that should be used by default (e.g. "Quality Assurance") | 104 | `state` | string | State/Province (ST) value that should be used by default (e.g. "Utah") | 105 106 ### Policy 107 108 | Parameter | Data Type | Description | 109 |------------------------|--------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 110 | `autoInstalled` | boolean |  Indicates whether the requested certificate will be automatically installed (i.e. provisioned) | 111 | `certificateAuthority` | string |  The distinguished name of a CA Template object.<br />For example, "\VED\Policy\Certificate Authorites\Entrust Advantage"<br /><br /> 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.<br />For example, "DIGICERT\My DigiCert Account\ssl_plus" | 112 | `domains` | array of string | Specifies domain suffixes that are permitted in Common Name (CN) and DNS Subject Alternative Name (SAN) values | 113 | `keyPair` | [KeyPair](#keypair) object | The private key settings allowed for certificates requested using this policy | 114 | `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. | 115 | `subject` | [Subject](#subject) object | The `subject` values allowed for certificates requested using this policy | 116 | `subjectAltNames` | [SubjectAltNames](#subjectaltnames) object | The SANs values allowed for certificates requested using this policy | 117 | `wildcardAllowed` | boolean | Indicates whether CN and DNS SAN values may specify wildcards like "*.example.com" | 118 119 ### KeyPair 120 121 | Parameter | Data Type | Description | 122 |--------------------|------------------|-----------------------------------------------------------------------------------------------------| 123 | `ellipticCurves` | array of string | Permitted elliptic curves: `P256`, `P384`, and/or `P521` | 124 | `keyTypes` | array of string | Key algorithm: `RSA` and/or `ECDSA` | 125 | `reuseAllowed` | boolean | Indicates whether new certificate requests are permitted to reuse a key pair of a known certificate | 126 | `rsaKeySizes` | array of integer | Permitted number of bits for RSA keys: `512`, `1024`, `2048`, `3072`, and/or `4096` | 127 | `serviceGenerated` | boolean | Indicates whether key pair and CSR must be generated by the Venafi machine identity service | 128 129 130 ### Subject 131 132 | Parameter | Data Type | Description | 133 |--------------|-----------------|---------------------------------------------------------------------------------------------------------| 134 | `countries` | array of string | [ISO 3166 2-Alpha](https://www.iso.org/obp/ui/#search/code/) Country (C) code values that are permitted | 135 | `localities` | array of string | City/Locality (L) values that are permitted | 136 | `orgs` | array of string | Organization (O) values that are permitted | 137 | `orgUnits` | array of string | Organizational Unit (OU) values that are permitted | 138 | `states` | array of string | State/Province (ST) values that are permitted | 139 140 ### SubjectAltNames 141 142 | Parameter | Data Type | Description | 143 |----------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------| 144 | `dnsAllowed` | boolean | Indicates whether DNS Subject Alternative Names are permitted | 145 | `ipAllowed` | boolean | Indicates whether IP Address Subject Alternative Names are permitted | 146 | `emailAllowed` | boolean | Indicates whether Email Address (RFC822) Subject Alternative Names are permitted | 147 | `uriAllowed` | boolean | Indicates whether Uniform Resource Indicator (URI) Subject Alternative Names are permitted | 148 | `upnAllowed` | boolean |  Indicates whether User Principal Name (UPN) Subject Alternative Names are permitted |