Configuring AppViewX Certbot Client

source venv/bin/activate

1. Using HTTP challenge in Standalone Mode
   HTTP-01 challenge:This is the most common challenge type. The ACME server issues a token to the ACME client, and the ACME client puts a file on the web server at http://<YOUR_DOMAIN>/.well-known/acme-challenge/<TOKEN>. Once the token is published on the web server (Linux server), AppViewX sends an HTTP request to fetch the token from the client machine.

   Note: The common name must resolve to the IP address of the client machine, and port 80 on the client machine must be accessible to AppViewX.
   • A sample Certbot certificate enrollment command using HTTP challenge is as shown:

     certbot -vv certonly --standalone --preferred-challenges http -d <domain_name> --logs-dir /etc/avx-certbot/
     --config-dir /etc/avx-certbot/ --work-dir /etc/avx-certbot/ -m <mail_id> --agree-tos --no-verify-ssl --server <ACME server endpoint URL fetched from AppViewX GUI>
     

2. Using HTTP challenge when Apache server is running on Port 80

   If the Apache server is already running on port 80 but is not available, Certbot's Apache plugin allows it to be used for challenge validation. To enable this functionality, a new folder must be created in the /etc directory. This directory will serve as the configuration, working, and log directory when using the --apache plugin option. For example, by creating a folder named avx-certbot within /etc and specifying it as a custom directory, this setup can be achieved..

   A sample command is as shown:

   certbot certonly --apache -d <domain_name> --preferred-challenges http -m <Email> --agree-tos --no-verify-ssl --server <ACME_URL> --config-dir /etc/avx-certbot/ --logs-dir /etc/avx-certbot/ --work-dir /etc/avx-certbot/

