TrueNASTrueNAS Nightly Development Documentation
This content follows experimental nightly development software. Pre-release software is intended for testing purposes only.
Use the Product and Version selectors above to view content specific to a stable software release.

Certificates Screens

The Certificates widget on the Credentials > Certificates screen displays certificates added to TrueNAS and allows you to add new certificates, or download, delete, or edit the name of an existing certificate. Each TrueNAS has an internal, self-signed certificate that enables encrypted access to the web interface.

CertificatesWidget

The download icon downloads the certificate to your server.

delete deletes the certificate from your server.

Each certificate listed on the widget is a link that opens the Edit Certificate screen.

Add opens the Add Certificate wizard.

Add Certificate Wizard

The Add Certificate wizard screens guide users through configuring a new certificate on TrueNAS. The wizard has five different configuration screens, one for each step in the certificate configuration process:

1 Identifier and Type

2 Certificate Options

3 Certificate Subject

4 Extra Constraints

5 Confirm Options

Before you create a new certificate, configure a new CA if you do not already have one on your system. Creating an internal certificate requires a CA to exist on the system.
Many of the settings in the Add Certificate wizard are the same as those in the Add CA and Add Certificate Signing Request wizards.

Identifier and Type Options

The Identifier and Type options specify the certificate name and choose whether to use it for internal or local systems or import an existing certificate.
Users can also select a predefined certificate extension from the Profiles dropdown list.

Click Here for More Information

The selection in Type changes setting options on this screen, the Certificate Options and Extra Constraints screens, and determines if the Certificate Subject screen displays at all.

AddCertificateIdentifierAndTypeInternalCert

SettingDescription
NameRequired. Enter a descriptive identifier for this certificate.
TypeSelect the certificate type from the dropdown list. Internal Certificate uses system-managed CAs for certificate issuance. Import Certificate allows you to import an existing certificate onto the system. Import Certificate removes the Profiles field and changes other screens and fields displayed on other wizard screens.
ProfileSelect a predefined certificate extension. Options are HTTPS RSA Certificate or HTTPS ECC Certificate. Choose a profile that best matches your certificate usage scenario.

Certificate Options

Certificate Options settings choose the signing certificate authority (CSR), the type of private key type to use (as well as the number of bits in the key used by the cryptographic algorithm), the cryptographic algorithm the certificate uses, and how many days the certificate authority lasts.

The Certificate Options settings change based on the selection in Type on the Identifier and Type screen.

Certificate Options - Internal Certificate

The Key Type selection changes fields displayed. RSA is the default setting in Key Type. The Signing Certificate Authority field requires you to have a CA already configured on your system. If you do not have a Certificate Authority (CA) configured on your system, exit the Add Certificate wizard and add the required CA.

Click Here for More Information

AddCertificateCertificateOptions

SettingDescription
Signing Certificate AuthorityRequired. Select a previously imported or created CA from the dropdown list.
Key TypeRequired. Select an option (RSA or EC) from the dropdown list. See why is elliptic curve cryptography not widely used, compared to RSA? for more information about key types. Selecting EC displays the EC Curve field and removes the Key Length field.
Key LengthRequired. Displays when Key Type is set to RSA. The number of bits in the key used by the cryptographic algorithm. For security reasons, a minimum key length of 2048 is recommended.
EC CurveDisplays when Key Type is set to EC. Select the Brainpool or SECP curve that fits your scenario. Brainpool curves can be more secure than SECP curves but SECP curves can be faster. Options are BrainpoolP512R1, BrainpoolP384R1, BrainpoolP256R1, SECP256R1, SECP384R1, SECP521R1, and ed25519. See Elliptic Curve performance: NIST vs Brainpool for more information.
Digest AlgorithmRequired. Select the cryptographic algorithm to use from the dropdown list. Options are SHA1, SHA224, SHA256, SHA384 or SHA512. Only change the default SHA256 if the organization requires a different algorithm.
LifetimeRequired. Enter the number of days for the lifetime of the CA.

