Installation and configuration

This page describes how to configure the connector to automate certificate lifecycle management. The configuration involves validating domains in SCM, creating an ACME account, and defining certificate profile and credentials files.

Create ACME account and obtain EAB values

Log in to SCM at https://cert-manager.com/customer/<customer_uri> with the MRAO administrator credentials provided to your organization.

Sectigo runs multiple instances of SCM. The main instance of SCM is accessible at https://cert-manager.com. If your account is on a different instance, adjust the URL accordingly.
Navigate to Enrollment ACME.
Select your ACME endpoint.
Click Accounts.
Click Add and provide the following details:
- Name: A name for the ACME account
- Organization: The organization to be associated with the ACME account
- Department: (Optional) The department to be associated with the ACME account
Click Save.

External Account Binding (EAB) is now created for the new ACME account.
Make a note of the following ACME account details for client registration:

ACME URL

Key ID

HMAC Key
Click Close.

Install the connector

Login as root to the Linux client machine.
Navigate to the /opt directory.
Copy the sectigo-acme-f5-bigip-<version>.tgz file to the /opt directory.
Extract the file to the /opt directory.
```
tar xvf sectigo-acme-f5-bigip-<version>.tgz
```
This will create a subdirectory called sectigo under /opt.
Navigate to the sectigo directory.
Run ./install.sh.

You can accept EULA automatically by using the ./install.sh --agree-tos command.

Set up the SCM ACME credentials file

Update the /opt/sectigo/env file with ACME account details corresponding to your account in SCM. You can have details for one or more ACME accounts, separated with labels. The default account doesn’t require any label. Additional accounts inherit parameters and values from the default account, or you can override them.

ACME_URL=https://acme.demo.sectigo.com
ACME_EXTERNAL_ACCOUNT_ID=2a82af7331a11fc8b9ec2793d924b0aa
ACME_EXTERNAL_ACCOUNT_KEY=AqlqlXB9mQoQzrGHmFzLSdbhENiea9RibwyCZoNfXrp7o7A1Yb9pvPwCPFpl7ZBMztc752le8VhCDXyTg5ms68U6
[email protected]
EXPIRY_WINDOW=30

[acme.ov]
ACME_URL=https://acme.secure.trust-provider.com/v2/OV
ACME_EXTERNAL_ACCOUNT_ID=4d31gd7331a11jc8b9ek2783d924b0aa
ACME_EXTERNAL_ACCOUNT_KEY=KulqlMB2mQoQzrGHmFzLSdbhENiea9LibwyCZoDfXpc7o7A1Yb9pvPwCPFpl7ZBMztc752le8VhCDXyTg5ms68U6

[acme.enterprise]
ACME_URL=https://enterprise.acme.sectigo.com
ACME_EXTERNAL_ACCOUNT_ID=6c35hf7351a13fh8d9kc2753l914l0ar
ACME_EXTERNAL_ACCOUNT_KEY=VrlalXB9mJoQzrPHmFjLSubhENiea3RibwyPZoSfHrp7o7A4Yb5pvPwCPFpl2ZBMztc843le8VhCDXyTg5ms68U6
EXPIRY_WINDOW=60

The following table describes the parameters in the env file.

Variable Mandatory Description

Variable	Mandatory	Description
`ACME_URL`	Yes	The URL of the ACME service
`ACME_EXTERNAL_ACCOUNT_ID`	Yes	The key identifier (key ID) for EAB
`ACME_EXTERNAL_ACCOUNT_KEY`	Yes	The hash-based message authentication code (HMAC key) for EAB
`ACME_NON_INTERACTIVE_EMAIL`	Yes	An email address for important account notifications
`ACME_USER_AGENT_COMMENT`	No	A comment to be added to the `User-Agent` header when communicating with the ACME service
`EXPIRY_WINDOW`	No	The number of days prior to expiration that a certificate renewal process is initiated. The default value is `30` days. This is a global parameter that is applied to all certificate profiles. For per-certificate expiry window control, apply an optional parameter `expiry_window` in the certificate profile file.
`acme.<label>`	No	A user-defined credentials label. This label is referenced in the `acme_account` parameter in a certificate profile file. You can have details for multiple accounts, each with their own label. The label name must start with `acme.`

ACME_URL

Yes

