USER GUIDETBSCERTBOT

V0.1

CHANGELOG

VERSION DATE ACTION COMMENTS

V0.1 2016-12-01 Creation

RIGHTSThe content of this manual is the property of TBS INTERNET SAS, located at Caen, France (SIREN 440.443.810). © All rights reserved.All reproduction, copy or mirroring prohibited.

NOTESDocument created on LibreOffice 4.1 on Linux

2/15

TABLE OF CONTENTS1. OVERVIEW............................................................................................................................................................. 42. QUICKSTART......................................................................................................................................................... 53. OPTIONS AND PARAMETERS.............................................................................................................................. 6

3.1. Configuration file............................................................................................................................................. 63.2. Commands..................................................................................................................................................... 73.3. Cli parameters................................................................................................................................................. 8

4. ORDERING A CERTIFICATE.................................................................................................................................. 94.1. Requirements.................................................................................................................................................. 94.2. Example order................................................................................................................................................. 9

5. RENEWING A CERTIFICATE............................................................................................................................... 116. DOWNLOADING THE CERTIFICATE LIST..........................................................................................................127. MANAGING YOUR CERTIFICATES WITH THE “SHOW” COMMAND................................................................138. CERTIFICATE STATUS........................................................................................................................................ 149. CRON MODE........................................................................................................................................................ 15

3/15

1. OVERVIEW

TBSCertBot is an automated certificate management tool that allows you to seamlessly order,renew, download your certificate from the TBS Internet API. With minimal requirements (PHP,cURL and openssl), TBSCertBot allows you to:

• Order DV (including free 90 days certificates), OV, and EV Certificates

• Automatically generate private keys and CSR and transmit the CSR to your Certificate Authority

• Automatically renew your certificates, via an easy to integrate with sysadmin tools (cron,systemd, sysv) mode.

• Generate DCV challenge HTTP files or CNAME records

• Simple configuration

4/15

2. QUICKSTART

TBSCertBot is a command line tool based on PHP, Openssl, cURL, and the standard PHPlibraries. For optional features, an openssl executable present in the Path and the PHP mbcryptmodule are necessary.

It uses a simple, ini configuration file that can be overwritten by an abitrary configuration file orcommand line parameters. This file is:

data/conf.ini

Edit your defaults settings and then, you'll be ready to order your certificates.

$ php tbscertbot.php order

TBSCertbot has a built-in help that lists the commands and options. The general help can becalled either via the commande “help” or by calling TBSCertbot without any command.

$ php tbscertbot.php$ php tbscertbot.php help

You can provide a custom configuration file to overwrite the default file.

$ php tbscertbot.php --config example.org.ini

Each parameter is also configurable on the fly. The following wil allow you to order a 90 daysfree DV Certificate from PositiveSSL.

$ php tbscertbot.php order --product PsfreeW –validity 90

5/15

3. OPTIONS AND PARAMETERS

3.1. CONFIGURATION FILE

As mentionned previously. TBSCertbot requires a configuration file, at least for some internalvalues and default parameters.

The file comes with a description for each pertinent options

3.1.1. TSCertBot configuration

Some internal parameters are left without a category and should not be modified unlessthe implications are understood.Here is a list of the internal categories regarding other settings:[API]: API connection parameters.[DIRECTORIES]: Directories in which main files will be placed (e.g. certs and keys).[HOOKS]: Hooks that allow you to execute scripts on orders, renewals and downloads.

3.1.2. Default values

These categories contain default values:[PRODUCT]: Product choice.[REQUEST]: Certificate request information.[PAYMENT]: Payment details.[MISCELLANEOUS]: Miscellaneous parameters.[ORGANIZATION]: Default organization.[BILLING_ORGANIZATION]: Optional default billing organization.[CORPORATE_CONTACT]: Corporate contact, must be from the organizationrequesting the certificate.[TECHNICAL_CONTACT]: Technical contact, contact that will install the certificate andinteract with the TBS Internet team. Can be external to the organization requesting thecertificate.[LEGAL_CONTACT]: Is used instead of the corporate contact for eIDas/RGScertificates.

6/15

3.1.3. Hooks

Hooks are options that allow you to set an arbitrary script to be executed at the end ofsome command types (order, renewal, download). The following environment variableswill be made available if applicable:

• PHP_TBS_REFERENCE: Your order's TBS reference.

• PHP_TBS_CN: Your certificate's CN (Common Name).

• PHP_TBS_SAN: A comma-separated list of all SAN included in the certificate.

• PHP_TBS_KEY: Absolute path to the private key.

• PHP_TBS_CERT: Absolute path to the certificate file.

• PHP_TBS_CHAIN: Absolute path to the chain file.

• PHP_TBS_DCV: Absolute path to the DCV HTTP file.

Some example scripts are provided with TBSCertBot.

3.2. COMMANDS

The first parameter passed to TBSCertBot is special and represent the internal commandused.

Exhaustive list with descriptions:

• show: displays a list of your TBSCertBot-managed certificates.

• status: displays information on a certificate.

• order: orders a certificate.

• renew: renews a certificate.

• help: displays TBSCertBot's help. Can be used with the following sub-commands:

• product: Display help for product codes.

• software: Display help for software codes.

• country-code: Display help for country codes.

• organization-type: Display help for organization types.

• payment-mode: Display help for payments modes.

7/15

3.3. CLI PARAMETERS

Most options of TBSCertBot can also be modified using cli parameters. You can find anexhausting list using the help command.

