Conditions

The dataset contains a set of conditions that define specific checks to be performed in certain cases. Multiple conditions can be combined by using logical operators AND, OR, parenthesis (, ) and the negation symbol !. In case of numeric values, the comparison operators >, >=, <, <=, == and != can be used.

Important

The conditions can be used to define additional notes or to dynamically change the requirement level of an element. Each condition MUST return either True or False.

Tip

These conditions can be evaluated automatically by using the dataset combined with TLSAssistant.

List of conditions

The conditions that can be currently verified are:

• "CA X" - can be used to perform additional checks on the certificate authority that issued the certificate. The value of X can be:

  1. "count" - Returns the number of CAs which issued the certificate. Example: "CA count > 1";
  2. "publicly trusted" - returns True if the CA is publicly trusted. The check is performed using the TrustedCerts field from testssl.sh. Example: "CA publicly trusted";

• "CERTIFICATESIGNATURE X"/"CERTSIG X" - can be used to check whether the certificate signature algorithm X is enabled or not. For a list of all the possible values, please refer to the "Certificate Signature.md" file. Example: "CERTSIG rsa";

• "CHECK_AKI" - checks if the Authority Key Identifier is compliant with the requirement "Same as subject key identifier in issuing CA certificate; Prohibited: Issuer DN, Serial Number tuple" found in the NIST guidelines;

• "CHECK_DN" - checks if the Distinguished Name of the certificate is compliant with the requirement "A single value should be encoded in each Relative Distinguished Name (RDN) (the single values that compose the DN). All attributes that are of DirectoryString type should be encoded as a PrintableString.". Example: "CHECK_DN Issuer Distinguished Name - der" or "CHECK_DN Subject Distinguished Name - der";

• "CHECK_KEY_TYPE X" - checks if the key type defined in a certificate is compliant with the requirement "The key type should be consistent with the signature algorithm". Example: "CHECK_KEY_TYPE rsa";

• "CHECK_SAME_KEYUSAGE" - checks if the "KeyUsage" extension's values are consistent with the "extendedKeyUsage"' extension's values.

• "CIPHER X" - same as CertificateSignature but for the cipher suites;

• "DISABLE_IF X" - always returns True. If the result of the conditions evaluation is X, the element is disabled. Example: "CHECK_AKI AND DISABLE_IF False";

• "EXTENSION" - same as CertificateSignature but for the TLS extensions;

• "GROUPS" - same as CertificateSignature but for the groups;

• "HASH" - same as CertificateSignature but for the hash algorithms;

• "KEY" - same as CertificateSignature but for the key lengths;

• "NOTE_ALWAYS" - it always returns True. A note is always added to the report for the given element. Example: "NOTE_ALWAYS this is a note";

• "NOTE_DISABLED" - same as NOTE_ALWAYS but only if the element is disabled;

• "NOTE_ENABLED" - same as NOTE_ALWAYS but only if the element is enabled;

• "NOTE_FALSE" - same as NOTE_ALWAYS but only if the result of the conditions evaluation is False;

• "NOTE_TRUE" - same as NOTE_ALWAYS but only if the result of the conditions evaluation is True;

• "PROTOCOLS X" - checks if the given protocol version is enabled. Example: "PROTOCOLS TLS 1.2",

• "THIS or Category Element" - returns True if the current element (the entry in the first column of the row containing this condition) or the alternative element (Element) is enabled. Example: "THIS or PROTOCOLS TLS 1.2". Multiple elements can be checked at the same time by using ; as a separator e.g. CertificateSignature rsa;ecdsa. If any of the elements is enabled and the final result of the condition is True, all the alternative elements are considered as if they are enabled;

• "TRANSPARENCY X" - checks the type of certificate transparency used by the certificate. The possible values for X are:

  • "certificate extension"
  • "OCSP extension"
  • "TLS extension"

Tip

For more details please refer to Mozilla Docs

• "VALUE Category value comparison ToCompare" - used to check the value of a given element.

  • Category - name of the Markdown file containing the element to compare;
    • value - value to be checked;
    • comparison - comparison operator. The possible comparison operators are: ==, !=, >, >=, <, <=;
    • ToCompare - indicates which value to check against. Example: "VALUE Certificate 2 == X.509 version"

Important

If the target element is contained inside a dictionary, the syntax [field][subfield] can be used together with the in, not in operators. Example: VALUE Certificate * in [Issuer Distinguished Name][CN];

• "VERIFY_SCSV" - checks if the server offers the fallback_SCSV cipher suite;

• "VLP X" - checks if any TLS version up to v1.2 (included) is enabled. If so, it checks if X is True or False. If X is False, the element's level becomes "MUST NOT". Otherwise, it checks if the result of the version check is consistent with X. Example: "VLP False";

• "YEAR X" - returns True if the execution date is before 31-dec-X (included). If X ends with “+” then the condition is always considered to be True;

• "YEARS operator X" - checks if the certificate is valid for a given range of years. Example: "YEARS <= 3";

Adding a new condition to TLSAssistant

To automate the check of a new condition, you have to:

• write the function with the fn(**kwargs): bool signature;
• add the new function as a method to the CustomFunctions class, found in modules/compliance/compliance_base.py;
• (optional) define an alias for the function in the configs/compliance/condition instructions.json file.