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:

-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

-cn

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

-file

Use to specify a file name and a location where the resulting file should be written.

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-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.  The default is 2048.

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

-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

-file

Use to specify a file name and a location where the resulting file should be written.

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