Follow

Introducing VCert - API Abstraction for DevOps

Venafi VCert is a command line utility designed to generate keys and simplify certificate acquisition by eliminating the need to write code to interact with the Venafi REST API. VCert is available in 32 and 64 bit versions for Linux, Windows, and macOS.

Click here to download the latest version of VCert from https://github.com/Venafi/vcert/releases/latest

Prerequisites

  • A user account that has an authentication token with "certificate:manage,revoke" scope (i.e. access to the "Venafi VCert CLI" API Application as of 20.1) or has been granted WebSDK Access
  • A folder where the user has been granted the following permissions: View, Read, Write, Create, Revoke (for the revoke action), and Private Key Read (for the pickup action when CSR is service generated)
  • A policy applied to the folder which specifies:
  • Subject DN values for Organizational Unit (OU), Organization (O), City/Locality (L), State/Province (ST) and Country (C)
  • CA Template that Trust Protection Platform will use to enroll certificate requests submitted by VCert
  • Management Type not locked or locked to 'Enrollment'
  • Certificate Signing Request (CSR) Generation not locked or locked to Service Generated CSR
  • Generate Key/CSR on Application not locked or locked to 'No'
  • (Recommended) Disable Automatic Renewal set to 'Yes'
  • (Recommended) Key Bit Strength set to 2048 or higher
  • (Recommended) Domain Whitelisting policy appropriately assigned

Compatibility

VCert is compatible with Trust Protection Platform 17.3 and higher.  The Custom Fields and Instance Tracking features require 18.2 or higher.  Token Authentication requires 19.2 or higher; for earlier versions, username/password authentication (deprecated) applies.

General Command Line Options

The following options apply to the enroll, pickup, renew, and revoke actions:

--config

Use to specify INI configuration file containing connection details.

  • For TPP: tpp_url, tpp_user, tpp_password, tpp_zone
  • For Cloud: cloud_url, cloud_apikey, cloud_zone
  • For TPP & Cloud: trust_bundle, test_mode

--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.

-t

Use to specify the token required to authenticate with Venafi Platform 19.2 (and higher).  See the Appendix for help using VCert to obtain a new authorization token.

--test-mode

Use to test operations without connecting to Venafi Platform.  This option is useful for integration tests where the test environment does not have access to Venafi Platform.  Default is false.

Options: true | false

--test-mode-delay

Use to specify the maximum number of seconds for the random test-mode connection delay.  Default is 15 (seconds).

--timeout

Use to specify the maximum amount of time to wait in seconds for a certificate to be processed by Venafi Platform. Default is 120 (seconds).

--tpp-password

[DEPRECATED] Use to specify the password required to authenticate with Venafi Platform.  Use -t instead for Venafi Platform 19.2 (and higher).

--tpp-user

[DEPRECATED] Use to specify the username required to authenticate with Venafi Platform.  Use -t instead for Venafi Platform 19.2 (and higher).

--trust-bundle

Use to specify a file with PEM formatted certificates to be used as trust anchors when communicating with Venafi Platform. VCert uses the trust store of your operating system for this purpose if not specified.

Example: --trust-bundle /path-to/bundle.pem
-u

Use to specify the URL of the Venafi Platform API server.

Example: -u https://tpp.venafi.example

--verbose

Use to increase the level of logging detail, which is helpful when troubleshooting issues.

 

Certificate Request Usage

VCert enroll -u <tpp url> -t <auth token> --cn <common name> -z <zone>

VCert enroll -u <tpp url> --tpp-user <username> --tpp-password <password> --cn <common name> -z <zone>

Options:

--app-info

Use to identify the application requesting the certificate with details like vendor name and vendor product.

Example: --app-info "Venafi VCert CLI"

--cert-file

Use to specify the name and location of an output file that will contain only the end-entity certificate.

Example: --cert-file /path-to/example.crt

--chain

Use to include the certificate chain in the output, and to specify where to place it in the file. By default, it is placed last.

Options:  ignore | root-first | root-last

--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.

--cn

Use to specify the common name (CN). This is required for Enrollment.

--csr

Use to specify the CSR and private key location.  Default is local.

Options: local | service | file

  • local: private key and CSR will be generated locally
  • service: private key and CSR will be generated within Venafi Platform
  • file: CSR will be read from a file by name
 Example: --csr file:/path-to/csr.pem

