Setting up hook for DCV HTTP/HTTPS in TBSCertBot

It is possible to validate DCV controls via TBSCertBot using different methods, including HTTP/HTTPS file.

This documentation explains how to set up a hook to generate the DCV file and place it in the desired directory.

Hooks creation

You can create as many hooks as you like. A testing feature called "test-hook" exists within TBSCertBot specifically for testing your hooks.

How to test your hooks?

To test a hook, you must use the command:

php tbscertbot.php test-hook NAME_OF_THE_HOOK [TBS reference].

The TBS reference is optional. Indicate it if you want to test your hook on a specific command. Example:

php tbscertbot.php test-hook download 1234567890.

This command will restart the script related to the download hook on command 1234567890. You can find some example hooks in the data/testhooks directory of your TBSCertBot installation.

Configuring the DCV parameter

The DCV (Domain Control Validation) parameter can be configured in two different ways:

• In the configuration file: You can set the DCV parameter directly in the configuration file:

      [REQUEST]
      domainControlValidation = HTTP_CSR_HASH
      

• In command line: You can specify the DCV parameter when running the TBSCertBot order command. Here is an example of a command line:

      #php tbscertbot.php order --product ssl --maindomain domain.tld --dcv HTTP_CSR_HASH
      

The available values ​​for the DCV method in the configuration file are:

• HTTP_CSR_HASH: text file to place in your website accessible in HTTP
• HTTPS_CSR_HASH: text file to place in your website accessible in HTTPS
• CNAME_CSR_HASH: CNAME entry to add to your DNS configuration
• DNSTXT_CSR_HASH (for DigiCert products only): TXT entry to add to your DNS configuration
• Email address: a valid email address among admin@, administrator@, hostmaster@, postmaster@, webmaster@domain.tld

DCV Hook

Environment variables

The following environment variables are set to use the DCV DNS functionality:

• PHP_TBS_DCV_METHOD: DCV method (e.g. dns-txt-token or dns-cname-token)
• PHP_TBS_DCV_DOMAIN_ROOT: Root domain for DCV
• PHP_TBS_DCV_DOMAIN_SUB: Subdomain for DCV
• PHP_TBS_DCV_VALUE: Value for DCV
• PHP_TBS_DNS_ACTION: Action for DNS (CREATE or UPDATE)
• PHP_TBS_REGISTRAR: Domain registrar (for example, GANDI SAS or OVH SAS)

DCV Hook Configuration

• In the configuration file: Add the DCV hook configuration to the conf.ini file. Here is an example:

      [HOOKS]
      dcv = /path/to/exportDCVScript.sh
      

Script

# define the DCV file parameters
SSHHOST="server.domain.tld"
SSHUSER="user"
SSHPASS="YOURPASSWORD"
SSHPATH="path"

# Only if PHP_TBS_DCV_METHOD empty or http-token
echo "Method : PHP_TBS_DCV_METHOD"
if [ -z "$PHP_TBS_DCV_METHOD" ] || [ "$PHP_TBS_DCV_METHOD" = "http-token" ]; then
 echo "Send the DCV file to the server"
 export SSHPASS="$SSHPASS"
 sshpass -e sftp -oBatchMode=no -b - "$SSHUSER"@"$SSHHOST" ‹‹ !
 cd "$SSHPATH"/.well-known/pki-validation
 put $PHP_TBS_DCV
 bye
!
fi

Displaying DCV values ​​and their statuses

DCV values ​​and their statuses can be displayed using the TBSCertBot status command. Here is an example:

#php tbscertbot.php status REFERENCE

example result:

DCV:
  test.domain.tld: unapproved
    -> DCV Method: http-token
    -> DCV File location: http://test.domain.tld/.well-known/pki-validation/7912F4DA0F3E42E92CA593F8E319AE2F.txt
    -> DCV File content: c74735f59b4f108da31dfe37ca375493f53cc603354155bd05f7bb2c530039b4
trust-provider.com
XjqHgF6uSTqO7gCwvop7

Updating information in cron mode

If the DCV is not known at the time of the order, TBSCertBot can be run in cron mode to receive the information to set the values. Once configured, reissuances will use the same mechanics.