3. Using DNS challenge

   DNS-01 challenge: This challenge requires you to demonstrate control over the DNS for the domain name by inserting a specific value into a TXT record within that domain. Subsequently, AppViewX conducts a DNS query to verify the presence of the token in the domain's DNS records.

   Refer to the following link to configure and use Certbot with different type of DNS servers: https://eff-certbot.readthedocs.io/

   • Default Challenge Validation (using default plugins)

     This challenge requires demonstrating control over the DNS for a domain by adding a specific value to a TXT record within that domain. AppViewX then performs a DNS query to verify the presence of the token in the domain's DNS records.

     A sample command to do the challenge validation using the AWS route 53 server is as shown:

     certbot -vv certonly --preferred-challenges dns --dns-route53 -d <domain_name> --logs-dir /etc/avx-certbot/--config-dir /etc/avx-certbot/ --work-dir/etc/avx-certbot/ -m <mail_id> --agree-tos --no-verify-ssl --server<ACME server endpoint URL fetched from AppViewX GUI>

     You must configure the credentials in Certbot to access the DNS servers. Refer to the following link to configure and use Certbot with different type of DNS servers: https://eff-certbot.readthedocs.io/en/stable/
   • DNS Challenge Validation (using AppViewX DNS plugin with Infoblox DNS Server)

     This challenge requires demonstrating how AppViewX manages DNS for the domain by adding a specific value to a TXT record within it. AppViewX then performs a DNS query to verify the token's presence in the domain's DNS records. With the support of Platform Integration Hub, AppViewX will handle all tasks related to creating, searching for, and deleting TXT records in the DNS server.

     A sample command to do the AppViewX DNS Challenge Validation option is as shown:

     certbot certonly --dns-appviewx --dns-vendor infoblox --dns-server <Infoblox server name configured in appviewx> -d <Domain name> --logs-dir <logs dir>
     --config-dir <config dir> --work-dir <work dir> -m <mail id> --agree-tos --no-verify-ssl --eab-kid <key identifier> --eab-hmac-key <HMAC value> --server <acme url>
     

   • Enterprise Secure Challenge Validation

     This challenge involves demonstrating how AppViewX manages DNS for a domain by querying the DNS A record to verify the presence of the client's IP address. This verification does not require DNS server credentials, as it only entails accessing the DNS A record for the specified domain.

     A sample command to do the AppViewX Enterprise Secure Challenge Validation option is as shown:

     certbot certonly --dns-appviewx -d <Domain name> --logs-dir <logs_dir> --config-dir <config_dir> --work-dir <work_dir> --agree-tos --no-verify-ssl --eab-kid
     <key identifier> --eab-hmac-key <HMAC value> --server <acme_server_url>
     

     Note: DNS Challenge Validation and Enterprise Secure Challenge Validation are only supported through the command-line interface (CLI) and not through the interactive script (execute.sh).

     Re-enrolling Certbot using DNS-Based Challenge Validation

   • Default Challenge Validation

     certbot renew --no-verify-ssl --no-random-sleep-on-renew --eab-kid <key identifier> --eab-hmac-key <HMAC value> --config-dir <config dir for which renew
     should be triggered> --force-renewal
     

     To automate renewal for Certbot through cron job, run:

     (crontab -l ; echo "MM HH * * * /usr/bin/env bash -c 'source <certbot_folder/venv/bin/activate> && certbot renew --no-verify-ssl --no-random-sleep-on-renew
     --config-dir <config_dir>'") | crontab -
     

   • DNS Challenge Validation

     certbot renew --dns-appviewx --dns-vendor infoblox --dns-server <Infoblox server name configured in appviewx> --no-verify-ssl --no-random-sleep-on-renew
     --config-dir <config dir for which renew should be triggered> --eab-kid <key identifier> --eab-hmac-key <HMAC value> --force-renewal
     

     To automate renewal for Certbot through cron job, run:

     (crontab -l ; echo "MM HH * * * /usr/bin/env bash -c 'source <certbot_folder/venv/bin/activate> && certbot renew --dns-appviewx --dns-vendor infoblox
     --dns-server <Infoblox server name configured in appviewx> --no-verify-ssl --no-random-sleep-on-renew --config-dir <config dir for which renew should be triggered> --eab-kid <key identifier> --eab-hmac-key <HMAC value> --force-renewal'") | crontab -
     

   • Enterprise Secure Challenge Validation

     certbot renew --dns-appviewx --no-verify-ssl --no-random-sleep-on-renew --config-dir <config dir for which renew should be triggered> --eab-kid <key
     identifier> --eab-hmac-key <HMAC value> --force-renewal
     

     To automate renewal for Certbot through cron job, run:

     (crontab -l ; echo "MM HH * * * /usr/bin/env bash -c 'source <certbot_folder/venv/bin/activate> && certbot renew --dns-appviewx --no-verify-ssl
     --no-random-sleep-on-renew --config-dir <config dir for which renew should be triggered> --eab-kid <key identifier> --eab-hmac-key <HMAC value>
     --force-renewal'") | crontab -
     

4. Using Polling during Enrollment

   Polling can be activated when manual approval is configured for certificate generation. In this scenario, the client conducts polling for the certificate within a specified time frame, as determined by the configured parameters. If the certificate is approved before the polling duration expires, it is retrieved. To enable polling in the Certbot client, you may pass the parameters as mentioned:

   Parameters	Type	Mandatory	Description
   --retry-after	Integer	No	The waiting period in seconds, after which the next call in the polling is triggered. [Default value : 10]
   --retry-frequency	Integer	No	The number of times for which the certificate is polled from the client side. [Default value : 20]

   A sample command with retry-after as 5 and retry-frequency as 10 is as shown:

   certbot -vv certonly --standalone --preferred-challenges http -d <domain_name> --logs-dir /etc/avx-certbot/ --config-dir /etc/avx-certbot/ --work-dir /etc/avx-certbot/ -m <mail_id> --agree-tos --no-verify-ssl --server <ACME server endpoint URL fetched from AppViewX GUI> --retry-after 5 --retry-frequency 10

   In this case, the certificate is polled 10 times with a 5-second interval for each polling attempt. Therefore, the polling process takes a total of 10 x 5 = 50 seconds to complete.

   Note: To enable polling during the renewal process, it is important to include these parameters along with the renewal commands.
5. Providing Custom and Certificate Attributes during Enrollment

   Certbot can be run with custom attributes allowing additional command line arguments. These arguments can include multiple name-value pairs, which are then included in the Finalize Order call along with the CSR. The values for these fields are provided as a JSON name/value pair, which can then be retrieved and mapped to the custom attributes in our application. This mapping enables including the custom attribute information in the certificate request for reporting.

   A sample Certbot certificate enrollment command with custom attributes is as shown:

   certbot -vv certonly --standalone --preferred-challenges http -d <domain_name> --logs-dir /etc/avx-certbot/
   --config-dir /etc/avx-certbot/ --work-dir /etc/avx-certbot/ -m <mail_id> --agree-tos --no-verify-ssl --server <ACME server endpoint URL fetched from AppViewX GUI> --attributes "cust_id:123,name:appviewx" --attribute-type custom

   This section covers the attributes and attribute-type parameters.

   1. The --attributes field allows users to provide multiple attributes as a string with comma and colon separated values in the Certbot command. Format: name:AppViewX,city:Coimbatore

      The attributes field must adhere to the following guidelines:

      • The string must not be empty and must contain at least one name-value pair.
      • Multiple name-value pairs can be provided within the string separated by a comma.
      • Space is only allowed in the value field of the name-value pairs.
      • The attributes, after processing, will be sent as part of the payload in the finalize order call along with the CSR.
   2. The --attributes field must be accompanied with the --attribute-type field that takes in one of the following inputs:
      • cert
      • custom
      • both
      1. When attribute-type is passed as cert the attributes from the (--attributes) field are taken as certificate attributes. An example of certificate attribute is:

         --attributes "id:1098,environment:development,Director:director_id" --attribute-type cert

         The following image depicts how certificate attributes are defined in Certbot command:
      2. When attribute-type is passed as custom the attributes from the (--attributes) field are taken as custom attributes. An example of certificate attribute is as follows:

         --attributes "cust_id:123,name:appviewx" --attribute-type custom

         The image shows how certificate attributes are defined in the Certbot command:
      3. When attribute-type is passed as both, a JSON mapping is expected by the AppViewX Certbot. A new JSON file named attributesMapping.json needs to be created inside the Certbot folder. A sample JSON file is as shown:

         {
         "senior_director" : "Sr Director",
         "intermediate_director" : "Intermediate Director"
         }
         

         • The key [in the key:value pair from attributesMapping.json] refers to the certificate attribute key provided in the command, while the value corresponds to the custom attribute key where the value of the certificate attribute must be passed.
         • The attributes passed as input are sent as certificate attributes. For attributes present in the attributesMapping.json, the mapped value is being used as attribute name and sent as custom attribute.

         An example of custom attribute is as follows:

         --attributes "cust_id:123,name:appviewx,senior_director:srDirector_id_1,intermediate_director:IntDirector_2" --attribute-type both

         The image shows how certificate attributes are defined in Certbot command:
         Note:

         • The attributes are applicable only to Method 1: Using Certbot Command Line.
         • If the attributes and attribute-type field are not specified in the Certbot command, normal flow of Certbot will work fine without any exceptions.
6. Using EAB Credentials during Enrollment
   A sample Certbot certificate enrollment command with external account binding enabled in the ACME server:

   certbot -vv certonly --standalone --preferred-challenges http -d <domain_name> --logs-dir /etc/avx-certbot/
   --config-dir /etc/avx-certbot/ --work-dir /etc/avx-certbot/ -m <mail_id> --agree-tos --no-verify-ssl --server <ACME server endpoint URL fetched from AppViewX GUI> --eab-kid <Key identifier> --eab-hmac-key <MAC value>
   

   Note: This command is applicable only when the EAB algorithm is HS256. For other algorithms, use the cert_config.json file and adjust the configuration accordingly.
7. Certbot - CSR and EAB Configuration

   Providing CSR Parameters and EAB Fields

   The file named cert_config_template.json located in the Certbot directory is designed to facilitate the configuration of CSR and External Account Binding (EAB) fields. Renaming this file to cert_config.json and subsequently populating the required fields will ensure that these configurations are applied.

   CSR fields that can be provided:

   1. Subject fields:
      1. Organization
      2. Organization unit
      3. Country
      4. State
      5. Locality
   2. Hashing algorithm
   3. RSA Key-Size
   4. key type
   5. elliptic curve details

   EAB fields that can be provided:

   1. EAB HMAC
   2. EAB KID
   3. EAB Algorithm

   Note:

   • EAB details can be provided via Certbot command parameters or a cert_config.json file. The Certbot command only supports HS256. Other EAB algorithms require the cert_config.json file.
   • The cert_config.json file contains key-value pairs for all subject fields. If any of these fields are not required, the corresponding key-value pair can be deleted from thecert_config.json.
   A sample JSON is as follows:

   
   {
   "csr_params": {
           "organization" : "AVX",
           "organization_unit" : "AVX_IOT",
           "country" : "IN",
           "state" : "TN",
           "locality" : "CBE",
           "hashing_algorithm":"SHA512",
           "rsa_key_size": "4096",
           "key_type":"rsa",
           "elliptic_curve":""
           },
   "eab": {
           "kid":"",
           "mac":"",
           "alg":""
   }
   

   Json keys	Expected Input	Comments
   csr_params:organization csr_params:organization_unit csr_params:country csr_params:state csr_params:Locality	String	Choose the appropriate subject fields for the CSR.
   csr_params:hashing_algorithm	<Hashing_Algorithm>	Choose the appropriate hashing algorithm [SHA256,SHA384 & SHA512]
   csr_params:rsa_key_size	<RSA_keysize> (String)	Default value : “2048” The size of the private key to use for the certificate. For RSA keys, specify a number between 2048-4096 (divisible by 128) [Provide this field only when key_type is set to “rsa” ]
   csr_params:key_type	Possible values : [“rsa”, “ecdsa”] (String)	Default value : “rsa” Provide the key type which can be used for private key generation.
   csr_params:elliptic_curve	Possible values : [“secp256r1” , “secp384r1”, “secp521r1”] (String)	Default value : “secp256r1” The type of elliptic curve can be specified here. [Provide this field only when key_type is set to “ecdsa” ]
   eab:kid	<value_of_EAB_KID>	Key Identifier for External Account Binding (Optional).
   eab:hmac	<value_of_EAB_HMAC_KEY>	HMAC key for External Account Binding (Optional).
   eab:alg	HS256/HS384/HS512	Default value : “HS256” Signature Algorithm for External Account Binding.

   Note: When a certificate is initially created with key_type set to rsa and needs to be changed or renewed to ecdsa, you must use the --key-type ecdsa option along with --cert-name on the command line during the certificate creation or renewal process.

   Example: certbot renew --key-type ecdsa --cert-name example.com --force-renewal

With the AppViewX Certbot user-friendly script, you can run commands to perform enroll, renew, and revoke certificate actions by activating the virtual environment as described in this section.

Errors are also encountered if any extra arguments, other than supported arguments are given in the Certbot command. They are as follows:

1. Sample command: certbot -vv certonly -d sampledomain.info --preferred-challenges dns --dns-route53 --logs-dir /home/appviewx/certbot/certbot_certs/ --config-dir /home/appviewx/certbot/certbot_certs/ --work-dir /home/appviewx/certbot/certbot_certs/ -m <mail_id> --agree-tos --no-verify-ssl --server <ACME server endpoint URL fetched from AppViewX GUI> -

   Error: certbot: error: unrecognized arguments

2. Sample command: certbot certbot -vv certonly -d sampledomain.info --preferred-challenges dns --dns-route53 --logs-dir /home/appviewx/certbot/certbot_certs/ --config-dir /home/appviewx/certbot/certbot_certs/ --work-dir /home/appviewx/certbot/certbot_certs/ -m <mail_id> --agree-tos --no-verify-ssl --server <ACME server endpoint URL fetched from AppViewX GUI> cert

   Error: certbot: error: unrecognized arguments: cert

3. Sample command: certbot -vv certonly -d sampledomain.info --preferred-challenges dns --dns-route53 --logs-dir /home/appviewx/certbot/certbot_certs/ --config-dir /home/appviewx/certbot/certbot_certs/ --work-dir /home/appviewx/certbot/certbot_certs/ -m <mail_id> --agree-tos --no-verify-ssl --server <ACME server endpoint URL fetched from AppViewX GUI> -cert

   Error: certbot: error: Unable to open config file: ert. Error: No such file or directory

4. Sample command: certbot -vv certonly -d sampledomain.info --preferred-challenges dns --dns-route53 --logs-dir /home/appviewx/certbot/certbot_certs/ --config-dir /home/appviewx/certbot/certbot_certs/ --work-dir /home/appviewx/certbot/certbot_certs/ -m <mail_id> --agree-tos --no-verify-ssl --server <ACME server endpoint URL fetched from AppViewX GUI> -test

   Error: certbot: error: argument -t/--text: ignored explicit argument 'est'