--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 ...

--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.

Example: --file /path-to/keycert.pem

--format

Use to specify the output format.  PEM is the default format.  The --file option must be used with the PKCS#12 format to specify the keystore file.

Options: pem | json | pkcs12

--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.

Example: --instance node:workload

--key-curve

Use to specify the elliptic curve for key generation when --key-type is ECDSA.  Default is p256.

Options:  p256 | p384 | p521

--key-file

Use to specify the name and location of an output file that will contain only the private key.

Example: --key-file /path-to/example.key

--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.

Example: --key-password file:/path-to/passwd.txt

--key-size

Use to specify a key size for RSA keys.  Default is 2048.

--key-type

Use to specify the key algorithm.  Default is RSA.

Options: rsa | ecdsa

--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).

--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.

--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.

--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.

--san-dns

Use to specify a DNS Subject Alternative Name. To specify more than one, use spaces, like this: 

--san-dns san1.example.com --san-dns san2.example.com ...

--san-email

Use to specify an Email Subject Alternative Name.  To specify more than one, use spaces, like this: 

--san-email john@example.com --san-email jane@example.com ...

--san-ip

Use to specify an IP Address Subject Alternative Name.  To specify more than one, use spaces, like this:

--san-ip 10.20.30.1 --san-ip 10.20.30.2 ...

--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.

Example: --tls-address 10.20.30.40:443

-z

Use to specify the folder path where the certificate object will be placed. VCert prepends \VED\Policy\, so you only need to specify child folders under the root Policy folder.

Example:  -z DevOps\CorpApp

 

Certificate Retrieval Usage

VCert pickup -u <tpp url> -t <auth token> [--pickup-id <request id> | --pickup-id-file <file name>]

VCert pickup -u <tpp url> --tpp-user <username> --tpp-password <password> [--pickup-id <request id> | --pickup-id-file <file name>]

Options:

--cert-file

Use to specify the name and location of an output file that will contain only the end-entity certificate.

Example: --cert-file /path-to/example.crt

--chain

Use to include the certificate chain in the output, and to specify where to place it in the file. By default, it is placed last.

Options:  ignore | root-first | root-last

--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.

--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.

Example: --file /path-to/keycert.pem

--format

Use to specify the output format.  PEM is the default format.  The --file option must be used with the PKCS#12 format to specify the keystore file.

Options: pem | json | pkcs12

--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.

--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.

 

Certificate Renewal Usage

VCert renew -u <tpp url> -t <auth token> [--id <request id> | --thumbprint <certificate thumbprint>]

VCert renew -u <tpp url> --tpp-user <username> --tpp-password <password> [--id <request id> | --thumbprint <certificate thumbprint>]

Options:

--cert-file

Use to specify the name and location of an output file that will contain only the end-entity certificate.

Example: --cert-file /path-to/example.crt

--chain

Use to include the certificate chain in the output, and to specify where to place it in the file. By default, it is placed last.

Options:  ignore | root-first | root-last

--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.

--cn

Use to specify the common name (CN). This is required for Enrollment.

--csr

Use to specify the CSR and private key location.  Default is local.

Options: local | service | file

  • local: private key and CSR will be generated locally
  • service: private key and CSR will be generated within Venafi Platform.  Depending on policy, the private key may be reused
  • file: CSR will be read from a file by name
Example: --csr file:/path-to/csr.pem

--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.

Example: --file /path-to/keycert.pem

--format

The --file option must be used with the PKCS#12 format to specify the keystore file.

Options: pem | json | pkcs12

--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. 

Example: --id file:cert_id.txt

--key-curve

Use to specify the elliptic curve for key generation when --key-type is ECDSA.  Default is p256.

Options:  p256 | p384 | p521

--key-file

Use to specify the name and location of an output file that will contain only the private key.

Example: --key-file /path-to/example.key

--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.

Example: --key-password file:/path-to/passwd.txt

--key-size

Use to specify a key size for RSA keys.  Default is 2048.

--key-type

Use to specify the key algorithm.  Default is RSA.

Options: rsa | ecdsa

--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.

--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.

--san-dns

Use to specify a DNS Subject Alternative Name. To specify more than one, use spaces, like this: 

--san-dns san1.example.com --san-dns san2.example.com ...

