Certificate Management

Certificates are managed from System > Certificates, on the Certificates tab.

When creating a certificate on any platform the process generally follows this flow:

  • User creates a certificate signing request (CSR) and set of keys. The public key is a part of the CSR, but the private key is separate.

  • The user transmits only the CSR to the CA, not the private key which remains private to the user.

  • The CA signs the CSR, which results in a certificate.

  • The CA transmits the certificate to the user.

The user now has a certificate trusted by the CA, and the private key for the certificate.

The GUI handles most this process automatically, but it also supports performing individual steps separately as well. For example, when creating an internal certificate, there is no need to create and sign a CSR in separate steps, the GUI automates that process and does them in one step. Aside from that, the GUI supports creating a CSR which can be sent to a separate CA and it also supports signing CSRs.

Certificate Settings

When creating a certificate entry or working with a CSR, the following common options are available:

Common Properties:

See Certificate Properties which covers properties of most certificate entries.

Certificate Type:

Sets the intended purpose of this certificate. This influences which key usage properties are set in the certificate and thus limits the ways in which the certificate can operate.

Warning

The certificate can only be used for purposes which match the selected type. Attempting to use it in other ways will produce errors and fail, or prevent the certificate from being shown for selection.

User Certificate:

Certificates for end users and clients. For example, IPsec and OpenVPN client certificates.

Note

User type certificates include Extended Key Usage attributes indicating they may be used for client authentication. They also are marked with a constraint indicating that they are not a CA.

Server Certificate:

Certificates for servers, services, daemons, etc. For example, HTTPS servers (GUI, Captive Portal, HAProxy, etc), IPsec IKEv2 mobile server, OpenVPN servers, and for packages such as FreeRADIUS.

Note

Server type certificates include Extended Key Usage attributes indicating they may be used for server authentication as well as the OID 1.3.6.1.5.5.8.2.2 which is used by Microsoft to signifiy that a certificate may be used as an IKE intermediate. These are required for Windows 7 and later to trust the server certificate for use with certain types of VPNs. They also are marked with constraints indicating that they are not a CA, and they have nsCertType set to server.

Alternative Names:

Identifiers for this certificate, such as a hostname. See Subject Alternative Name for details.

When importing an existing certificate entry, the following options are available:

Certificate Data:

The PEM-encoded certificate data for the certificate.

Certificate data is typically contained in a file ending with .crt or .pem. It would be plain text, and enclosed in a block such as:

-----BEGIN CERTIFICATE-----
[A bunch of random-looking base64-encoded data]
-----END CERTIFICATE-----

The format varies slightly for ECDSA certificates.

Private Key Data:

The PEM-encoded private key for the certificate.

The key data is typically in a file ending in .key. It would be plain text data enclosed in a block such as:

-----BEGIN RSA PRIVATE KEY-----
[A bunch of random-looking base64-encoded data]
-----END RSA PRIVATE KEY-----

The format varies slightly for ECDSA keys.

Create a new Certificate

To create a new certificate, start the process as follows:

  • Navigate to System > Certificates, Certificates tab

  • Click Add to create a new certificate

  • Enter a Descriptive name for the certificate

    This is used as a label for this certificate throughout the GUI.

  • Select the Method that best suits how the certificate will be generated

    These options and further instructions are in the corresponding sections below:

    • Create an Internal Certificate

    • Import an Existing Certificate

    • Create a Certificate Signing Request

    • Sign a Certificate Signing Request

  • Complete the steps for the chosen method

  • Click Save to finish the import process

Create an Internal Certificate

The most common Method is Create an Internal Certificate. This will make a new certificate using one of the existing certificate authorities.

  • Select the Certificate Authority which will sign this certificate. Only a CA that has a private key present can be in this list, as the private key is required in order for the CA to sign a certificate.

  • Set the properties of the certificate as described in Certificate Settings.

  • Click Save.

Import an Existing Certificate

To import an existing certificate from an external source, set Method to Import an Existing Certificate. This can be useful for certificates made using another system or for certificates provided by a third party.

There are two ways to import a certificate, indicated by the Certificate Type option:

X.509 (PEM):