$ php tbscertbot.php help

8/15

4. ORDERING A CERTIFICATE

4.1. REQUIREMENTS

As for most commands, the “order” command is based on the default configuration file thatcan be found in the subdirectory data:

data/conf.ini

The following settings must be configured in order to order a certificate:

• API

• Directories (configured by default)

• Product (and validity)

• Request

• Payment

• Organization

• Administrative contact and Technical contact

The following settings are optional:

• Legal Contact (mandatory to order RGS/eIDAS Certificates)

• Billing Entity (can be necessary if it differs from your organization)

• Miscellaneous (if applicable)

• Hooks (if wanted)

4.2. EXAMPLE ORDER

Once all the settings have been entered (either in the default file, via the config argument topass an abitrary file) you can run the order command. Omitted parameters can be added viathe option available in the help command.

$ php tbscertbot.php order

Here is the output from a PositiveSSL test order for example.org (IDs have been obcuscatedand do not correspond to a real order). The HTTP DCV method has been selected.

Validating all parameters...All parameters are OK!

Generating new cryptographic key...

9/15

- Type = RSA - Length = 2048New cryptographic key generated!

Generating new CSR... - CN = example.org - O = TBS INTERNET - L = Caen - ST = Calvados - C = FRNew CSR generated!

Placing order...Order taken into account under the reference 1444444444.

Checking if certificate reference 1444444444 (CN = example.org) is available... -> Certificate is NOT AVAILABLE now, its current state is "Processing". -> Extra information says "Awaiting DCV".

DCV: DCV: example.org: DCV Method: HTTP_CSR_HASH DCV Status: The file is not available yet on your server DCV Checked URL: http://example.org/6BDDC106B1E386E68B1AAEAEACFFFFFF.txt DCV File: /home/user/path/to/tbscertbot/data/dcv/6BDDC106B1E386E68B1AAEAEACFFFFFF.txt

The first step is parameter validation if a parameter is incorrect an error will be raised andthe order will not be processed.

Then, an RSA private key is generated.

Follows the generation of the derived CSR that will be sent to TBS Internet.

Then the order is placed and its status checked.

If applicable the Domain Control Validation (DCV) status will be displayed for each FQDN(SAN fields of the future certificate) of the certificate. DCV is necessary for TBS X509,Comodo, and PositiveSSL certificates.

10/15

5. RENEWING A CERTIFICATE

In order to renew a certificate, it needs to have been ordered using TBSCertBot. The otherprerequisites are the same as regular orders.

To renew a certificate you need to run the “renew” command. By default it tries to renew all thecertificates managed by TBSCertBot. An optional TBS Reference can be passed as aparameter to try to renew only one certificate. To get the TBS Reference of an order, you canuse the “show” command which will be described in a later section.

By default, the previous private key and CSR will be reused. The configuration file key “reuse-keys” can be set to 0 to disable this behavior. Two command line flags --reuse-keys --no-reuse-keys are also available.

To automatically renew certificates, the “cron” command can be run via a cron job or aservice/daemon/unit from the OS service manager. This command will be described in a latersection.

The output of the “renew” command is mostly similar to the “order” command.

11/15

6. DOWNLOADING THE CERTIFICATE LIST

The “download” command allows you to download the latest status updates from yourcertificates.

For each managed certificate, TBSCertBot will check the status, update it if necessary andbriefly display the status.

See an example for a certificate awaiting DCV:

Checking if certificate reference 1444444444 (CN = example.org) is available... -> Certificate is NOT AVAILABLE now, its current state is "Processing". -> Extra information says "Awaiting DCV".

If a certificate is newly available all the links to the pertinent files will be displayed:

Checking if certificate reference 1444444444 (CN = example.org) is available... -> Certificate has been successfully issued! - Certificate downloaded and saved in file /path/to/certs/cert-1444444444.cer - Certificate chain downloaded and saved in file /path/to/certs/chain-1444444444.txt - Moving and renaming private key file to /path/to/keys/key-1444444444.pkey

12/15

7. MANAGING YOUR CERTIFICATES WITH THE “SHOW”COMMAND

The “show” command allows you to see all your certificates, their CN, state and validity period.

$ php tbscertbot.php show+---+------------+-------------+-----------------+------------------+---------------+-----------------+| # | reference | CN | state | extra state info | issuance date | expiration date |+---+------------+-------------+-----------------+------------------+---------------+-----------------+| 1 | 1444444444 | example.org | Processing | Awaiting DCV | | || 2 | 1444444445 | example.com | Currently Valid | Achieved | 2016-09-20 | 2017-09-20 |+---+------------+-------------+-----------------+------------------+---------------+-----------------+

The show command does not automatically update the list, you need to update it using the“download” command. You can combine these actions using your shell capabilities. Forinstance, for Posix sh:

$ php tbscertbot.php download && php tbscertbot.php show

13/15

8. CERTIFICATE STATUS

The “status” command allows you to see all the information related to a specific certificate. Youneed to invoke it passing the TBS Reference of the certificate as a parameter. This reference isdisplayed when the certificate is ordered and can be shown using the “show” command.

$ php tbscertbot.php status 1444444444

You will get various elements such as the validity period, the certificate and chain if they havebeen delivered, or the DCV challenge information if it hasn't been validated yet.

14/15

9. CRON MODE

The “cron” command allows you to combine the download and renew command. That can beused to automate those operations, especially using hooks.

$ php tbscertbot.php cron

15/15