14 Integrity Checking

8.12

14 Integrity Checking🔗ℹ

package: denxi

denxi/integrity reprovides denxi/integrity/base, and is meant for use as a high-level interface to the integrity checking subsystem.

14.1 High-level Integrity Operations🔗ℹ

procedure
(load-builtin-chf name [fail-thunk]) → any
name : symbol?
fail-thunk : (-> any)
= (lambda () (raise ($chf-unavailable name)))

Returns a built-in chf-impl/c procedure, or (fail-thunk) if no implementation is available.

The output of this function may change across systems.

procedure
(fetch-digest intinfo exhaust) → any/c
intinfo : well-formed-integrity?
exhaust : exhaust/c

Returns the unencoded bytes of a message digest from (integrity-digest intinfo), or a value created by applying exhaust when a source is exhausted.

No more than MAX_EXPECTED_DIGEST_LENGTH will be copied from the source.

procedure
(make-sourced-digest variant
chf-name
[ exhaust]) → bytes?
  variant : source-variant?
  chf-name : symbol?
  exhaust : exhaust/c = raise

Like make-digest, except the digest is produced using bytes tapped from variant using fetch.

procedure
(lock-integrity [ #:digest-budget digest-budget]
to-lock
[ exhaust])
→ well-formed-integrity?
  digest-budget : budget/c = MAX_EXPECTED_DIGEST_LENGTH
  to-lock : well-formed-integrity?
  exhaust : exhaust/c = raise

Returns a new integrity instance L.

Or, if the integrity information uses a source for the digest and that source is exhausted, returns exhaust applied to the contextual failure value.

(raw-integrity? L) is #t if a new digest can be created using no more than digest-budget bytes of overhead in the content. Otherwise, L is eq? to to-lock.

procedure
(make-trusted-integrity source [chf]) → raw-integrity?
source : source-variant?
chf : symbol? = (get-default-chf)

Returns integrity information based on source’s bytes. No safety limits are places on bytes drawn from the source, so this procedure should only be used on trusted data.

value
sourced-integrity? : flat-contract?
= (struct/c integrity symbol? source?)
value
well-formed-integrity? : flat-contract?
= (or/c raw-integrity? sourced-integrity?)
value
malformed-integrity? : flat-contract?
= (not/c well-formed-integrity?)

Duck typing contracts for integrity instances.

14.2 Integrity Settings🔗ℹ

setting
DENXI_TRUST_BAD_DIGEST : boolean? = #f

CLI Flags: -Y/--trust-any-digest/--DENXI_TRUST_BAD_DIGEST

Highly dangerous. When true, disable integrity checking.

setting
DENXI_TRUST_CHFS : (listof symbol?) = ()

CLI Flags: +c/++trust-chf/--DENXI_TRUST_CHFS/++trust-message-digest-algorithm

A list of possible canonical names for chfs to trust when checking data integrity.

14.3 Integrity-based Trust🔗ℹ

procedure
(bind-trust-list trusted [chfs]) → (-> input-port? boolean?)
trusted : (listof integrity?)
chfs : (listof chf?) = (current-chfs)

Returns a procedure P.

(P input-port) is #t if it can reproduce an element of trusted using chfs.

make-user-chf-trust-predicate is the fastest way to check if a user trusts a CHF.

procedure
(make-user-chf-trust-predicate) → (-> symbol? boolean?)

Returns (chf-bind-trust configured), where configured combines existing values in (current-chfs) with the built-in implementations found in (DENXI_TRUST_CHFS).

procedure
(build-builtin-chf-trust trust-chfs) → (listof chf?)
trust-chfs : (listof symbol?)

Returns a value suitable for use in current-chfs.

The implementations of the given CHFs come from a bundled C library, any input symbols must appear in (integrity-ffi-get-c-chfs!).

14.4 Prototyping Integrity Checks🔗ℹ

value
snake-oil-chf : chf? = (chf 'sha1 #px"^(?i:sha-?1)$" sha1-bytes)

A CHF meant for use in tests, low-security contexts, or when compatibility is more important than security.

Do not use in production if you can avoid doing so.

procedure
(call-with-snake-oil-chf-trust thunk) → any
thunk : (-> any)

Call thunk in tail position. While control is in the thunk, (current-chfs) is (list snake-oil-chf).

14.5 Integrity Checking Primitives🔗ℹ

(require denxi/integrity/base)

package: denxi

Unlike denxi/integrity, denxi/integrity/base provides fundamental definitions for integrity checking.

struct
(struct integrity (chf-symbol digest))
chf-symbol : any/c
digest : any/c

Represents integrity information for content. An instance passes check-integrity if data processed by the CHF named by chf-symbol maps to digest. An instance does not indicate which implementation of a CHF to use.

The fields may be any value to address particular scenarios. Use raw-integrity?, well-formed-integrity?, malformed-integrity?, and sourced-integrity? to classify instances.

value
raw-integrity? : flat-contract? = (struct/c symbol? bytes?)

Returns #t if the argument is an instance of integrity has a symbolic CHF name and an unencoded digest available in the instance itself.

This contract does not validate the content of the fields, but an instance that passes this contract is suitable for use with check-integrity.

Allowing #f in the arguments is intentional due to the possibility of missing information.

procedure
(check-integrity #:trust-bad-digest trust-bad-digest
trust-chf?
int
expected-digest) → symbol?
  trust-bad-digest : any/c
  trust-chf? : (-> symbol? any/c)
  int : (or/c #f integrity?)
  expected-digest : (or/c #f bytes?)

Returns

'digests-match if the digests are equal? and the user trusts the CHF.
'digests-differ if the digests are not equal?, but the user trusts the CHF.
'skip if trust-bad-digest is a true value.
'blocked-chf if the user does not trust the CHF.
'malformed-input if (raw-integrity? int) is #f.

value
integrity-check-passed? : predicate/c

Returns #t if the argument is in the range of check-integrity, and you can interpret it as permission to proceed in a larger procedure.

value
MAX_EXPECTED_DIGEST_LENGTH : exact-positive-integer?

The maximum number of bytes expected from any message digest.

procedure
(make-digest in [chf-name]) → bytes?
in : (or/c bytes? path-string? input-port?)
chf-name : (or/c #f symbol?) = (get-default-chf)

Returns the unencoded bytes for a message digest computed using chf, using bytes drawn from a given input port.

If in is a path string, it is coerced to an input port using call-with-input-file*.

If in is a byte string, it is coerced to an input port using open-input-bytes.

If chf-name is #f, or no CHF implementation is available for it, make-digest will raise ($chf-unavailable chf-name).

14.5.1 Cryptographic Hash Functions🔗ℹ

struct
(struct chf (canonical-name alias-pattern implementation))
  canonical-name : symbol?
  alias-pattern : regexp?
  implementation : chf-impl/c

chf represents an implementation of a cryptographic hash function, and the many names it might go by.

canonical-name represents the primary name of the CHF in the context of the running process. alias-pattern captures variations of the canonical name. implementation produces a digest using the CHF’s specification.

An instance might encode SHA-1 as follows:

(chf 'sha1 #px"^(?i:sha[-_ ]?1)$" sha1-bytes) ; openssl/sha1, file/sha1

The name fields capture possible variation where CHF symbols appear, such as in integrity instances.

(integrity 'SHA1 #"...")
(integrity 'SHA-1 #"...")
(integrity 'Sha_1 #"...")
(integrity 'sha1 #"...") ; <- canonical
(integrity 'sha-1 #"...")

chf implements prop:procedure, such that applying the instance to arguments will forward those arguments to the procedure bound to the implementation field.

chf implements gen:equal+hash, such that two instances are equal? if their canonical names are eq?.

struct
(struct $chf-unavailable (name)
#:prefab)
name : symbol?

The process could not find an instance of chf using name.

value
chf-impl/c : chaperone-contract? = (-> input-port? bytes?)

Represents a high level implementation of a cryptographic hash function.

The procedure must return a byte string representing an unencoded digest.

The first argument is an input port that produces bytes from an arbitrary source, such as an HTTP response or a file. The output digest must represent all bytes drawn from the port.

value
current-chfs : (parameter/c (listof chf?))

The CHFs trusted by the user for digest creation.

Defaults to null, which disables digest creation and integrity checks.

procedure
(chf-bind-trust [chfs]) → predicate/c
chfs : (listof chf?) = (current-chfs)

Returns a predicate P, such that (P v) is #t if v is a symbol and (chf-find chfs v) returns a non-#f value.

procedure
(chf-fold-trust select-implementation
trusted-chf-names) → (listof chf?)
select-implementation : (-> symbol? chf-impl/c)
trusted-chf-names : (listof symbol?)

Returns a list of chf instances based on trusted names.

For each name in trusted-chf-names, the output list will contain:

(chf name
(pregexp (format "^(?i:~a)$" name))
(select-implementation name))

procedure
(get-default-chf [trusted]) → (or/c #f symbol?)
trusted : (listof chf?) = (current-chfs)

Returns the canonical name of the first element in trusted, or #f if trusted is empty.

procedure
(chf-find haystack [needle]) → (or/c #f chf?)
haystack : (listof chf?)
needle : symbol? = (get-default-chf haystack)

Returns the first chf instance in haystack where needle either exactly matches the canonical name of the instance, or matches its alias pattern.

Returns #f if no instance meets the criteria.

14.6 Integrity FFI🔗ℹ

(require denxi/integrity/ffi)

package: denxi

denxi/integrity/ffi is a private module that defines FFI bindings for a bundled library dedicated to integrity checking.

procedure
(integrity-ffi-available?!) → boolean?

Returns #t if the FFI dynamically linked against the bundled foreign library for the purposes of integrity checking operations.

value
integrity-ffi-chf-available?! : predicate/c

Returns #t if the input argument is a symbol, and can be used to load a CHF implemented in the foreign library.

procedure
(integrity-ffi-get-c-chfs!) → (or/c #f (listof symbol?))

Returns a list of symbols that suitable for use with other functions that accept symbols as inputs.

procedure
(integrity-ffi-get-default-chf-index!)
→ (or/c #f exact-nonnegative-integer?)

Returns a foreign value representing the index of (integrity-ffi-get-supported-chfs!) suggested for use as a default CHF.

Do not confuse this index with get-default-chf. The default is a suggestion by the library among its own implementations, and does not apply as a default for the runtime unless it is installed using current-chfs.

procedure
(integrity-ffi-get-load-chf!) → any/c

Returns a foreign function for loading a CHF implementation in the C runtime. In OpenSSL, the C runtime uses the default implementation provider.

procedure
(integrity-ffi-get-get-digest-size!) → any/c

Returns a foreign function used to report the expected size of a message digest from a given CHF implementation.

procedure
(integrity-ffi-get-make-digest!) → any/c

Returns a foreign function used to create a message digest using a CHF implementation.

procedure
(integrity-ffi-get-chf-count!)
→ (or/c #f exact-positive-integer?)

Returns a Racket positive integer, or #f on load failure.

The integer represents the number of CHFs supported by the C runtime, not the number of implementations available.

procedure
(integrity-ffi-get-supported-chfs!) → any/c

Returns a FFI value as a C string array. Each element represents the name of a CHF. There are (integrity-ffi-get-chf-count!) elements in the array.

14.6.1 Integrity Foreign Functions🔗ℹ

To be included.

1	Prerequisite Knowledge
2	Command Line Argument Parsers
3	Command Line Utilities
4	Command Line Flags
5	Packages
6	Package Definitions
7	Package Queries
8	Launchers
9	Subprograms
10	Artifacts
11	Messages
12	Package Inputs
13	Package Outputs
14	Integrity Checking
15	Signature Checking
16	Digs
17	Reader Extension
18	Sources
19	Versions
20	State
21	Settings
22	Formatting
23	URLs
24	Strings
25	Localization
26	Printer
27	Archives
28	System
29	Monads
30	Files
31	Cryptography
32	Ports
33	Security
34	Racket Module Operations
35	Codec
36	Notaries

14.1	High-level Integrity Operations
14.2	Integrity Settings
14.3	Integrity-based Trust
14.4	Prototyping Integrity Checks
14.5	Integrity Checking Primitives
14.6	Integrity FFI