github.com/Venafi/vcert/v5@v5.10.2/README-CLI-FIREFLY.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 Firefly 12 13 _Venafi VCert_ is a command line tool designed to generate keys and simplify certificate acquisition, eliminating the need to write code that's required to interact with the Venafi REST API. _VCert_ is available in 32- and 64-bit versions for Linux, Windows, and macOS. 14 15 This article applies to the latest version of _VCert CLI_, which you can [download here](https://github.com/Venafi/vcert/releases/latest). 16 17 On macOS and Linux, if you have [Homebrew](https://brew.sh) you can install VCert with: 18 19 ```shell 20 brew install venafi/tap/vcert 21 ``` 22 23 ## Quick Links 24 25 Use these to quickly jump to a relevant section lower on this page: 26 27 - [VCert CLI for Venafi Firefly](#vcert-cli-for-venafi-firefly) 28 - [Quick Links](#quick-links) 29 - [Prerequisites](#prerequisites) 30 - [Compatibility](#compatibility) 31 - [Command Line Actions](#command-line-actions) 32 - [Environment Variables](#environment-variables) 33 - [Certificate Request Parameters](#certificate-request-parameters) 34 - [Examples](#examples) 35 - [Appendix](#appendix) 36 - [Obtaining an Authorization Token](#obtaining-an-authorization-token) 37 - [Client credentials flow grant parameters](#client-credentials-flow-grant-parameters) 38 - [Device code flow grant parameters](#device-code-flow-grant-parameters) 39 - [Resource owner password credentials flow grant parameters](#resource-owner-password-credentials-flow-grant-parameters) 40 - [Generating a new key pair and CSR](#generating-a-new-key-pair-and-csr) 41 42 ## Prerequisites 43 44 Review these prerequisites to get started. You'll need: 45 46 1. An **identity provider** with support for [OAuth 2.0](https://oauth.net/2/) configured to manage at least one of the following [OAuth 2.0 grant types](https://oauth.net/2/grant-types/): [client credentials](https://oauth.net/2/grant-types/client-credentials/), [device code](https://oauth.net/2/grant-types/device-code/) and [resource owner password credentials](https://oauth.net/2/grant-types/password/). 47 2. A [Venafi Firefly](https://venafi.com/firefly/) environment with the following requirements ([see here](https://developer.venafi.com/tlsprotectcloud/docs/firefly) for more details): 48 1. Configured the [TLS server interface for rest](https://developer.venafi.com/tlsprotectcloud/docs/firefly-config-yaml-reference#server-section). 49 2. Additionally, for _Firefly developer mode_ it's required to have configured the [authentication/authorization](https://developer.venafi.com/tlsprotectcloud/docs/firefly-config-yaml-reference#server-section) section to validate the [JSON Web Tokens](https://jwt.io/) provided by the _identity provider_. 50 51 ### Compatibility 52 53 **[VCert 5.1](https://github.com/Venafi/vcert/releases/tag/v5.1)** and later versions are compatible with **Venafi Firefly**. 54 55 ## Command Line actions 56 57 _VCert CLI_ for _Venafi Firefly_ provides support for `getcred`([see in appendix](#obtaining-an-authorization-token)) and `enroll` actions. 58 59 60 ### Environment Variables 61 62 As an alternative to specifying a `platform`, `token`, `trust bundle`, `url`, and/or `zone` via the command line or in a config file, _VCert_ supports supplying those values using environment variables `VCERT_PLATFORM`, `VCERT_TOKEN`, `VCERT_TRUST_BUNDLE`, `VCERT_URL`, and `VCERT_ZONE` respectively. 63 64 ## Certificate Request Parameters 65 66 To request a certificate to _Firefly_, _VCert CLI_ provides the `enroll` action. 67 68 Example 69 ``` 70 vcert enroll -u <firefly ip/url> -t <auth token> --cn <common name> -z <policy name> 71 ``` 72 Options: 73 74 | Command | Description | 75 |---------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 76 | `--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"` | 77 | `--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` | 78 | `--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` | 79 | `--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. | 80 | `--cn` | Use to specify the common name (CN). This is required for Enrollment. | 81 | `--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 within Venafi Platform<br/>- file: CSR will be read from a file by name<br/>Example: `--csr file:/path-to/example.req` | 82 | `--field` | Use to specify Custom Fields in 'key=value' format. If many values are required for the same Custom Field (key), use the following syntax: `--field key1=value1` `--field key1=value2` ... | 83 | `--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` | 84 | `--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` | 85 | `--instance` | Use to provide the name/address of the compute instance and an identifier for the workload using the certificate. This results in a device (node) and application (workload) being associated with the certificate in the Venafi Platform.<br/>Example: `--instance node:workload` | 86 | `--jks-alias` | Use to specify the alias of the entry in the JKS file when `--format jks` is used | 87 | `--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 | 88 | `--key-curve` | Use to specify the elliptic curve for key generation when `--key-type` is ECDSA.<br/>Options: `p256` (default), `p384`, `p521` | 89 | `--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` | 90 | `--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` | 91 | `--key-size` | Use to specify a key size for RSA keys. Default is 2048. | 92 | `--key-type` | Use to specify the key algorithm.<br/>Options: `rsa` (default), `ecdsa` | 93 | `--nickname` | Use to specify a name for the new certificate object that will be created and placed in a folder (which you specify using the `-z` option). | 94 | `--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. | 95 | `--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. | 96 | `--platform` | (REQUIRED) Use to specify the Venafi Firefly platform.<br/>Example: `--platform firefly` | 97 | `--replace-instance` | Force the specified instance to be recreated if it already exists and is associated with the requested certificate. Default is for the request to fail if the instance already exists. | 98 | `--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` | 99 | `--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` | 100 | `--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` | 101 | `--tls-address` | Use to specify the hostname, FQDN or IP address and TCP port where the certificate can be validated after issuance and installation. Only allowed when `--instance` is also specified.<br/>Example: `--tls-address 10.20.30.40:443` | 102 | `-u` | Use to specify the URL of the Venafi Firefly API server.<br/>Example: `-u https://firefly.venafi.example` | 103 | `--valid-days` | Use to specify the number of days a certificate needs to be valid if supported/allowed by the CA template. Indicate the target issuer by appending #D for DigiCert, #E for Entrust, or #M for Microsoft.<br/>Example: `--valid-days 90#M`<br/> Note: You can use the `valid-period` flag instead of this. | 104 | `--valid-period` | Use to specify the validity period certificate needs to be valid expressed as an ISO 8601 duration. This parameter has precedence over `valid-days` parameter. | 105 | `-z` | Use to specify the policy name configured in _Firefly_.<br/>Example: `-z "my policy"` | 106 107 108 ## Examples 109 110 For the purposes of the following examples, assume the following: 111 112 - The Firefly REST API is available at https://firefly.venafi.example:8003. 113 - An OAuth 2.0 access token with value "ql8AEpCtGSv61XGfAknXIA==..." and scope of "certificate:create" was gotten. 114 - Firefly was configured with a policy called _DevOps Certificates_. along with other typical policy settings (such as, organization, city, state, country, key size, whitelisted domains, etc.). 115 116 Use the Help to view the command line syntax for enroll: 117 ``` 118 vcert enroll -h 119 ``` 120 Submit a Firefly request for enrolling a certificate with a common name of “first-time.venafi.example” using an authentication token and have VCert prompt for the password to encrypt the private key: 121 ``` 122 vcert enroll --platform firefly -u https://firefly.venafi.example:8003 -t "ql8AEpCtGSv61XGfAknXIA==..." -z "DevOps Certificates" --cn first-time.venafi.example 123 ``` 124 Submit a Firefly request for enrolling a certificate where the private key to be generated is not password encrypted: 125 ``` 126 vcert enroll --platform firefly -u https://firefly.venafi.example:8003 -t "ql8AEpCtGSv61XGfAknXIA==..." -z "DevOps Certificates" --cn non-encrypted-key.venafi.example --no-prompt 127 ``` 128 Submit a Firefly request for enrolling a certificate where the private key and CSR are to be generated by the Venafi Platform: 129 ``` 130 vcert enroll --platform firefly -u https://firefly.venafi.example:8003 -t "ql8AEpCtGSv61XGfAknXIA==..." -z "DevOps Certificates" --cn service-generated.venafi.example --csr service --key-password somePassw0rd! 131 ``` 132 Submit a Firefly request for enrolling a certificate using an externally generated CSR: 133 ``` 134 vcert enroll --platform firefly -u https://firefly.venafi.example:8003 -t "ql8AEpCtGSv61XGfAknXIA==..." -z "DevOps Certificates" --nickname externally-generated-csr --csr file:/opt/pki/cert.req 135 ``` 136 Submit a Firefly request for enrolling a certificate where the certificate and private key are output using JSON syntax to a file called json.txt: 137 ``` 138 vcert enroll --platform firefly -u https://firefly.venafi.example:8003 -t "ql8AEpCtGSv61XGfAknXIA==..." -z "DevOps Certificates" --key-password Passw0rd --cn json-to-file.venafi.example --format json --file keycert.json 139 ``` 140 Submit a Firefly request for enrolling a certificate where only the certificate and private key are output, no chain certificates: 141 ``` 142 vcert enroll --platform firefly -u https://firefly.venafi.example:8003 -t "ql8AEpCtGSv61XGfAknXIA==..." -z "DevOps Certificates" --key-password Passw0rd --cn no-chain.venafi.example --chain ignore 143 ``` 144 Submit a Firefly request for enrolling two certificate that have the same common name but are to be represented by distinct objects in TPP rather than having the first certificate be considered an older generation of the second: 145 ``` 146 vcert enroll --platform firefly -u https://firefly.venafi.example:8003 -t "ql8AEpCtGSv61XGfAknXIA==..." -z "DevOps Certificates" --key-password Passw0rd --cn same-cn.venafi.example --nickname same-cn-separate-object-1 147 148 vcert enroll --platform firefly -u https://firefly.venafi.example:8003 -t "ql8AEpCtGSv61XGfAknXIA==..." -z "DevOps Certificates" --key-password Passw0rd --cn same-cn.venafi.example --nickname same-cn-separate-object-2 149 ``` 150 Submit a Firefly request for enrolling a certificate with three subject alternative names, one each of DNS name, IP address, and email address: 151 ``` 152 vcert enroll --platform firefly -u https://firefly.venafi.example:8003 -t "ql8AEpCtGSv61XGfAknXIA==..." -z "DevOps Certificates" --no-prompt --cn three-san-types.venafi.example --san-dns demo.venafi.example --san-ip 10.20.30.40 --san-email zach.jackson@venafi.example 153 ``` 154 155 156 ## Appendix 157 158 ### Obtaining an Authorization Token 159 160 To get an authorization token, _VCert CLI_ provides the `getcred` action. This action allows to get an [OAuth 2.0 access token](https://oauth.net/2/access-tokens/) from an _identity provider_. 161 162 _VCert CLI_ for _Venafi Firefly_ supports three [OAuth 2.0 grant types](https://oauth.net/2/grant-types/): [client credentials](https://oauth.net/2/grant-types/client-credentials/), [device code](https://oauth.net/2/grant-types/device-code/) and [resource owner password credentials](https://oauth.net/2/grant-types/password/), so it's required to set one of these in order to use the _**get credentials action**_ successfully. 163 164 The following are common options independently of the _OAuth 2.0 grant type configured_: 165 166 | Command | Description | 167 |---------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 168 | `--audience` | Use to specify the _audience_. It's not part of OAuth 2.0 specification, but it's implemented by some _identity providers_.<br/>Example: `--audience http://my.audience` | 169 | `--client-id` | (REQUIRED) Use to specify the _[client id](https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/)_ registered in the OAuth provider.<br/>Example: `--client-id fkUdhCrIKIgTsJtCJZTNK5JPpXZ6UOuM` | 170 | `--config` | Use to specify INI configuration file containing connection details. Available parameters: `oauth_token_url`, `oauth_client_id`, `oauth_client_secret`, `oauth_user`, `oauth_password`, `oauth_device_url`, `oauth_audience`, `oauth_scope`, `trust_bundle`, `test_mode` | 171 | `--format` | Specify "json" to get JSON formatted output instead of the plain text default. | 172 | `--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. | 173 | `--platform` | (REQUIRED) Use to specify the Venafi platform. The value to set is 'oidc'.<br/>Example: `--platform oidc` | 174 | `--scope` | Use to specify the _[OAuth scope](https://oauth.net/2/scope/)_. Multiples scopes must be separated by `;`.<br/>Example: `--scope read:client_grants;offline_access` | 175 | `--test-mode` | Use to test operations without connecting to Venafi Firefly. This option is useful for integration tests where the test environment does not have access to Venafi Firefly. Default is false. | 176 | `--test-mode-delay` | Use to specify the maximum number of seconds for the random test-mode connection delay. Default is 15 (seconds). | 177 | `--trust-bundle` | Use to specify a file with PEM formatted certificates to be used as trust anchors when communicating with Venafi Firefly. VCert uses the trust store of your operating system for this purpose if not specified.<br/>Example: `--trust-bundle /path-to/bundle.pem` | 178 | `-u` | (REQUIRED) Use to specify the _OAuth token URL_ to request an access token.<br/>Example: `-u https://myauth0domain/oauth/token` | 179 | `--verbose` | Use to increase the level of logging detail, which is helpful when troubleshooting issues. | 180 181 ### Client credentials flow grant parameters 182 183 The following is the required parameter needed to get credentials using the _OAuth 2.0 client credentials flow grant_: 184 185 | Command | Description | 186 |---------------------------------------------------------------------------------------------------------|---------------------------------------------------------| 187 | `--client-secret` | (REQUIRED) Use to specify the _OAuth 2.0 client secret_ | 188 Example 189 ``` 190 vcert getcred ---platform oidc -u <idp token url> --client-id <idp client id> --client-secret <idp client secret> --audience <idp audience> --scope <idp scopes> --format text 191 ``` 192 193 ### Device code flow grant parameters 194 195 The following is the required parameter needed to get credentials using the non standard _OAuth 2.0 device code flow grant_: 196 197 | Command | Description | 198 |---------------------------------------------------------------------------------------------------------|----------------------------------------------------------| 199 | `--device-url` | (REQUIRED) Use to specify the non _OAuth 2.0 device url_ | 200 Example 201 ``` 202 vcert getcred ---platform oidc -u <idp token url> --client-id <idp client id> --device-url <idp device url> --audience <idp audience> --scope <idp scopes> --format text 203 ``` 204 205 ### Resource owner password credentials flow grant parameters 206 207 The following are the required parameters needed to get credentials using the _OAuth 2.0 resource owner password credentials flow grant_: 208 209 | Command | Description | 210 |---------------------------------------------------------------------------------------------------------|-----------------------------------------------------------| 211 | `--username` | (REQUIRED) Use to specify the _OAuth 2.0 user's name_ | 212 | `--password` | (REQUIRED) Use to specify the _OAuth 2.0 user's password_ | 213 Example 214 ``` 215 vcert getcred ---platform oidc -u <idp token url> --client-id <idp client id> --username <idp username> --username <idp user's password> --audience <idp audience> --scope <idp scopes> --format text 216 ``` 217 218 ### Generating a new key pair and CSR 219 ``` 220 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> 221 ``` 222 223 Options: 224 225 | Command | Description | 226 |---------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 227 | `-c` | Use to specify the country (C) for the Subject DN. | 228 | `--cn` | Use to specify the common name (CN). This is required for enrollment except when providing a CSR file. | 229 | `--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` | 230 | `--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. | 231 | `--key-curve` | Use to specify the ECDSA key curve. Options: `p256` (default), `p384`, `p521` | 232 | `--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` | 233 | `--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` | 234 | `--key-size` | Use to specify a key size. Default is 2048. | 235 | `--key-type` | Use to specify a key type. Options: `rsa` (default), `ecdsa` | 236 | `-l` | Use to specify the city or locality (L) for the Subject DN. | 237 | `--no-prompt` | Use to suppress the private key password prompt and not encrypt the private key. | 238 | `-o` | Use to specify the organization (O) for the Subject DN. | 239 | `--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"` ... | 240 | `--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` | 241 | `--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` | 242 | `--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` | 243 | `--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` | 244 | `--st` | Use to specify the state or province (ST) for the Subject DN. |