--san-email

Use to specify an Email Subject Alternative Name.  To specify more than one, use spaces, like this: 

--san-email john@example.com --san-email jane@example.com ...

--san-ip

Use to specify an IP Address Subject Alternative Name.  To specify more than one, use spaces, like this:

--san-ip 10.20.30.1 --san-ip 10.20.30.2 ...
--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.

 

Certificate Revocation Usage

VCert revoke -u <tpp url> -t <auth token> [--id <request id> | --thumbprint <certificate thumbprint>]

VCert revoke -u <tpp url> --tpp-user <username> --tpp-password <password> [--id <request id> | --thumbprint <certificate thumbprint>]

Options:

--id

Use to specify the unique identifier of the certificate to revoke.  Value may be specified as a string or read from a file using the file: prefix.

--no-retire

Do not disable certificate. Use this option if you intend to enroll a new version of the certificate later.  Works only with --id <certificate DN>

--reason

Use to specify the revocation reason.  Default is none.

Options: none | key-compromise | ca-compromise | affiliation-changed | superseded | cessation-of-operation

--thumbprint

Use to specify the SHA1 thumbprint of the certificate to revoke. Value may be specified as a string or read from the certificate file using the file: prefix.

 

Examples

For the purposes of the following examples assume that the Trust Protection Platform REST API is available at https://tpp.venafi.example/vedsdk, and that a user account named “DevOps” has been created with an authentication token of "ql8AEpCtGSv61XGfAknXIA==" that has "certificate:manage,revoke" scope, a password of “Passw0rd”, and has been granted “WebSDK Access”. Also assume that a folder has been created at the root of the Policy Tree called “DevOps Certificates” and the DevOps user has been granted View, Read, Write, Create, Revoke, and Private Key Read permissions to it.  Lastly, assume that a CA Template has been created and assigned to the DevOps Certificates folder along with other typical policy settings (organization, city, state, country, key size, whitelisted domains, etc.).

Use the help to view the command line syntax for enroll:

VCert enroll -h

Submit a Trust Protection Platform 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:

VCert enroll -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" -z "DevOps Certificates" --cn first-time.venafi.example

Submit a Trust Protection Platform request for enrolling a certificate with a common name of “first-time.venafi.example” and have VCert prompt for the DevOps user’s password and the password to encrypt the private key:

VCert enroll -u https://tpp.venafi.example --tpp-user DevOps -z "DevOps Certificates" --cn first-time.venafi.example

Submit a Trust Protection Platform request for enrolling a certificate where the DevOps user password is specified on the command line and the password for encrypting the private key to be generated is specified in a text file called passwd.txt:

VCert enroll -u https://tpp.venafi.example --tpp-user DevOps --tpp-password Passw0rd -z "DevOps Certificates" --key-password file:passwd.txt --cn passwd-from-file.venafi.example

Submit a Trust Protection Platform request for enrolling a certificate where the private key to be generated is not password encrypted:

VCert enroll -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" -z "DevOps Certificates" --cn non-encrypted-key.venafi.example --no-prompt

Submit a Trust Protection Platform request for enrolling a certificate where the private key and CSR are to be generated by the Venafi Platform:

VCert enroll -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" -z "DevOps Certificates" --cn service-generated.venafi.example --csr service --key-password somePassw0rd!

Submit a Trust Protection Platform request for enrolling a certificate using an externally generated CSR:

VCert enroll -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" -z "DevOps Certificates" --nickname externally-generated-csr --csr file:/opt/pki/cert.req

Submit a Trust Protection Platform request for enrolling a certificate where the certificate and private key are output using JSON syntax to a file called json.txt:

VCert enroll -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" -z "DevOps Certificates" --key-password Passw0rd --cn json-to-file.venafi.example --format json --file json.txt

Submit a Trust Protection Platform request for enrolling a certificate where only the certificate and private key are output, no chain certificates:

VCert enroll -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" -z "DevOps Certificates" --key-password Passw0rd --cn no-chain.venafi.example --chain ignore

Submit a Trust Protection Platform 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:

VCert enroll -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" -z "DevOps Certificates" --key-password Passw0rd --cn same-cn.venafi.example --nickname same-cn-separate-object-1