The URL of the ACME service

ACME_EXTERNAL_ACCOUNT_ID

Yes

The key identifier (key ID) for EAB

ACME_EXTERNAL_ACCOUNT_KEY

Yes

The hash-based message authentication code (HMAC key) for EAB

ACME_NON_INTERACTIVE_EMAIL

Yes

An email address for important account notifications

ACME_USER_AGENT_COMMENT

A comment to be added to the User-Agent header when communicating with the ACME service

EXPIRY_WINDOW

The number of days prior to expiration that a certificate renewal process is initiated. The default value is 30 days.

This is a global parameter that is applied to all certificate profiles. For per-certificate expiry window control, apply an optional parameter expiry_window in the certificate profile file.

acme.<label>

A user-defined credentials label. This label is referenced in the acme_account parameter in a certificate profile file. You can have details for multiple accounts, each with their own label. The label name must start with acme.

Set up the certificate profile file

Certificate profile files are YAML-based. Each file represents certificate configuration for one appliance.

To define a certificate profile file:

Create a directory called sectigo under the /etc directory (/etc/sectigo) with root privileges.

Copy the f5_demo.yaml file from the package to the /etc/sectigo directory and modify the values.

Sample certificate profile file

name: demo1
version: v1

devices:
- name: device1
  common_name: example.iiswebserver.com
  san_domains:
     - example.slitaz.com
     - example.nginxwebservere.com
  key_type: rsa
  key_size: 4096
  acme_account: acme.ov
  bigip_list:
    - 192.168.23.155
  protocol: https
  verify_ssl: no
  username: john
  password: doe123
  bigip_partition: Common
  bigip_clientssl_parent: /Common/clientssl
  #use_clientssl: my_bigip_profile_name
  bigip_unused_profile: xoxoprofile
  sni: no
  #expiry_window: 30
  renew_on_ocsp_fail: no
  force_renew: no
  virtualservers:
    - name: VSAB
      port: 8443

The following table describes the parameters in the configuration file.

Parameter Description

version

The value must be set to v1

name

The name of the certificate used by the Certbot command. This value is passed to the <configured_name> parameter in the certbot run command.

The name must be unique across all configuration files—otherwise, unrelated certificates are overwritten.

common_name

The Common Name (CN) for the appliance.

The connector also supports wildcard certificate issuance and installation on the BIG-IP devices. Wildcards use DNS-01 DCV challenge, so the domain should be capable of handling this challenge type for public certificates.

For a wildcard certificate, put double quotes around the domain name.

san_domains

(Optional) A list of SANs associated with the Common Name.

The Common Name is added automatically to the SAN values.

devices

Each entry specifies an appliance on which the certificate is to be installed:

name: Optional name of the device. The default value is host.
protocol: The value must be http or https
verify_ssl: (Optional) Specifies whether the certificate chain will be verified by the device up to the root certificate. For a certificate issued by a public CA, the possible values are yes and no. For a certificate from a private CA, specify the full path to the CA bundle on your local machine. The default value is no.

This parameter has no effect when protocol is http.
username: The username of the BIG-IP user
password: The password of the BIG-IP user

If you store credentials in the credentials file, username and password can be omitted.
key_type: The possible key types are RSA (rsa) and ECDSA (ecdsa)
key_size: The possible key sizes for RSA and ECDSA keys:
- RSA: 2048, 3072, or 4096
- ECDSA: secp256r1, secp384r1, or secp521r1
protect_key: Specifies whether to set a passphrase for the private key. The possible values are yes/no. Default is yes, which means the generated private key will be protected with a passphrase.
acme_account: The credentials label from the env file. If you use the default ACME account, this parameter can be omitted.
bigip_partition: The partition name. The default value is Common.
bigip_clientssl_parent: An existing client SSL profile to use as the parent profile. The default is the clientssl profile.
use_clientssl: (Optional) An existing client SSL profile on BIG-IP. If the profile was found on the appliance, the profile’s certificate chain is updated with a new certificate, and the profile is attached to the virtual server(s).

