How do I upload my certificate to TR7; which formats are supported?

Short answer

The certificate is uploaded with Add on the Certificates & PKI → SSL/TLS Certificates screen: Type = Manual is selected and the certificate and the private key are entered in separate fields, or Type = PFX is selected and the PKCS#12 file is imported with its password. The Certificate Content field accepts the PEM, PKCS#7/P7B and DER formats; the private key must be an RSA or EC key in PEM format, and the password of the PFX file cannot be left empty. The uploaded certificate starts to be used when it is selected in the Certificate field of the vService.

Problem: Moving the Organization's Certificate to TR7

To provide an HTTPS service, the certificate and its private key must be present on TR7. Certificates come from different sources in different formats: separate PEM files from the certificate provider, a PFX file exported from Windows servers, a P7B bundle from some CAs. If the type suitable for the format is not selected, the record is rejected or the certificate is presented without its chain.

Solution: Two Methods

Depending on the format in which the certificate and the key are at hand, one of the two paths is used; both create the same certificate record.

Your situation	Suitable method
The certificate and the private key are in separate files (PEM, P7B or DER certificate + PEM key)	Method 1: Manual
The certificate, the key and the chain are in a single password-protected file (PFX / PKCS#12)	Method 2: PFX
There is no certificate at hand; the domain name is open to the internet	Automatic retrieval with ACME → Can I get certificates automatically with Let's Encrypt / ACME?
The key will be generated on TR7 and signed by a corporate or commercial CA	Can I create a CSR on TR7?
The certificate will be generated with the internal CA on TR7	Can I use TR7 as an internal CA to issue, automatically renew and revoke certificates?

Accepted formats:

Field	Accepted	Note
Certificate Content	PEM (one or more BEGIN CERTIFICATE blocks), PKCS#7/P7B (BEGIN PKCS7 block or binary), DER (.cer binary or Base64 body)	P7B and DER are converted to PEM while saving; unrecognized content is rejected. If a file is dragged, at most 32 KB
Key Content	RSA or EC private key in PEM format (PKCS#1, PKCS#8 or EC key)	The password of a password-protected key is entered in the Password field
PFX File	PKCS#12 file with the .pfx extension	The password is mandatory; the chain in the file is taken automatically

Method 1: Manual Recommended

• How it works The certificate and the private key are pasted into separate fields or dragged as files; the intermediate and root certificates are added in the same form.
• Where it is openedCertificates & PKI → SSL/TLS Certificates → Add → Type = Manual
• Requirement The certificate (PEM, P7B or DER) and the matching PEM private key
• vService type HTTP, L7 TCP (encrypted frontend)

Step-by-Step Configuration

1

Adım 1 Open the add form

The Configuration Menu is opened with the TR7 logo at the bottom left; Add is clicked on the Certificates & PKI → SSL/TLS Certificates screen (how to add). The form opens as a closable Add tab above the list.

2

Adım 2 Select the name and the type

The Certificate Name is entered; the name must be unique on the device. The Type field comes as ACME.SH by default (the other options are Manual, PFX, Internal CA); Manual is selected. The type cannot be changed after the record is created.

3

Adım 3 Enter the certificate

The certificate is pasted into the Certificate Content field or the file is dragged. If the intermediate certificates are also pasted into the same field after the certificate (fullchain), the additional blocks are used as the chain.

4

Adım 4 Enter the private key

The private key in PEM format is pasted into the Key Content field or the file is dragged. If the key is password-protected, the password is entered in the Password field; for a key without a password, the field is left empty.

5

Adım 5 Add the chain (if needed)

If the intermediate certificate was not added in step 3, the Intermediate Cert. Content field is used, and for the root certificate, the Root Cert. Content field. Both fields come as Disabled by default; when Without Profile is selected, PEM content is pasted into the box that opens, and when Use Profiles is selected, records on the Certificate Authorities (CA) screen are selected (How do I add the intermediate certificate chain?).

6

Adım 6 Set the download permission

Allow Download is off by default. If it is turned on, the certificate can be downloaded with the download icon in the list as a password-protected PFX together with its key and chain; if the key is not to leave the device, it is left off.

7

Adım 7 Save

Add at the bottom of the form is clicked; the certificate is added to the list. While there is a field with an invalid format, the button is disabled; unrecognized certificate content or a key that cannot be decoded is rejected with an error message while saving. In a cluster setup, the record is also sent to the peer device with the default auto-sync; if Manual Sync Mode is on, it is sent to the peer device manually.

After the certificate is added, for it to be used, it is selected in the Certificate field of the vService (Can I attach more than one certificate to a vService; how is the right certificate selected (SNI)?).

Verification

1Record and chainTR7 side

The certificate row in the list is clicked; the Chain tab of the preview that opens on the right is checked. The circle in the Valid Until column shows the status of the validity period.

ExpectedTrust chain is complete

The orange "Missing intermediate certificate — required issuer" message shows the signer of the missing link by name. If the named one is an intermediate CA, the field in step 5 is filled in or Suggest Completion in the Chain tab is used; if it is a root CA, only the root certificate is missing from the record, and clients take the root from their own trust store.

2Presented certificateClient side

After the certificate is selected on the vService and saved, the chain is queried from the client.

Command: openssl s_client -connect 203.0.113.10:443 -servername www.example.com -showcerts

ExpectedVerify return code: 0 (ok)

Method 2: PFX

• How it works The PKCS#12 file is imported with its password; the certificate, the key and the CA certificates in the file are parsed automatically (the self-signed ones as root, the others as intermediate certificates).
• Where it is openedCertificates & PKI → SSL/TLS Certificates → Add → Type = PFX
• Requirement A file with the .pfx extension and its password
• vService type HTTP, L7 TCP (encrypted frontend)

Step-by-Step Configuration

1

Adım 1 Open the add form

The Configuration Menu is opened with the TR7 logo at the bottom left; on the Certificates & PKI → SSL/TLS Certificates screen, Add is clicked (how to add).

2

Adım 2 Select the name and the type

The Certificate Name is entered; PFX is selected in the Type field.

3

Adım 3 Select the file

The file is selected from the PFX File field. The file picker lists the .pfx extension; since a PKCS#12 file with the .p12 extension has the same format, it is renamed to .pfx and selected.

4

Adım 4 Enter the password

The password of the file is entered in the Password field. The field does not appear marked as required in the form; however, without the password, the file cannot be decrypted and the record is rejected.

5

Adım 5 Complete the chain (if needed)

If there is no intermediate or root certificate in the file, they are added by selecting Without Profile or Use Profiles in the Intermediate Cert. Content and Root Cert. Content fields. If there is a chain in the file, the chain in the file is written to the record.

6

Adım 6 Set the download permission

Allow Download is off by default; if the certificate needs to be downloaded again as a PFX, it is turned on.

7

Adım 7 Save

Add at the bottom of the form is clicked; the certificate is added to the list. If the password is wrong or the file cannot be decrypted, the record is rejected with an error message. In a cluster setup, the record is also sent to the peer device with the default auto-sync; if Manual Sync Mode is on, it is sent to the peer device manually.

Verification

1Record and chainTR7 side

The certificate row in the list is clicked; the CN, the validity and the domain names are seen in the Details tab of the preview, and the chain in the Chain tab.

ExpectedTrust chain is complete

2Presented certificateClient side

After the certificate is selected on the vService and saved, the chain is queried from the client.

Command: openssl s_client -connect 203.0.113.10:443 -servername www.example.com -showcerts

ExpectedVerify return code: 0 (ok)

Common Mistakes

• Leaving the Type field on ACME.SH. The form opens with the ACME.SH type; for uploading from a file, Manual or PFX is selected. Since the type cannot be changed after saving, a record created with the wrong type is deleted and added again.
• Pasting a key that does not match the certificate in Manual. The match between the certificate and the key is not checked while saving; the mismatch comes out as an error while the configuration is applied. The match is checked before uploading (the openssl x509 -noout -pubkey and openssl pkey -pubout outputs of the two files must be the same).
• Trying to upload a PFX without a password. The PFX file must have been exported with a password; without the password being entered, the record is rejected.
• Giving the key in DER format or as an Ed25519 key. Key Content accepts only an RSA or EC key in PEM format; a DER key is converted to PEM with openssl pkey -in key.der -inform DER -out key.pem.
• Not adding the intermediate certificate. Even though browsers mostly show no problem, some clients and mobile applications cannot complete the chain; the Chain tab in the preview is checked.
• Adding the certificate and not selecting it on the vService. The record is not used on its own; it is selected in the Certificate field of the vService and the vService is saved.

How it is done in the documentation

• SSL/TLS Certificates · How to Add?
• SSL/TLS Certificates · Manual
• SSL/TLS Certificates · PFX
• SSL/TLS Certificates · Chain Tab

Related questions

• How do I add the intermediate certificate chain?
• Can I attach more than one certificate to a vService; how is the right certificate selected (SNI)?
• What does the vService do if the certificate I uploaded has an error?