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 from https://ftp.venafi.com/ (credentials required).

Prerequisites

  • A user account that has been granted WebSDK Access
  • A folder where the user has been granted View, Read, Write, and Create permissions
  • 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

The first time you execute vCert you will be required to accept its End User License Agreement (EULA).  If you have already reviewed the EULA and wish to accept it without an interactive prompt simply include the -accept-eula option when you execute the utility.
 

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.

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

Options include: pem | json

-h

Use to get additional help about required and optional parameters.

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

-no-prompt

Use to exclude the authentication prompt.  If you enable the prompt and you enter incorrect information, an error is displayed.  This is useful with scripting.

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

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

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

-tpp-password

Use to specify the password required to authenticate with Trust Protection Platform.

-tpp-url

Use to specify the URL of the Trust Protection Platform Server.

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

-tpp-user

Use to specify the username required to authenticate with Trust Protection Platform.

-trust-bundle

Use to specify a file with PEM formatted certificates to be used as trust anchors when communicating with Trust Protection 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.

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

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.

Options include: pem | json

-h

Use to get additional help about required and optional parameters.

-no-prompt

Use to exclude the authentication prompt.  If you enable the prompt and you enter incorrect information, an error is displayed.  This is useful with scripting.

-pickup-id

Use to specify the unique identifier of the certificate returned by enroll if a timeout occurs.

-tpp-password

Use to specify the password required to authenticate with Trust Protection Platform.

-tpp-url

Use to specify the URL of the Trust Protection Platform Server.

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

-tpp-user

Use to specify the username required to authenticate with Trust Protection Platform.

-trust-bundle

Use to specify a file with PEM formatted certificates to be used as trust anchors when communicating with Trust Protection 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.

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, and Create 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 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 issued within one minute 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"

 

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

Comments

Powered by Zendesk