If the value is not set, or no such profile was found on the appliance, a new client SSL profile is created.
bigip_list: If the BIG-IP appliances are in a HA group, specify one or more comma-separated IP addresses
bigip_unused_profile: (Optional) An existing client SSL profile to detach from the virtual server(s) and replace with a new profile (or with the profile specified in use_clientssl).
sni: Specifies whether Server Name Indication (SNI) is enabled for a client SSL profile. The possible values are yes and no. The default value is no.
expiry_window: (Optional) The number of days prior to expiration that a certificate renewal process is initiated. The default value is 30 days.

This is a local parameter that overrides the EXPIRY_WINDOW parameter in the ACME credentials file and is applied for per-certificate expiry window control.
renew_on_ocsp_fail: Specifies whether to renew a certificate if OCSP check fails. For example, you can use this parameter to renew a certificate issued by a Microsoft CA which doesn’t provide the required OSCP URL. The possible values are yes and no. The default value is no.
force_renew: Specifies whether to force the renewal of a certificate. If set to yes, the existing certificate will be renewed regardless of expiration date and status. The default value is no.
virtualservers: A list of virtual servers
- name: The name of the virtual server
- port: (Optional) The port that the virtual server will listen on for incoming connections after a certificate has been enrolled and bound to it. The default value is 443.
If the virtualservers parameter is not specified, the certificate is not bound to the virtual server, but is still installed on the appliances.

Set up the F5 credentials file

Optionally, you may move your BIG-IP username and password from the <example_cert_config>.yaml file to a separate file (for example, <bigip_creds>.yaml) to avoid exposing the credentials on a version control system or similar infrastructure tool.

bigip_devices:
  - host: 12.345.67.89
    username: admin
    password: john_1234
  - host: 21.345.67.89
    username: admin
    password: john_jr_1234

Encrypting the credentials file

The connector can work with a plaintext or encrypted configuration file. If you prefer to store your BIG-IP credentials in an ecrypted form, you need to install the GPG command-line tool and sops editor for encrypted files.

Encrypting the BIG-IP password is an optional but recommended step to protect your credentials from unauthorized access.

GPG keys with passphrase are not supported by the connector.

Install GPG

Run the following commands to install GPG (GNU Privacy Guard). The last two commands let you generate some randomness required to generate a key.

To check whether GPG is installed on the system, run gpg --version.

sudo apt install gnupg
sudo apt install rng-tools
sudo sed -i -e 's|#HRNGDEVICE=/dev/hwrng|HRNGDEVICE=/dev/urandom|' /etc/default/rng-tools
sudo service rng-tools start
GPG_TTY=$(tty)
export GPG_TTY

sudo yum install gnupg
sudo yum install rng-tools
sudo sed -i -e 's|#HRNGDEVICE=/dev/hwrng|HRNGDEVICE=/dev/urandom|' /etc/default/rng-tools
sudo service rng-tools start
GPG_TTY=$(tty)
export GPG_TTY

Install sops

Install the sops editor for encrypting and decrypting the credentials.

To check whether sops is installed on the system, use the sops --version command.

Encrypt the credentials file

Create a private key.
- Unattended key generation
- Attended key generation
gpg --batch --passphrase '' --quick-gen-key $(whoami) default default
The --quick-generate-key option requires you to specify the user ID field on the command line and optionally an algorithm, usage, and expire date. Default values are used for all other options.
gpg --full-generate-key
The --generate-key option prompts for the real name and email fields before asking for a confirmation to proceed, and provides a dialog for all options.
Retrieve the key fingerprint.
```
gpg --list-keys
```
Encrypt either your certificate configuration file or your external credentials file, depending on where you store the BIG-IP credentials.
- Full encryption
- Partial encryption
This command encrypts the values of all parameters in the file.
sops --encrypt --in-place --pgp <fingerpint> [<cert_config>.yaml] [<bigip_creds>.yaml]
If you’d like to encrypt specific values—for example, the client secret and password, you can use a regular expression.
sops --encrypt --encrypted-regex '^client_secret$' --in-place --pgp <fingerpint> scm.yaml sops --encrypt --encrypted-regex '^password$' --in-place --pgp <fingerpint> [<cert_config>.yaml] [<bigip_creds>.yaml]

Edit the credentials file

If you need to edit the ecrypted file, you don’t have to decrypt it—simply use the sops editor to edit the file as if it contained plaintext values.

bigip_creds.yaml

If you want to decrypt the file, run the following command.

sops --decrypt --in-place bigip_creds.yaml