Digicert CLI

Build Status Code Climate Gem Version

The Digicert CLI is a tool that allows us to manage Digicert orders, certificates and etc using Digicert Ruby Client.

Configure

We need to setup our API key before we want to use the CLI. For simplicity we have add an easier interface to setup the Digicert API KEY. To setup your key please use the following interface.

digicert config DIGICERT_API_KEY

Usages

Getting Help

We have been trying to simplify the CLI with proper help documentation. Each of the command and subcommand should provide you the basic usages guide with the list of supported options.

Normally the parent command should fire up the help documentation, but if it does not then you can explicitly call the help command or pass -h flags with any of the action and that should fire up the documentation. For example

$ digicert help

Commands:
  digicert certificate     # Manage Digicert Certificates
  digicert config API_KEY  # Configure The CLI Client
  digicert csr             # Fetch/generate Certificate CSR
  digicert help [COMMAND]  # Describe available / One specific command
  digicert order           # Manage Digicert Orders

The above command lists the available commands with a basic description and as you might have notice, it also ships with a help command which can be used to up the usages documentation for it's nested command.

# digicert order -h
$ digicert help order

Commands:
  digicert order find              # Find a digicert order
  digicert order help [COMMAND]    # Describe subcommands or one specific
  digicert order list              # List digicert orders
  digicert order reissue ORDER_ID  # Reissue digicert order

Hopefully you get the idea, we will try our best to keep this guide up to date but whenever you need some more information please add the -h flags with any commands or subcommands and you should see what you need.

Orders

Listing Orders

Listing orders is pretty simple with the CLI, once we have our API key configured then we can list all of our orders using the list interface

$ digicert order list

+---------------+---------------+------------------+-------------+-------------+
| Id            | Product Type  | Common Name      | Status      | Expiry      |
+---------------+---------------+------------------+-------------+-------------+
| xxxxx65       | ssl_wildcard  | *.ribosetest.com | expired     | 2018-06-25  |
| xxxxx20       | ssl_wildcard  | *.ribosetest.com | issued      | 2018-06-15  |
| xxxxx06       | ssl_wildcard  | *.ribosetest.com | revoked     | 2018-05-09  |
+---------------+---------------+------------------+-------------+-------------+

The above interface without any option will list out all of the orders we have with Digicert, but sometime we might need to filter those listings, and that's where can can use the filter options. This interface supports filter options through the --filter option and expect the value to be in key:value format.

For example, if we want to retrieve all of the orders that has product type of ssl_wildcard then we can use

$ digicert order list --filter 'product_name_id:ssl_wildcard'

It will only list the orders with the ssl_wildcard product type, Currently the supported filters options are date_created, valid_till, status, search, common_name and product_name_id. Please check the wiki for more up to date supported filtering options.

Find an order

We can use the find interface to retrieve a single order, by default it will print the details in the console. This interface also supports filter options.

One important thing to remember, it will only retrieve one single entry, so if you have multiple orders in your specified terms then it will only retrieve the most recent one form that list.

$ digicert order find --filter 'common_name:ribosetest.com' 'product_name_id:ssl_plus'

#<Digicert::ResponseObject id=xxx04, certificate=#<Digicert::ResponseObject
..........................id=xxxx08 price=xxxx, product_name_id="ssl_plus">

But if you don't care about that much of data and only need the ID then you can pass the --quiet flags to reduce the noises and retrieve only the id.

Reissue an order

To reissue a non-expired order we can use the reissue interface and pass the order id to it. By default it will reissue the order using the existing details but if we want to update the CSR then we can pass the certificate file as --crt.

$ digicert order reissue 12345 --crt path_to_the_new_csr.csr

Reissue request xxxxx8 created for order - 123456

Pretty cool right? The above interface also support some other option that we can use to download the recently reissued order. To download, all we need to do is just provide a valid path and it will automatically download the certificates

$ digicert order reissue 123456 --output /path/to/downloads

Reissue request 1xxxxx created for order - 123456

Fetch attempt 1..
Downloaded certificate to:

/path/to/downloads/123456.root.crt
/path/to/downloads/123456.certificate.crt
/path/to/downloads/123456.intermediate.crt

Certificate

Fetch a certificate

The fetch interface will retrieve the certificate for any specific orders, by default it will print out the detail in the console but if we only want the ID then we can pass the --quiet flags with it.

$ digicert certificate fetch 123456789 --quiet

Download a certificate

To download a certificate we can use the same fetch interface but with the --output option. Based on the --output option fetch interface will fetch the certificates and download the root, intermediate and certificate to the output path, to download a certificate we can do

$ digicert certificate fetch 123456 --output /path/to/downloads

The above interface supports downloading a certificate and it expects us to provide the order-id, but if we only care about download then we can also use the download interface. It acts pretty much similar but it let's us specify the order-id or certificate-id.

$ digicert certificate download --order-id 654321 --output /downloads
$ digicert certificate download --certificate-id 123456 --output /downloads

List duplicate certificates

Digicert allows us to duplicate a certificate and if we want to list all of the duplicates then we can use the duplicates interface. This interface expects us to provide the order-id to list the duplicates

$ digicert certificate duplicates 123456

+----------+-------------------+------------------+----------+--------------+
| Id       | Common Name       | SAN Names        | Status   | Validity     |
+----------+-------------------+------------------+----------+--------------+
| xxxxx19  | *.ribosetest.com  | *.ribosetest.com | approved | xxxxx-xxxxxx |
|          |                   | ribosetest.com   |          |              |
+----------+-------------------+------------------+----------+--------------+

CSR

Fetch an order's CSR

Retrieving a CSR is pretty easy, if we have an order id and we want retrieve it's CSR then we can use the fetch interface from csr command. And once we passed it to the interface then it will retrieve and print it to the console.

$ digicert csr fetch 123456

Generate a new CSR

Digicert gem usages a third party library to generate a CSR, and we have also included that in the CLI to make the CSR generation process simpler, so if we need to generate a new CSR then we can use the generate interface and pass the order id with the key file to generate the CSR

$ digicert csr generate --oreder-id 12345 --key /path/to/the/key-file.key

This interface also support custom details like common-name and san. We can pass those as --common-name and --san and it will automatically use it to generate the new CSR

$ digicert csr generate --common-name ribosetest.com --order-id 1234 \
  --san test1.ribosetest.com test2.ribosetest.com --key path_to_key_file

Development

We are following Sandi Metz's Rules for this gem, you can read the description of the rules here All new code should follow these rules. If you make changes in a pre-existing file that violates these rules you should fix the violations as part of your contribution.

Setup

Clone the repository.

git clone https://github.com/riboseinc/digicert-cli

Setup your environment.

bin/setup

Run the test suite

bin/rspec

Contributing

First, thank you for contributing! We love pull requests from everyone. By participating in this project, you hereby grant Ribose Inc. the right to grant or transfer an unlimited number of non exclusive licenses or sub-licenses to third parties, under the copyright covering the contribution to use the contribution by all means.

Here are a few technical guidelines to follow:

  1. Open an issue to discuss a new feature.
  2. Write tests to support your new feature.
  3. Make sure the entire test suite passes locally and on CI.
  4. Open a Pull Request.
  5. Squash your commits after receiving feedback.
  6. Party!

Credits

This gem is developed, maintained and funded by Ribose Inc.