Certificate Options - Import Certificate

Setting Type on the Identifier and Type screen to Import Certificate changes the options displayed on the Certificate Options configuration screen.

Click Here for More Information

AAddCertificateImportCertificateOptions

SettingDescription
CertificateRequired. Paste the certificate for the CA into this field.
CSR exists on this systemSelect if importing a certificate for which a CSR exists on this system. Displays the Certificate Signing Request dropdown.
Certificate Signing RequestSelect the existing CSR from the dropdown list.
Private KeyRequired. Paste the private key associated with the certificate when available. Provide a key at least 1024 bits long.
PassphraseEnter the passphrase for the private key.
Confirm PassphraseRe-enter the passphrase for the private key.

Certificate Subject Options

The Certificate Subject step lets users define the location, name, and email of the organization using the certificate.
Users can also enter the system fully-qualified hostname (FQDN) and any additional domains for multi-domain support.

The Certificate Subject screen does not display when Type on Internal Certificate is set to Import Certificate.

Click Here for More Information

AddCertificateCertifcateSubject

SettingDescription
CountryRequired. Select the country of the organization from the dropdown list.
StateRequired. Enter the state or province of the organization.
LocalityRequired. Enter the location of the organization. For example, the city.
OrganizationRequired. Enter the name of the company or organization.
Organizational UnitEnter the organizational unit of the entity.
EmailRequired. Enter the email address of the person responsible for the CA.
Common NameEnter the fully qualified host name (FQHN) of the system. This name must be unique within a certificate chain.
Subject Alternate NamesRequired. Enter additional domains to secure for multi-domain support. Separate each domain by pressing Enter. For example, if the primary domain is example.com, entering www.example.com* secures both addresses.

Extra Constraints Options

The Extra Constraints step contains certificate extension options.

  • Basic Constraints limits the path length for a certificate chain.
  • Authority Key Identifier provides a means of identifying the public key corresponding to the private key used to sign a certificate.
  • Key Usage defines the purpose of the public key contained in a certificate.
  • Extended Key Usage further refines key usage extensions.

The Extra Constraints settings change based on the selection in Type on the Identifier and Type screen.

Extra Constraints - Internal Certificate

After selecting Basic Constraints, Authority Key Identifier, Extended Key Usage, or Key Usage, each displays more settings that the option needs.

Click Here for More Information

AddCertificateExtraConstraintsInternalCert

