HORIZON HASKELLDocslts/ghc-9.10.xc74966e2026-09-27Search names, modules, packages, or :: a typeCtrl K

GHC 9.10.3 · lts/ghc-9.10.x · c74966e · 2026-09-27

Modulex509-validation-1.6.12Haskell2010

Data.X509.Validation

X.509 Certificate checks and validations routines

Follows RFC5280 / RFC6818

  • 13 types
  • 10 values
typetype ServiceID = (HostName, ByteString)
#

identification of the connection consisting of the fully qualified host name (e.g. www.example.com) and an optional suffix.

The suffix is not used by the validation process, but is used by the optional cache to identity certificate per service on a specific host. For example, one might have a different certificate on 2 differents ports (443 and 995) for the same host.

for TCP connection, it's recommended to use: :port, or :service for the suffix.

Failed validation types

2 declarations
datadata FailedReason
#

Possible reason of certificate and chain failure.

The values InvalidName and InvalidWildcard are internal-only and are never returned by the validation functions. NameMismatch is returned instead.

Constructors

Instances2Eq, Show

Validation configuration types

4 declarations
datadata ValidationChecks
#

A set of checks to activate or parametrize to perform on certificates.

It's recommended to use defaultChecks to create the structure, to better cope with future changes or expansion of the structure.

Constructors

  • ValidationChecks
    • checkTimeValidity :: Bool

      check time validity of every certificate in the chain. the make sure that current time is between each validity bounds in the certificate

    • checkAtTime :: Maybe DateTime

      The time when the validity check happens. When set to Nothing, the current time will be used

    • checkStrictOrdering :: Bool

      Check that no certificate is included that shouldn't be included. unfortunately despite the specification violation, a lots of real world server serves useless and usually old certificates that are not relevant to the certificate sent, in their chain.

    • checkCAConstraints :: Bool

      Check that signing certificate got the CA basic constraint. this is absolutely not recommended to turn it off.

    • checkExhaustive :: Bool

      Check the whole certificate chain without stopping at the first failure. Allow gathering a exhaustive list of failure reasons. if this is turn off, it's absolutely not safe to ignore a failed reason even it doesn't look serious (e.g. Expired) as other more serious checks would not have been performed.

    • checkLeafV3 :: Bool

      Check that the leaf certificate is version 3. If disable, version 2 certificate is authorized in leaf position and key usage cannot be checked.

    • checkLeafKeyUsage :: [ExtKeyUsageFlag]

      Check that the leaf certificate is authorized to be used for certain usage. If set to empty list no check are performed, otherwise all the flags is the list need to exists in the key usage extension. If the extension is not present, the check will pass and behave as if the certificate key is not restricted to any specific usage.

    • checkLeafKeyPurpose :: [ExtKeyUsagePurpose]

      Check that the leaf certificate is authorized to be used for certain purpose. If set to empty list no check are performed, otherwise all the flags is the list need to exists in the extended key usage extension if present. If the extension is not present, then the check will pass and behave as if the certificate is not restricted to any specific purpose.

    • checkFQHN :: Bool

      Check the top certificate names matching the fully qualified hostname (FQHN). it's not recommended to turn this check off, if no other name checks are performed.

Instances3Eq, Show, Default
datadata ValidationHooks
#

A set of hooks to manipulate the way the verification works.

BEWARE, it's easy to change behavior leading to compromised security.

Constructors

Instances1Default
valuedefaultChecks :: ValidationChecks
#

Default checks to perform

The default checks are: * Each certificate time is valid * CA constraints is enforced for signing certificate * Leaf certificate is X.509 v3 * Check that the FQHN match

Validation

4 declarations
valuevalidate
  1. :: HashALG

    the hash algorithm we want to use for hashing the leaf certificate

  2. -> ValidationHooks

    Hooks to use

  3. -> ValidationChecks

    Checks to do

  4. -> CertificateStore

    The trusted certificate store for CA

  5. -> ValidationCache

    the validation cache callbacks

  6. -> ServiceID

    identification of the connection

  7. -> CertificateChain

    the certificate chain we want to validate

  8. -> IO [FailedReason]

    the return failed reasons (empty list is no failure)

#

X509 validation

the function first interrogate the cache and if the validation fail, proper verification is done. If the verification pass, the add to cache callback is called.

Cache

6 declarations
valueexceptionValidationCache :: [(ServiceID, Fingerprint)] -> ValidationCache
#

create a simple constant cache that list exceptions to the certification validation. Typically this is use to allow self-signed certificates for specific use, with out-of-bounds user checks.

No fingerprints will be added after the instance is created.

The underlying structure for the check is kept as a list, as usually the exception list will be short, but when the list go above a dozen exceptions it's recommended to use another cache mechanism with a faster lookup mechanism (hashtable, map, etc).

Note that only one fingerprint is allowed per ServiceID, for other use, another cache mechanism need to be use.

valuetofuValidationCache
  1. :: [(ServiceID, Fingerprint)]

    a list of exceptions

  2. -> IO ValidationCache
#

Trust on first use (TOFU) cache with an optional list of exceptions

this is similar to the exceptionCache, except that after each succesfull validation it does add the fingerprint to the database. This prevent any further modification of the fingerprint for the remaining

Signature verification

4 declarations
datadata SignatureVerification
#

A set of possible return from signature verification.

When SignatureFailed is return, the signature shouldn't be accepted.

Other values are only useful to differentiate the failure reason, but are all equivalent to failure.

Constructors

Instances2Eq, Show