Enter the Certificate data and Private key data, which are both required. See Certificate Settings for details on populating the contents of the fields.

The most common error is not pasting in the right portion of the certificate or private key. Make sure to include the entire block, including the beginning header and ending footer around the encoded data.

PKCS #12 (PFX):

This method reads the certificate data from a PKCS #12 file, commonly found with a .p12 extension. If the .p12 file contains a CA, it is also imported along with the certificate, provided it does not already exist locally.

PKCS #12 Certificate:

Click Browse to locate the .p12 file on the local client, it will be uploaded and read when saving.

PKCS #12 Certificate Password:

Enter the password used to protect the contents of the .p12 file

Intermediates:

When set, if the PKCS #12 file contains multiple CA entries in a chain, this option will import all of them instead of only one.

Create a Certificate Signing Request

Choosing a Method of Certificate Signing Request creates a new request file that can signed by a CA at a later time, including by a third party CA not present on the firewall. This is commonly used to obtain a certificate from a trusted root certificate authority.

The parameters for creating this certificate are identical to those for creating a certificate and are covered in Certificate Settings.

Note

Though the GUI shows fields for Certificate Type and Alternative Names as described in Certificate Settings, they are only suggestions for the CA. The signing CA may ignore these options and replace them with values of its own.

Sign a Certificate Signing Request

Signing a certificate signing request (CSR) is a special process which uses an internal CA on the firewall to sign a CSR and turn it into a full-fledged certificate.

The following options are available when signing a CSR:

CA to sign with:

The CA on the firewall which will sign this CSR. This must be an internal CA (private key present).

CSR to sign:

This option chooses whether to sign a new CSR not present on the firewall or an existing CSR on the firewall.

New CSR:

When chosen, the GUI presents fields in which the CSR data can be pasted.

CSR Data:

The PEM-encoded CSR data. CSR data is typically contained in a file ending with .req or .pem. It would be plain text, and enclosed in a block such as:

-----BEGIN CERTIFICATE REQUEST-----
[A bunch of random-looking base64-encoded data]
-----END CERTIFICATE REQUEST-----
Key Data:

The optional PEM-encoded private key for the certificate. This is not required to sign a CSR, but may be useful, or even necessary, if the resulting certificate will be used on the firewall. For example, a private key would be required for a local service or as a user certificate used with a VPN export package.

The key data is typically in a file ending in .key. It would be plain text data enclosed in a block such as:

-----BEGIN RSA PRIVATE KEY-----
[A bunch of random-looking base64-encoded data]
-----END RSA PRIVATE KEY-----
Existing CSR:

The remaining items in the drop-down list are CSR entries which already exist on the firewall. Choose one to sign.

Certificate Lifetime:

The lifetime of the new certificate. See Lifetime for details.

Digest Algorithm:

The digest algorithm for the new certificate. See Digest Algorithm for details.

When signing a CSR, the signing CA may also give new values for Certificate Type and Alternative Names as described in Certificate Settings. The signing process in the GUI does not support automatically reading these values from a CSR, so set them again here.

When complete, the result is a certificate entry in the list, which can then be used or exported.

Edit a Certificate

To edit an existing certificate:

  • Navigate to System > Certificates, Certificates tab

  • Locate the Certificate entry in the list

  • Click the fa-pencil icon at the end of its row to reach the Edit page for the certificate.

The Edit page can modify some aspects of the certificate, such as:

  • The Descriptive Name of the certificate.

  • The Certificate Data, which may need to be replaced if the certificate was renewed by a CA off the firewall.

  • The Private key data, which may need updated if the private key is regenerated (e.g. with a stronger key, or a different key type)

The Edit page also contains options for exporting entries with a password. See Export Password-Protected Files or Use Different Encryption Options for details.

Export a Certificate

There are multiple methods to export certificates. The primary differences are whether or not the files will have password protection and which type of encryption is used to protect the PKCS #12 archive. The certificate itself does not contain private information and thus does not require protection. The private key and PKCS #12 format files do contain private information and thus can be exported in a protected manner.