SettingDescription
Basic ConstraintsSelect to activate this extension to identify whether the certificate subject is a CA and the maximum depth of valid certification paths that include this certificate. Options are CA or Critical Extension. Selecting Basic Constraints displays the Path Length and Basic Constraints Config fields.
Path LengthDisplays after selecting Basic Constraints. Enter a value of 0 or greater to set how many non-self-issued intermediate certificates can follow this certificate in a valid certification path. Entering 0 allows a single additional certificate to follow in the certificate path. Value cannot be less than 0.
Basic Constraints ConfigSelect the option to specify whether to use the certificate for a Certificate Authority and whether this extension is critical. Clients must recognize critical extensions to prevent rejection. Web certificates typically require you to disable CA and enable Critical Extension in Basic Constraints.
Authority Key IdentifierSelect to activate this extension. The authority key identifier extension provides a means of identifying the public key corresponding to the private key used to sign a certificate. This extension is used where the issuer has multiple signing keys (either due to multiple concurrent key pairs or due to changeover). The identification might be based on either the key identifier (the subject key identifier in the issuer certificate) or on the issuer name and serial number. See RFC 3280, section 4.2.1.1 for more information. Displays the Authority Key Config field.
Authority Key ConfigDisplays after selecting Authority Key Identifier. Select the option to specify whether the issued certificate should include authority key identifier information and whether the extension is critical. Critical extension must be recognized by the client or be rejected. Options are Authority Cert Issuer and or Critical Extension. Multiple selections display separated by a comma (,).
Extended Key UsageSelect to activate this certificate extension. The Extended Key Usage extension identifies and limits valid uses for this certificate, such as client authentication or server authentication. See RFC 3280, section 4.2.1.13 for details. Displays the Usages field.
UsagesDisplays after selecting Extended Key Usage. Select the option to identify the purpose of this public key from the dropdown list. Typically used for the end entity certificates. You can select multiple usages that display separated by a comma (,). Options are ANY_EXTENDED_KEY_USAGE, CERTIFICATE_TRANSPARENCY, CLIENT_AUTH, CODE_SIGNING, EMAIL_PROTECTION, IPSEC_IKE, KERBEROS_PKINIT_KDC, OCSP_SIGNING, SERVER_AUTH, SMARTCARD_LOGON or TIME_STAMPING. Do not mark this extension critical when set to ANY_EXTENDED_KEY_USAGE. The purpose of the certificate must be consistent with both extensions when using both Extended Key Usage and Key Usage extensions. See [RFC 3280, section 4.2.1.13 for more details.
Critical ExtensionSelect to identify this extension as critical for the certificate. The certificate-using system must recognize the critical extensions to prevent this certificate from being rejected. The certificate-using system can ignore extensions identified as not critical and still approve the certificate.
Key UsageSelect to activate this certificate extension. The key usage extension defines the purpose (e.g., encipherment, signature, certificate signing) of the key contained in the certificate. The usage restriction might be employed when a key that can be used for more than one operation is to be restricted. For example, when an RSA key should be used only to verify signatures on objects other than public key certificates and CRLs, the Digital Signature bits are asserted. Likewise, when an RSA key should be used only for key management, the Key Encipherment bit is asserted. See RFC 3280, section 4.2.1.3 for more information. Displays the Key Usage Config field.
Key Usage ConfigDisplays after selecting Extended Key Usage or Key Usage. Select the option that specifies valid key usages for this certificate. Options are Digital Signature, Content Commitment, Key Encipherment, Data Encipherment, Key Agreement, Key Cert Sign, CRL Sign, Encipher Only, Decipher Only or Critical Extension. Web certificates typically need at least Digital Signature and possibly Key Encipherment or Key Agreement, while other applications might need other usages.

Import Certificate Options

When Type on Identifier and Type is set to Import Certificate the Import Certificate options screen displays.

Click Here for More Information

AddCertificateImportOptions

SettingDescription
CertificateRequired. Paste the certificate for the CA into this field.
CSR exists on this systemSelect if importing a certificate for which a CSR exists on this system. Displays the Certificate Signing Request dropdown.
Certificate Signing RequestSelect an existing CSR from the dropdown list.
Private KeyRequired. Paste the private key associated with the certificate when available. Provide a key at least 1024 bits long.
PassphraseEnter the passphrase for the private key.
Confirm PassphraseRe-enter the passphrase for the private key.

Confirm Options

The final step screen is the Confirm Options that displays the certificate Type, Key Type, Key Length, Digest Algorithm, Lifetime, Country, and any configured Usages.

AddCertificateConfirmOptions

Save adds the certificate to TrueNAS. Back returns to previous screens to make changes before you save. Next advances to the next screen in the sequence to return to Confirm Options.

Edit Certificate Screen

The certificate listed on the Certificates widget is a link that opens the Edit Certificate screen.

EditCertificateScreen

The Edit Certificate screen displays the fixed Subject settings, the type, path, and other details about that certificate that are not editable. You can enter an alphanumeric name for the certificate in Identifier if you want to rename the certificate. You can use underscore (_) and or dash (-) characters in the name.

View/Download Certificate opens a window with the certificate string. Use the assignment clipboard icon to copy the certificate to the clipboard or Download to download the certificate to your server. Keep the certificate in a secure area where you can back up and save it.

View/Download Key opens a window with the certificate private key. Use the assignment clipboard icon to copy the public key to the clipboard or Download to download the key to your server. Keep the private key in a secure area where you can back up and save it.