VCert enroll -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" -z "DevOps Certificates" --key-password Passw0rd --cn same-cn.venafi.example --nickname same-cn-separate-object-2

Submit a Trust Protection Platform request for enrolling a certificate with three subject alternative names, one each of DNS name, IP address, and email address:

VCert enroll -u https://tpp.venafi.example -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

Submit a Trust Protection Platform request for enrolling a certificate and setting two Custom Fields, one string (Cost Center) and one multi-valued list (Environment):

VCert enroll -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" -z "DevOps Certificates" --no-prompt --cn custom-fields.venafi.example --field "Cost Center=ABC123" --field "Environment=Staging" --field "Environment=UAT"

Submit a Trust Protection Platform request for enrolling a certificate and identifying the location where it will be installed and can be validated:

VCert enroll -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" -z "DevOps Certificates" --no-prompt --cn custom-fields.venafi.example --instance beta-cluster.venafi.example:order_svc_23 --tls-address 10.20.30.40:44300

Submit a Trust Protection Platform request for enrolling a certificate where the certificate is not issued after two minutes and then subsequently retrieve that certificate after it has been issued:

VCert enroll -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" -z "DevOps Certificates" --no-prompt --cn demo-pickup.venafi.example

VCert pickup -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" --pickup-id "\VED\Policy\DevOps Certificates\demo-pickup.venafi.example"

Note:  Special command line characters vary by shell will generally require escaping.  For example, in Unix/Linux shells the backslash character \ must be escaped so in the value of --pickup-id above would need to be "\\VED\\Policy\\DevOps Certificates\\demo-pickup.venafi.example".

Submit a Trust Protection Platform request for enrolling a certificate that will be retrieved later using a Pickup ID from in a text file:

VCert enroll -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" -z "DevOps Certificates" --no-prompt --cn demo-pickup.venafi.example --no-pickup -pickup-id-file pickup_id.txt

VCert pickup -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" --pickup-id-file pickup_id.txt

Submit a Trust Protection Platform request for renewing a certificate using the enrollment (pickup) ID of the expiring certificate:

VCert renew -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" --id "\VED\Policy\DevOps Certificates\demo.venafi.example"

Submit a Trust Protection Platform request for enrolling a certificate using the expiring certificate file:

VCert renew -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" --thumbprint file:/opt/pki/demo.crt

Submit a Trust Protection Platform revocation request using the enrollment (pickup) ID of the certificate and keep the certificate enabled so that a replacement certificate can be enrolled later:

VCert revoke -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" --id "\VED\Policy\DevOps Certificates\demo.venafi.example" --reason superseded --no-retire

Submit a Trust Protection Platform revocation request using the actual certificate file:

VCert revoke -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" --thumbprint file:/opt/pki/demo.crt --reason cessation-of-operation

 

Appendix:  Obtaining an Authorization Token

VCert getcred -u <tpp url> --username <tpp username> --password <tpp password>

VCert getcred -u <tpp url> --p12-file <client cert file> --p12-password <client cert file password>

Options:

--client-id

Use to specify the application that will be using the token. "vcert-cli" is the default.

--format

Specify "json" to get JSON formatted output instead of the plain text default.

--password

Use to specify the Venafi Platform user's password.

--p12-file

Use to specify a PKCS#12 file containing a client certificate (and private key) of a Venafi Platform user to be used for mutual TLS. Required if --username or --t is not present and may not be combined with either. Must specify --trust-bundle if the chain for the client certificate is not in the PKCS#12 file.

--p12-password

Use to specify the password of the PKCS#12 file containing the client certificate.

--scope

Use to request specific scopes and restrictions. "certificate:manage,revoke;" is the default which is the minimum required to perform any actions supported by the VCert CLI.

-t

Use to specify a refresh token for a Venafi Platform user. Required if --username or --p12-file is not present and may not be combined with either.

--trust-bundle

Use to specify a PEM file name to be used as trust anchors when communicating with the Venafi Platform API server.

-u

Use to specify the URL of the Venafi Platform API server.

 Example: --u https://tpp.example.com

--username

Use to specify the username of a Venafi Platform user. Required if --p12-file or --t is not present and may not be combined with either.

--verbose

Use to increase the level of logging detail, which is helpful when
troubleshooting issues.

Was this article helpful?
5 out of 5 found this helpful
Have more questions? Submit a request

Comments