Follow

Introducing VCert - API Abstraction for DevOpsSec

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 (3.18.3.1) from https://github.com/Venafi/vcert/releases/latest

Prerequisites

  • A user account that 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

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.

-test-mode

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

Options include: true | false

-test-mode-delay

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

-tpp-password

Use to specify the password required to authenticate with the Venafi Platform.

-tpp-url

Use to specify the URL of the Venafi Platform server.

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

-tpp-user

Use to specify the username required to authenticate with the Venafi Platform.

-trust-bundle

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

-verbose

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

 

Certificate Request Usage

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

Options:

-cert-file

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

Example: /tmp/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 include:  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 include: local | service | file

  • local: private key and CSR will be generated locally
  • service: private key and CSR will be generated within the Venafi Platform
  • file: CSR will be read from a file by name, example: file:/tmp/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: /tmp/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 include: pem | json | pkcs12

-key-curve

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

Options include:  p256 | p384 | p521

-key-file

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

Example: /tmp/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:/tmp/passwd.txt

-key-size

Use to specify a key size.  Default is 2048.

-key-type

Use to specify the key algorithm.  Default is RSA.

Options include: 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.

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

-timeout

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

-z

Use to specify the folder path where the certificate object will be located. vCert automatically prepends \VED\Policy\, so you only need to specify folders below the root Policy folder.

Example:  -z DevOps\CorpApp

 

Certificate Retrieval Usage

VCert pickup -tpp-url <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: /tmp/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 include:  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: /tmp/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 include: 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.

-timeout

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

 

Certificate Renewal Usage

VCert renew -tpp-url <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: /tmp/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 include:  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 include: local | service | file

  • local: private key and CSR will be generated locally
  • service: private key and CSR will be generated within the Venafi Platform.  Depending on policy, the private key may be reused
  • file: CSR will be read from a file by name, example: file:/tmp/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: /tmp/keycert.pem

-format

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

Options include: 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: file:cert_id.txt

-key-curve

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

Options include:  p256 | p384 | p521

-key-file

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

Example: /tmp/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:/tmp/passwd.txt

-key-size

Use to specify a key size.  Default is 2048.

-key-type

Use to specify the key algorithm.  Default is RSA.

Options include: 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.  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.

-timeout

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

 

Certificate Revocation Usage

VCert revoke -tpp-url <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 include: 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 a password of “Passw0rd” and 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” and have VCert prompt for the DevOps user’s password and the password to encrypt the private key:

VCert enroll -tpp-url 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 -tpp-url 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 -tpp-url https://tpp.venafi.example -tpp-user DevOps -tpp-password Passw0rd -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 -tpp-url https://tpp.venafi.example -tpp-user DevOps -tpp-password Passw0rd -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 -tpp-url https://tpp.venafi.example -tpp-user DevOps -tpp-password Passw0rd -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 -tpp-url https://tpp.venafi.example -tpp-user DevOps -tpp-password Passw0rd -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 -tpp-url https://tpp.venafi.example -tpp-user DevOps -tpp-password Passw0rd -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 -tpp-url https://tpp.venafi.example -tpp-user DevOps -tpp-password Passw0rd -z "DevOps Certificates" -key-password Passw0rd -cn same-cn.venafi.example -nickname same-cn-separate-object-1

VCert enroll -tpp-url https://tpp.venafi.example -tpp-user DevOps -tpp-password Passw0rd -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 -tpp-url https://tpp.venafi.example -tpp-user DevOps -tpp-password Passw0rd -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 where the certificate is not issued after two minutes and then subsequently retrieve that certificate after it has been issued:

VCert enroll -tpp-url https://tpp.venafi.example -tpp-user DevOps -tpp-password Passw0rd -z "DevOps Certificates" -no-prompt -cn demo-pickup.venafi.example

VCert pickup -tpp-url https://tpp.venafi.example -tpp-user DevOps -tpp-password Passw0rd -pickup-id "\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 -tpp-url https://tpp.venafi.example -tpp-user DevOps -tpp-password Passw0rd -z "DevOps Certificates" -no-prompt -cn demo-pickup.venafi.example -no-pickup -pickup-id-file pickup_id.txt

VCert pickup -tpp-url https://tpp.venafi.example -tpp-user DevOps -tpp-password Passw0rd -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 -tpp-url https://tpp.venafi.example -tpp-user DevOps -tpp-password Passw0rd -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 -tpp-url https://tpp.venafi.example -tpp-user DevOps -tpp-password Passw0rd -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 -tpp-url https://tpp.venafi.example -tpp-user DevOps -tpp-password Passw0rd -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 -tpp-url https://tpp.venafi.example -tpp-user DevOps -tpp-password Passw0rd -thumbprint file:/opt/pki/demo.crt -reason cessation-of-operation

 

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

Comments