Export Unprotected Files

  • Navigate to System > Certificates, Certificates tab

  • Locate the Certificate entry in the list

  • Click the fa-certificate icon at the end of its row to export the certificate.

    The file will download with the descriptive name of the certificate as the file name, with the extension .crt.

  • Click the fa-key icon to export the private key for the certificate.

    The file will download with the descriptive name of the certificate as the file name, with the extension .key.

  • Click the fa-archive icon to export a PCKS #12 file containing the CA, certificate, and private key together.

    The file will download with the descriptive name of the certificate as the file name, with the extension .p12.

Export Password-Protected Files or Use Different Encryption Options

The GUI can also export password-protected versions of the private key and PKCS #12 archives. This is more secure, but some systems may not support using password-protected keys. There is also an option to control the type of encryption used to protect the PKCS #12 archive because some platforms do not support certain types of algorithms when dealing with these files.

  • Navigate to System > Certificates, Certificates tab

  • Locate the Certificate entry in the list

  • Click the fa-pencil icon at the end of its row to reach the Edit page for the certificate.

  • Fill in the desired Export Password (or leave it blank to export without a password)

  • Choose an appropriate PKCS #12 Encryption option:

    High:

    Uses AES-256 and SHA256 to encrypt the archive (default). This is the current strongest option and is supported by pfSense software, FreeBSD, Linux, and Windows 10/11. In most cases this is the most desirable option.

    Note

    Use this level when exporting for platforms with OpenSSL 3.0.

    Low:

    Uses 3DES and SHA1 to encrypt the archive. This algorithm is considered weak and deprecated by most modern operating systems, but it is required by the key management built into macOS (current versions, including Ventura 13.2) and older versions of Windows.

    Legacy:

    Uses RC2-40 and SHA1 to encrypt the archive. Avoid using this level if at all possible as it is extremely weak by modern standards. This was the previous default on older versions of pfSense software (Plus 22.05, CE 2.6.0).

    Warning

    OpenSSL 3.0 will not read PKCS #12 archives encrypted with this method as it has deprecated this type of weak encryption.

  • Click the fa-key Export Private Key button to export the private key for the certificate.

    The password-protected file will download with the descriptive name of the certificate as the file name, with the extension .key.

  • Click the fa-archive PCKS #12 button to export a PCKS #12 file containing the CA, certificate, and private key together.

    The password-protected file will download with the descriptive name of the certificate as the file name, with the extension .p12.

Export a Certificate Signing Request

  • Navigate to System > Certificates, Certificates tab

  • Locate the CSR entry in the list

  • Click the fa-right-from-bracket icon at the end of its row to export the CSR.

    The file will download with the descriptive name of the CSR as the file name, with the extension .req.

Remove a Certificate

To remove a certificate, first it must be removed from active use.

  • Check areas that can use a certificate, such as the WebGUI options, OpenVPN, IPsec, and packages

    Note

    In most cases, the areas using a certificate are noted in the In Use column of the certificate list. This does not necessarily include all areas, especially if the certificate is used by a package.

  • Remove entries using the certificate, or choose another certificate

  • Navigate to System > Certificates, Certificates tab

  • Locate the certificate to delete in the list

  • Click fa-trash-can at the end of the row for the certificate

    Note

    This icon will only be present if the certificate is not in use.

  • Click OK on the confirmation dialog

Renew a Certificate

To renew a certificate entry:

  • Navigate to System > Certificates, Certificates tab

  • Locate the certificate entry in the list

  • Click fa-arrow-rotate-right at the end of the row for the certificate

  • Follow the rest of the renewal procedure as described in Renew or Reissue a CA or Certificate

User Certificates

If a VPN is being used that requires user certificates, they may be created in one of several ways. The exact method depends on where the authentication for the VPN is being performed and whether or not the certificate already exists.

No Authentication or External Authentication

If there is no user authentication, or if the user authentication is being performed on an external server (RADIUS, LDAP, etc) then make a user certificate like any other certificate described earlier. Ensure that User Certificate is selected for the Certificate Type and set the Common Name to match the username.

Local Authentication

If user authentication is being performed by this firewall, the user certificate can be made inside of the User Manager. The User Manager can create a certificate while creating a user or it can add certificates to existing users. These processes are documented at Manage Local Users.