github.com/Venafi/vcert/v5@v5.10.2/README-CLI-CLOUD.md (about) 1  2 [](https://opensource.org/licenses/Apache-2.0) 3  4  5 _**This open source project is community-supported.** To report a problem or share an idea, use 6 **[Issues](../../issues)**; and if you have a suggestion for fixing the issue, please include those details, too. 7 In addition, use **[Pull Requests](../../pulls)** to contribute actual bug fixes or proposed enhancements. 8 We welcome and appreciate all contributions. Got questions or want to discuss something with our team? 9 **[Join us on Slack](https://join.slack.com/t/venafi-integrations/shared_invite/zt-i8fwc379-kDJlmzU8OiIQOJFSwiA~dg)**!_ 10 11 # VCert CLI for Venafi Control Plane 12 13 Venafi VCert is a command line tool designed to generate keys and simplify certificate acquisition, eliminating the 14 need to write code that's required to interact with the Venafi REST API. VCert is available in 32- and 64-bit versions 15 for Linux, Windows, and macOS. 16 17 This article applies to the latest version of VCert CLI, which you can [download here](https://github.com/Venafi/vcert/releases/latest). 18 19 On macOS and Linux, if you have [Homebrew](https://brew.sh) you can install VCert with: 20 21 ```shell 22 brew install venafi/tap/vcert 23 ``` 24 25 ## Quick Links 26 27 Use these links to quickly jump to a relevant section lower on this page: 28 29 - [VCert CLI for Venafi as a Service](#vcert-cli-for-venafi-control-plane) 30 - [Quick Links](#quick-links) 31 - [Prerequisites](#prerequisites) 32 - [General Command Line Parameters](#general-command-line-parameters) 33 - [Environment Variables](#environment-variables) 34 - [Certificate Request Parameters](#certificate-request-parameters) 35 - [Certificate Retrieval Parameters](#certificate-retrieval-parameters) 36 - [Certificate Renewal Parameters](#certificate-renewal-parameters) 37 - [Certificate Retire Parameters](#certificate-retire-parameters) 38 - [Certificate Provisioning Parameters](#certificate-provisioning-parameters) 39 - [Parameters for Applying Certificate Policy](#parameters-for-applying-certificate-policy) 40 - [Parameters for Viewing Certificate Policy](#parameters-for-viewing-certificate-policy) 41 - [Examples](#examples) 42 - [Appendix](#appendix) 43 - [Registering and obtaining an API Key](#registering-and-obtaining-an-api-key) 44 - [Generating a new key pair and CSR](#generating-a-new-key-pair-and-csr) 45 46 ## Prerequisites 47 48 Review these prerequisites to get started. You'll need the following: 49 50 1. Verify that the Venafi Control Plane REST API is accessible from the system where 51 VCert will be run. Currently, we support the following regions: 52 - [https://api.venafi.cloud](https://api.venafi.cloud/vaas) [US] 53 - [https://api.venafi.eu](https://api.eu.venafi.cloud/vaas) [EU] 54 - [https://api.au.venafi.cloud](https://api.au.venafi.cloud/vaas) [AU] 55 - [https://api.uk.venafi.cloud](https://api.uk.venafi.cloud/vaas) [UK] 56 - [https://api.sg.venafi.cloud](https://api.sg.venafi.cloud/vaas) [SG] 57 - [https://api.ca.venafi.cloud](https://api.ca.venafi.cloud/vaas) [CA] 58 2. You have successfully registered for a Venafi Control Plane account, have been granted at least the "Resource Owner" 59 role, and know your API key. You can use the `getcred` action to 60 [register and obtain an API key](#registering-and-obtaining-an-api-key), but you will need an administrator to update 61 your role if there are already 3 or more users registered for your company in Venafi Control Plane. Alternatively, you 62 have configured a service account, the service account has been granted the "Resource Owner" role, you have the 63 `token URL` and have obtained a `JWT` from the Identity Provider associated to the service-account. 64 3. A CA Account and Issuing Template exist and have been configured with: 65 1. Recommended Settings values for: 66 1. Organizational Unit (OU) 67 2. Organization (O) 68 3. City/Locality (L) 69 4. State/Province (ST) 70 5. Country (C) 71 2. Issuing Rules that: 72 1. (Recommended) Limits Common Name and Subject Alternative Names that are allowed by your organization 73 2. (Recommended) Restricts the Key Length to 2048 or higher 74 3. (Recommended) Does not allow Private Key Reuse 75 4. An Application exists where you are among the owners, and you know the Application Name. 76 5. An Issuing Template is assigned to the Application, and you know its API Alias. 77 78 > 📌 **NOTE**: if you're just testing, you can skip the last 3 items. Simply specify "Default" for the issuing template 79 > alias portion of your zone (e.g. "My Application\Default") and an application with the name you specified will be 80 > automatically created for you. 81 82 ## General Command Line Parameters 83 84 The following options apply to the `enroll`, `pickup`, and `renew` actions: 85 86 | Flag | Description | 87 |----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 88 | `--config` | Use to specify INI configuration file containing connection details. Available parameters: `cloud_apikey`, `cloud_zone`, `trust_bundle`, `test_mode`. | 89 | `-k` or `--apiKey` | Use to specify your API key for Venafi Control Plane.<br/>Example: -k aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee | 90 | `--no-prompt` | Use to exclude password prompts. If you enable the prompt and you enter incorrect information, an error is displayed. This option is useful with scripting. | 91 | `-p` or `--platform` | Use to specify Venafi Control Plane as the platform of choice to connect. Accepted value is `vcp`, case-insensitive. | 92 | `-t` or `--token` | Use to specify an access token for Venafi Control Plane. You need to set `--platform vcp` or `-p vcp` in order to use access tokens for Venafi Control Plane. | 93 | `--test-mode` | Use to test operations without connecting to Venafi Control Plane. This option is useful for integration tests where the test environment does not have access to Venafi Control Plane. Default is false. | 94 | `--test-mode-delay` | Use to specify the maximum number of seconds for the random test-mode connection delay. Default is 15 (seconds). | 95 | `--timeout` | Use to specify the maximum amount of time to wait in seconds for a certificate to be processed by Venafi Control Plane. Default is 120 (seconds). | 96 | `--trust-bundle` | Use to specify a file with PEM formatted certificates to be used as trust anchors when communicating with Venafi Control Plane. Generally not needed because VCP is secured by a publicly trusted certificate, but it may be needed if your organization requires VCert to traverse a proxy server. VCert uses the trust store of your operating system for this purpose if not specified.<br/>Example: `--trust-bundle /path-to/bundle.pem` | 97 | `-u` or `--url` | Use to specify the URL of the Venafi Control Plane API server. Currently, we support the following regions:<br/>- `https://api.venafi.cloud` (US region).<br/>- `https://api.venafi.eu` (EU region).<br/>- `https://api.au.venafi.cloud` (AU region).<br/> - `https://api.uk.venafi.cloud` (UK region).<br/> - `https://api.sg.venafi.cloud` (SG region).<br/> - `https://api.ca.venafi.cloud` (CA region).<br/> If it's omitted, then VCert will default to US region. <br/>Example: `-u https://api.venafi.eu` | 98 | `--verbose` | Use to increase the level of logging detail, which is helpful when troubleshooting issues. | 99 100 ### Environment Variables 101 102 VCert supports supplying flag values using environment variables: 103 104 | Attribute | Flag | Environment Variable | 105 |--------------------------------|--------------------|----------------------| 106 | API key | `-k` or `--apiKey` | `VCERT_APIKEY` | 107 | JWT from Identity Provider | `--external-jwt` | `VCERT_EXTERNAL_JWT` | 108 | Venafi Control Plane token | `-t` or `--token` | `VCERT_TOKEN` | 109 | Venafi Control Plane token URL | `--token-url` | `VCERT_TOKEN_URL` | 110 | Venafi Control Plane URL | `-u` or `--url` | `VCERT_URL` | 111 | Venafi platform | `--platform` | `VCERT_PLATFORM` | 112 | Zone | `-z` or `--zone` | `VCERT_ZONE` | 113 114 115 ## Certificate Request Parameters 116 API key: 117 ``` 118 vcert enroll -k <api key> --cn <common name> -z <application name\issuing template alias> 119 ``` 120 Access token: 121 ``` 122 vcert enroll -p vcp -t <access token> --cn <common name> -z <application name\issuing template alias> 123 ``` 124 Options: 125 126 | Command | Description | 127 |--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 128 | `--app-info` | Use to identify the application requesting the certificate with details like vendor name and vendor product.<br/>Example: `--app-info "Venafi VCert CLI"` | 129 | `--cert-file` | Use to specify the name and location of an output file that will contain only the end-entity certificate.<br/>Example: `--cert-file /path-to/example.crt` | 130 | `--chain` | Use to include the certificate chain in the output, and to specify where to place it in the file.<br/>Options: `root-last` (default), `root-first`, `ignore` | 131 | `--chain-file` | Use to specify the name and location of an output file that will contain only the root and intermediate certificates applicable to the end-entity certificate. | 132 | `--cn` | Use to specify the common name (CN). This is required for Enrollment. | 133 | `--csr` | Use to specify the CSR and private key location. Options: `local` (default), `service`, `file`<br/>- local: private key and CSR will be generated locally<br/>- service: private key and CSR will be generated by a VSatellite in Venafi as a Service<br/>- file: CSR will be read from a file by name<br/>Example: `--csr file:/path-to/example.req` | 134 | `--file` | Use to specify a name and location of an output file that will contain the private key and certificates when they are not written to their own files using `--key-file`, `--cert-file`, and/or `--chain-file`.<br/>Example: `--file /path-to/keycert.pem` | 135 | `--format` | Use to specify the output format. The `--file` option must be used with the PKCS#12 and JKS formats to specify the keystore file. JKS format also requires `--jks-alias` and at least one password (see `--key-password` and `--jks-password`) <br/>Options: `pem` (default), `legacy-pem`, `json`, `pkcs12`, `legacy-pkcs12` (analogous to OpenSSL 3.x -legacy flag), `jks` | 136 | `--jks-alias` | Use to specify the alias of the entry in the JKS file when `--format jks` is used | 137 | `--jks-password` | Use to specify the keystore password of the JKS file when `--format jks` is used. If not specified, the `--key-password` value is used for both the key and store passwords | 138 | `--key-curve` | Use to specify the elliptic curve for key generation when `--key-type` is ECDSA.<br/>Options: `p256` (default), `p384`, `p521` | 139 | `--key-file` | Use to specify the name and location of an output file that will contain only the private key.<br/>Example: `--key-file /path-to/example.key` | 140 | `--key-password` | Use to specify a password for encrypting the private key. For a non-encrypted private key, specify `--no-prompt` without specifying this option. You can specify the password using one of three methods: at the command line, when prompted, or by using a password file.<br/>Example: `--key-password file:/path-to/passwd.txt` | 141 | `--key-size` | Use to specify a key size for RSA keys. Default is 2048. | 142 | `--key-type` | Use to specify the key algorithm.<br/>Options: `rsa` (default), `ecdsa` | 143 | `--no-pickup` | Use to disable the feature of VCert that repeatedly tries to retrieve the issued certificate. When this is used you must run VCert again in pickup mode to retrieve the certificate that was requested. | 144 | `--pickup-id-file` | Use to specify a file name where the unique identifier for the certificate will be stored for subsequent use by pickup, renew, and revoke actions. Default is to write the Pickup ID to STDOUT. | 145 | `--san-dns` | Use to specify a DNS Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.<br/>Example: `--san-dns one.example.com` `--san-dns two.example.com` | 146 | `--san-email` | Use to specify an Email Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.<br/>Example: `--san-email me@example.com` `--san-email you@example.com` | 147 | `--san-ip` | Use to specify an IP Address Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.<br/>Example: `--san-ip 10.20.30.40` `--san-ip 192.168.192.168` | 148 | `--san-uri` | Use to specify a Uniform Resource Indicator Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.<br/>Example: `--san-uri spiffe://workload1.example.com` `--san-uri spiffe://workload2.example.com` | 149 | `--valid-days` | Use to specify the number of days a certificate needs to be valid.<br/>Example: `--valid-days 30` | 150 | `-z` | Use to specify the name of the Application to which the certificate will be assigned and the API Alias of the Issuing Template that will handle the certificate request.<br/>Example: `-z "Business App\\Enterprise CIT"` | 151 152 ## Certificate Retrieval Parameters 153 API key: 154 ``` 155 vcert pickup -k <api key> [--pickup-id <request id> | --pickup-id-file <file name>] 156 ``` 157 Access token: 158 ``` 159 vcert pickup -p vcp -t <access token> [--pickup-id <request id> | --pickup-id-file <file name>] 160 ``` 161 Options: 162 163 | Command | Description | 164 |--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 165 | `--cert-file` | Use to specify the name and location of an output file that will contain only the end-entity certificate.<br/>Example: `--cert-file /path-to/example.crt` | 166 | `--chain` | Use to include the certificate chain in the output, and to specify where to place it in the file.<br/>Options: `root-last` (default), `root-first`, `ignore` | 167 | `--chain-file` | Use to specify the name and location of an output file that will contain only the root and intermediate certificates applicable to the end-entity certificate. | 168 | `--file` | Use to specify a name and location of an output file that will contain certificates when they are not written to their own files using `--cert-file` and/or `--chain-file`.<br/>Example: `--file /path-to/keycert.pem` | 169 | `--format` | Use to specify the output format.<br/>Options: `pem` (default), `json` | 170 | `--pickup-id` | Use to specify the unique identifier of the certificate returned by the enroll or renew actions if `--no-pickup` was used or a timeout occurred. Required when `--pickup-id-file` is not specified. | 171 | `--pickup-id-file` | Use to specify a file name that contains the unique identifier of the certificate returned by the enroll or renew actions if --no-pickup was used or a timeout occurred. Required when `--pickup-id` is not specified. | 172 173 ## Certificate Renewal Parameters 174 API key: 175 ``` 176 vcert renew -k <api key> [--id <request id> | --thumbprint <sha1 thumb>] 177 ``` 178 Access token: 179 ``` 180 vcert renew -p vcp -t <access token> [--id <request id> | --thumbprint <sha1 thumb>] 181 ``` 182 Options: 183 184 | Command | Description | 185 |--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 186 | `--cert-file` | Use to specify the name and location of an output file that will contain only the end-entity certificate.<br/>Example: `--cert-file /path-to/example.crt` | 187 | `--chain` | Use to include the certificate chain in the output, and to specify where to place it in the file.<br/>Options: `root-last` (default), `root-first`, `ignore` | 188 | `--chain-file` | Use to specify the name and location of an output file that will contain only the root and intermediate certificates applicable to the end-entity certificate. | 189 | `--cn` | Use to specify the common name (CN). This is required for Enrollment. | 190 | `--csr` | Use to specify the CSR and private key location. Options: `local` (default), `service`, `file`<br/>- local: private key and CSR will be generated locally<br/>- service: private key and CSR will be generated by a VSatellite in Venafi as a Service<br/>- file: CSR will be read from a file by name<br/>Example: `--csr file:/path-to/example.req` | 191 | `--file` | Use to specify a name and location of an output file that will contain the private key and certificates when they are not written to their own files using `--key-file`, `--cert-file`, and/or `--chain-file`.<br/>Example: `--file /path-to/keycert.pem` | 192 | `--format` | Use to specify the output format. The `--file` option must be used with the PKCS#12 and JKS formats to specify the keystore file. JKS format also requires `--jks-alias` and at least one password (see `--key-password` and `--jks-password`) <br/>Options: `pem` (default), `legacy-pem`, `json`, `pkcs12`, `legacy-pkcs12` (analogous to OpenSSL 3.x -legacy flag), `jks` | 193 | `--id` | Use to specify the unique identifier of the certificate returned by the enroll or renew actions. Value may be specified as a string or read from a file by using the file: prefix.<br/>Example: `--id file:cert_id.txt` | 194 | `--jks-alias` | Use to specify the alias of the entry in the JKS file when `--format jks` is used | 195 | `--jks-password` | Use to specify the keystore password of the JKS file when `--format jks` is used. If not specified, the `--key-password` value is used for both the key and store passwords | 196 | `--key-curve` | Use to specify the elliptic curve for key generation when `--key-type` is ECDSA.<br/>Options: `p256` (default), `p384`, `p521` | 197 | `--key-file` | Use to specify the name and location of an output file that will contain only the private key.<br/>Example: `--key-file /path-to/example.key` | 198 | `--key-password` | Use to specify a password for encrypting the private key. For a non-encrypted private key, specify `--no-prompt` without specifying this option. You can specify the password using one of three methods: at the command line, when prompted, or by using a password file. | 199 | `--key-size` | Use to specify a key size for RSA keys. Default is 2048. | 200 | `--key-type` | Use to specify the key algorithm.<br/>Options: `rsa` (default), `ecdsa` | 201 | `--no-pickup` | Use to disable the feature of VCert that repeatedly tries to retrieve the issued certificate. When this is used you must run VCert again in pickup mode to retrieve the certificate that was requested. | 202 | `--omit-sans` | Ignore SANs in the previous certificate when preparing the renewal request. Workaround for CAs that forbid any SANs even when the SANs match those the CA automatically adds to the issued certificate. | 203 | `--pickup-id-file` | Use to specify a file name where the unique identifier for the certificate will be stored for subsequent use by `pickup`, `renew`, and `revoke` actions. By default it is written to STDOUT. | 204 | `--san-dns` | Use to specify a DNS Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.<br/>Example: `--san-dns one.example.com` `--san-dns two.example.com` | 205 | `--san-email` | Use to specify an Email Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.<br/>Example: `--san-email me@example.com` `--san-email you@example.com` | 206 | `--san-ip` | Use to specify an IP Address Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.<br/>Example: `--san-ip 10.20.30.40` `--san-ip 192.168.192.168` | 207 | `--san-uri` | Use to specify a Uniform Resource Indicator Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.<br/>Example: `--san-uri spiffe://workload1.example.com` `--san-uri spiffe://workload2.example.com` | 208 | `--thumbprint` | Use to specify the SHA1 thumbprint of the certificate to renew. Value may be specified as a string or read from the certificate file using the `file:` prefix. | 209 210 ## Certificate Retire Parameters 211 API key: 212 ``` 213 vcert retire -k <api key> [--id <request id> | --thumbprint <sha1 thumb>] 214 ``` 215 Access Token: 216 ``` 217 vcert retire -p vcp -t <access token> [--id <request id> | --thumbprint <sha1 thumb>] 218 ``` 219 Options: 220 221 | Command | Description | 222 |----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| 223 | `--id` | Use to specify the unique identifier of the certificate to retire. Value may be specified as a string or read from a file using the `file:` prefix. | 224 | `--thumbprint` | Use to specify the SHA1 thumbprint of the certificate to retire. Value may be specified as a string or read from the certificate file using the `file:` prefix. | 225 226 ## Certificate Provisioning Parameters 227 API key: 228 ``` 229 vcert provisioning cloudkeystore -p vcp -k <api key> [--certificate-id <certificate id> | --pickup-id <request id> | --pickup-id-file <file name>] [ --keystore-id <keystore id> | --keystore-name <keystore name> --provider-name <provider name>] --certificate-name <certificate name> --gcm-cert-scope <gcm certificate scope> 230 ``` 231 Access token: 232 ``` 233 vcert provisioning cloudkeystore -p vcp -t <access token> [--certificate-id <certificate id> | --pickup-id <request id> | --pickup-id-file <file name>] [ --keystore-id <keystore id> | --keystore-name <keystore name> --provider-name <provider name>] --certificate-name <certificate name> --gcm-cert-scope <gcm certificate scope> 234 ``` 235 Options: 236 237 | Command | Description | 238 |-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 239 | `--arn` | Use to specify AWS Resource Name which provisioned certificate will replace (only for AWS Certificate Manager) | 240 | `--gcm-cert-scope` | Use to specify Certificate Scope of the certificate to be provisioned (only for Google Cloud Certificate Manager). Supported values from GCM API documentation: DEFAULT, EDGE_CACHE, ALL_REGIONS. | 241 | `--certificate-id` | The id of the certificate to be provisioned to a cloud keystore. | 242 | `--certificate-id-file` | Use to specify a file name that contains the unique identifier of the certificate. Required when `--certificate-id` is not specified. | 243 | `--certificate-name` | Use to specify Cloud Keystore Certificate Name to be set or replaced by provisioned certificate (only for Azure Key Vault and Google Certificate Manager) | 244 | `--file` | Use to specify a file name and a location where the output should be written. Example: --file /path-to/provision-output | 245 | `--format` | The format of the operation output: text or JSON. Defaults to text. | 246 | `--keystore-id` | The id of the cloud keystore where the certificate will be provisioned. | 247 | `--keystore-name` | The name of the cloud keystore where the certificate will be provisioned. Must be set along with provider-name flag. | 248 | `--pickup-id` | Use to specify the unique identifier of the certificate returned by the enroll or renew actions. Required when `--pickup-id-file` is not specified. | 249 | `--pickup-id-file` | Use to specify a file name that contains the unique identifier of the certificate returned by the enroll or renew actions if --no-pickup was used or a timeout occurred. Required when `--pickup-id` is not specified. | 250 | `--provider-name` | The name of the cloud provider which owns the cloud keystore where the certificate will be provisioned. Must be set along with keystore-name flag. | 251 252 ## Parameters for Applying Certificate Policy 253 API key: 254 ``` 255 vcert setpolicy -k <api key> -z <application name\issuing template alias> --file <policy specification file> 256 ``` 257 Access token: 258 ``` 259 vcert setpolicy -p vcp -t <access token> -z <application name\issuing template alias> --file <policy specification file> 260 ``` 261 Options: 262 263 | Command | Description | 264 |------------|-----------------------------------------------------------------------------------------------------------------| 265 | `--file` | Use to specify the location of the required file that contains a JSON or YAML certificate policy specification. | 266 | `--verify` | Use to verify that a policy specification is valid. `-k` and `-z` are ignored with this option. | 267 268 Notes: 269 - The Venafi certificate policy specification is documented in detail [here](README-POLICY-SPEC.md). 270 - The PKI Administrator role is required to apply certificate policy. 271 - Policy (Issuing Template rules) and defaults (Issuing Template recommended settings) revert to their default state if 272 they are not present in a policy specification applied by this action. 273 - If the application or issuing template specified by the `-z` zone parameter do not exist, this action will attempt to 274 create them with the calling user as the application owner. 275 - This action can be used to simply create a new application and/or default issuing template by indicating those names 276 with the `-z` zone parameter and applying a file that contains an empty policy (i.e. `{}`). 277 - If the issuing template specified by the `-z` zone parameter is not already assigned to the application, this action 278 will attempt to make that assignment. 279 - The syntax for the `certificateAuthority` policy value is _CA Account Type\\CA Account Name\\CA Product Name_ 280 (e.g. `DIGICERT\\DigiCert SSL Plus\\ssl_plus`). 281 When not present in the policy specification, `certificateAuthority` defaults to `BUILTIN\\Built-In CA\\Default Product`. 282 - The `autoInstalled` policy/defaults does not apply as automated installation of certificates by Venafi Control Plane 283 is not yet supported. 284 - The `ellipticCurves` and `serviceGenerated` policy/defaults (`keyPair`) do not apply as ECC and central key generation 285 are not yet supported by Venafi Control Plane. 286 - The `ipAllowed`, `emailAllowed`, `uriAllowed`, and `upnAllowed` policy (`subjectAltNames`) do not apply as those SAN 287 types are not yet supported by Venafi Control Plane. 288 - If undefined key/value pairs are included in the policy specification, they will be silently ignored by this action. 289 This would include keys that are misspelled. 290 291 ## Parameters for Viewing Certificate Policy 292 API key: 293 ``` 294 vcert getpolicy -k <api key> -z <application name\issuing template alias> [--file <policy specification file>] 295 ``` 296 Access token: 297 ``` 298 vcert getpolicy -p vcp -t <access token> -z <application name\issuing template alias> [--file <policy specification file>] 299 ``` 300 Options: 301 302 | Command | Description | 303 |-------------|----------------------------------------------------------------------------------------------------------------------------| 304 | `--file` | Use to write the retrieved certificate policy to a file in JSON format. If not specified, policy is written to STDOUT. | 305 | `--starter` | Use to generate a template policy specification to help with getting started. `-k` and `-z` are ignored with this option. | 306 307 ## Examples 308 309 For the purposes of the following examples, assume the following: 310 311 - The Venafi Control Plane REST API is accessible from the system where 312 VCert will be run. Currently, we support the following regions: 313 - [https://api.venafi.cloud](https://api.venafi.cloud/vaas) [US] 314 - [https://api.venafi.eu](https://api.eu.venafi.cloud/vaas) [EU] 315 - [https://api.au.venafi.cloud](https://api.au.venafi.cloud/vaas) [AU] 316 - [https://api.uk.venafi.cloud](https://api.uk.venafi.cloud/vaas) [UK] 317 - [https://api.sg.venafi.cloud](https://api.sg.venafi.cloud/vaas) [SG] 318 - [https://api.ca.venafi.cloud](https://api.ca.venafi.cloud/vaas) [CA] 319 - A user has been registered and granted at least the `OP Resource Owner` role and has an API key. 320 - A CA Account and Issuing Template have been created and configured appropriately (organization, city, state, country, 321 key length, allowed domains, etc.). 322 - An Application has been created with a name of `Storefront` to which the user has been given access, and the Issuing 323 Template has been assigned to the Application with an API Alias of `Public Trust`. 324 325 Use the help to view the command line syntax for enroll: 326 ``` 327 vcert enroll -h 328 ``` 329 330 Submit a request to Venafi Control Plane for enrolling a certificate with a common name of `first-time.venafi.example` 331 using an api key and have VCert prompt for the password to encrypt the private key: 332 ``` 333 vcert enroll -k 3dfcc6dc-7309-4dcf-aa7c-5d7a2ee368b4 -z "Storefront\\Public Trust" --cn first-time.venafi.example 334 ``` 335 336 Submit a request to Venafi Control Plane for enrolling a certificate where the password for encrypting the private key 337 to be generated is specified in a text file called passwd.txt: 338 ``` 339 vcert enroll -k 3dfcc6dc-7309-4dcf-aa7c-5d7a2ee368b4 -z "Storefront\\Public Trust" --key-password file:passwd.txt --cn passwd-from-file.venafi.example 340 ``` 341 342 Submit a request to Venafi Control Plane for enrolling a certificate where the private key to be generated is not 343 password encrypted: 344 ``` 345 vcert enroll -k 3dfcc6dc-7309-4dcf-aa7c-5d7a2ee368b4 -z "Storefront\\Public Trust" --cn non-encrypted-key.venafi.example --no-prompt 346 ``` 347 348 Submit a request to Venafi Control Plane for enrolling a certificate using an externally generated CSR: 349 ``` 350 vcert enroll -k 3dfcc6dc-7309-4dcf-aa7c-5d7a2ee368b4 -z "Storefront\\Public Trust" --csr file:/opt/pki/cert.req 351 ``` 352 353 Submit a request to Venafi Control Plane for enrolling a certificate where the certificate and private key are output 354 using JSON syntax to a file called json.txt: 355 ``` 356 vcert enroll -k 3dfcc6dc-7309-4dcf-aa7c-5d7a2ee368b4 -z "Storefront\\Public Trust" --key-password Passw0rd --cn json-to-file.venafi.example --format json --file keycert.json 357 ``` 358 359 Submit a request to Venafi Control Plane for enrolling a certificate where only the certificate and private key are 360 output, no chain certificates: 361 ``` 362 vcert enroll -k 3dfcc6dc-7309-4dcf-aa7c-5d7a2ee368b4 -z "Storefront\\Public Trust" --key-password Passw0rd --cn no-chain.venafi.example --chain ignore 363 ``` 364 365 Submit a request to Venafi Control Plane for enrolling a certificate with three DNS subject alternative names: 366 ``` 367 vcert enroll -k 3dfcc6dc-7309-4dcf-aa7c-5d7a2ee368b4 -z "Storefront\\Public Trust" --no-prompt --cn three-sans.venafi.example --san-dns first-san.venafi.example --san-dns second-san.venafi.example --san-dns third-san.venafi.example 368 ``` 369 370 Submit request to Venafi Control Plane for enrolling a certificate where the certificate is not issued after two 371 minutes and then subsequently retrieve that certificate after it has been issued: 372 ``` 373 vcert enroll -k 3dfcc6dc-7309-4dcf-aa7c-5d7a2ee368b4 -z "Storefront\\Public Trust" --no-prompt --cn demo-pickup.venafi.example 374 375 vcert pickup -k 3dfcc6dc-7309-4dcf-aa7c-5d7a2ee368b4 --pickup-id "{7428fac3-d0e8-4679-9f48-d9e867a326ca}" 376 ``` 377 378 Submit request to Venafi Control Plane for enrolling a certificate that will be retrieved later using a Pickup ID from 379 a text file: 380 ``` 381 vcert enroll -k 3dfcc6dc-7309-4dcf-aa7c-5d7a2ee368b4 -z "Storefront\\Public Trust" --no-prompt --cn demo-pickup.venafi.example --no-pickup -pickup-id-file pickup_id.txt 382 383 vcert pickup -k 3dfcc6dc-7309-4dcf-aa7c-5d7a2ee368b4 --pickup-id-file pickup_id.txt 384 ``` 385 386 Submit request to Venafi Control Plane for renewing a certificate using the enrollment (pickup) ID of the expiring 387 certificate: 388 ``` 389 vcert renew -k 3dfcc6dc-7309-4dcf-aa7c-5d7a2ee368b4 --id "{7428fac3-d0e8-4679-9f48-d9e867a326ca}" 390 ``` 391 392 Submit request to Venafi Control Plane for renewing a certificate using the expiring certificate file: 393 ``` 394 vcert renew -k 3dfcc6dc-7309-4dcf-aa7c-5d7a2ee368b4 --thumbprint file:/opt/pki/demo.crt 395 ``` 396 397 ## Appendix 398 399 ### Registering and obtaining an API Key 400 ``` 401 vcert getcred --email <business email address> 402 ``` 403 Options: 404 405 | Command | Description | 406 |--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 407 | `--email` | Use to specify a user's business email address. An email will be sent to this address with a link to activate the API key that is output by this action. This is required for (re)registering with Venafi Control Plane. | 408 | `--format` | Specify "json" to get more verbose JSON formatted output instead of the plain text default. | 409 | `--password` | Use to specify the user's password if it is expected the user will need to login to the [Venafi Control Plane web UI](https://ui.venafi.cloud/). | 410 411 ### Obtaining an access token from service account 412 ``` 413 vcert getcred -p vcp --token-url https://api.venafi.cloud/v1/oauth2/v2.0/aaa-bbb-ccc/token --external-jwt "file:jwt.txt" 414 ``` 415 Options: 416 417 | Flag | Description | 418 |----------------------|-----------------------------------------------------------------------------------------------------------------------| 419 | `-p` or `--platform` | Use to specify Venafi Control Plane as the platform of choice to connect. Accepted value is `vcp`, no case-sensitive. | 420 | `--token-url` | The URL used to obtain the access token, provided by Venafi Control Plane's service account page | 421 | `--external-jwt` | The JWT of the Identity Provider associated to the service account that is going to grant the access token | 422 423 ### Generating a new key pair and CSR 424 ``` 425 vcert gencsr --cn <common name> -o <organization> --ou <ou1> --ou <ou2> -l <locality> --st <state> -c <country> --key-file <private key file> --csr-file <csr file> 426 ``` 427 428 Options: 429 430 | Command | Description | 431 |---------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 432 | `-c` | Use to specify the country (C) for the Subject DN. | 433 | `--cn` | Use to specify the common name (CN). This is required for enrollment except when providing a CSR file. | 434 | `--csr-file` | Use to specify a file name and a location where the resulting CSR file should be written.<br/>Example: `--csr-file /path-to/example.req` | 435 | `--format` | Generates the Certificate Signing Request in the specified format. Options: `pem` (default), `json`<br />- pem: Generates the CSR in classic PEM format to be used as a file.<br />- json: Generates the CSR in JSON format, suitable for REST API operations. | 436 | `--key-curve` | Use to specify the ECDSA key curve. Options: `p256` (default), `p384`, `p521` | 437 | `--key-file` | Use to specify a file name and a location where the resulting private key file should be written. Do not use in combination with `--csr` file.<br/>Example: `--key-file /path-to/example.key` | 438 | `--key-password` | Use to specify a password for encrypting the private key. For a non-encrypted private key, omit this option and instead specify `--no-prompt`.<br/>Example: `--key-password file:/path-to/passwd.txt` | 439 | `--key-size` | Use to specify a key size. Default is 2048. | 440 | `--key-type` | Use to specify a key type. Options: `rsa` (default), `ecdsa` | 441 | `-l` | Use to specify the city or locality (L) for the Subject DN. | 442 | `--no-prompt` | Use to suppress the private key password prompt and not encrypt the private key. | 443 | `-o` | Use to specify the organization (O) for the Subject DN. | 444 | `--ou` | Use to specify an organizational unit (OU) for the Subject DN. To specify more than one, simply repeat this parameter for each value.<br/>Example: `--ou "Engineering"` `--ou "Quality Assurance"` ... | 445 | `--san-dns` | Use to specify a DNS Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.<br/>Example: `--san-dns one.example.com` `--san-dns two.example.com` | 446 | `--san-email` | Use to specify an Email Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.<br/>Example: `--san-email me@example.com` `--san-email you@example.com` | 447 | `--san-ip` | Use to specify an IP Address Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.<br/>Example: `--san-ip 10.20.30.40` `--san-ip 192.168.192.168` | 448 | `--san-uri` | Use to specify a Uniform Resource Indicator Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.<br/>Example: `--san-uri spiffe://workload1.example.com` `--san-uri spiffe://workload2.example.com` | 449 | `--st` | Use to specify the state or province (ST) for the Subject DN. |