15 Signature Checking

8.12

15 Signature Checking🔗ℹ

package: denxi

denxi/signature uses asymmetric cryptography to verify if a digest was signed by a private key. The quality of signature verification is therefore dependent on the quality of the CHF used to create the digest.

value
sourced-signature? : flat-contract?
value
well-formed-signature? : flat-contract?
= (or/c raw-signature? sourced-signature?)
value
malformed-signature? : flat-contract?
= (not/c well-formed-signature?)

Duck typing contracts for signature instances.

sourced-signature? returns #t if at least one of the fields of the instance is a source. This is unlike sourced-integrity?, which only checks if the digest field is a source.

procedure
(fetch-signature-payload src exhaust) → any/c
src : source-variant?
exhaust : exhaust/c

Like fetch, except transfer limits are capped to MAX_EXPECTED_SIGNATURE_PAYLOAD_LENGTH and no transfer status information is reported. When the source has been successfully tapped, the return value is a byte string representing the full content of the requested resource.

In practice, the fetched bytes are expected to contain either a public key or a signature. In any case, the output is assumed to be compatible with the tool used to verify signatures.

procedure
(lock-signature [ #:public-key-budget public-key-budget
#:signature-budget signature-budget]
siginfo
exhaust)
→ signature?
   public-key-budget : budget/c
= MAX_EXPECTED_SIGNATURE_PAYLOAD_LENGTH
   signature-budget : budget/c
= MAX_EXPECTED_SIGNATURE_PAYLOAD_LENGTH
  siginfo : well-formed-signature?
  exhaust : exhaust/c

Like lock-integrity for signatures.

procedure
(make-snake-oil-signature digest [chf-name]) → raw-signature?
digest : bytes?
chf-name : symbol? = (get-default-chf)

Return a new signature using snake-oil-private-key.

Do not use in production code.

value
MAX_EXPECTED_SIGNATURE_PAYLOAD_LENGTH : budget/c

An estimated maximum number of bytes (chosen empirically) for a public key or signature.

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

Calls thunk in tail position. While control is in the thunk, (DENXI_TRUST_PUBLIC_KEYS) is (list snake-oil-public-key).

Implies call-with-snake-oil-chf-trust.

setting
DENXI_TRUST_ANY_PUBLIC_KEY : boolean? = #f

CLI Flags: --trust-any-pubkey/--DENXI_TRUST_ANY_PUBLIC_KEY

Dangerous. When true, trust any public key used to verify a signature.

setting
DENXI_TRUST_UNSIGNED : boolean? = #f

CLI Flags: -U/--trust-unsigned/--DENXI_TRUST_UNSIGNED

Dangerous. When true, trust any input that lacks a valid signature.

setting
DENXI_TRUST_BAD_SIGNATURE : boolean? = #f

CLI Flags: -T/--trust-bad-signature/--DENXI_TRUST_BAD_SIGNATURE

Dangerous. When true, trust any input that has a signature that does not match the input’s integrity information.

setting
DENXI_TRUST_PUBLIC_KEYS : (listof well-formed-integrity?) = ()

CLI Flags: +p/++trust-public-key/--DENXI_TRUST_PUBLIC_KEYS

A list of integrity information for public keys. Trusts public keys that can be used to reproduce an element of this list.

15.1 Signature Checking Primitives🔗ℹ

(require denxi/signature/base)

package: denxi

struct
(struct signature (public-key body)
    #:transparent)
  public-key : any/c
  body : any/c

Represents a claim that the bytes in body are a signature that can be verified using public-key.

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

A flat contract for signature claims that contain only unencoded bytes in memory.

value
make-signature/c : chaperone-contract?
=
(-> bytes?
    symbol?
    bytes?
    (or/c #f bytes?)
    bytes?)

A contract for procedures that return new signatures as unencoded bytes.

Arguments

A digest as unencoded bytes
A symbol representing the name of the cryptographic hash function used to create the first argument.
A private key of some encoding.
A password for the private key, or #f if there is no password.

value
verify-signature/c : chaperone-contract?
=
(-> bytes?
    symbol?
    bytes?
    bytes?
    boolean?)

A contract for procedures that return #t for trusted signatures.

Arguments

A digest as unencoded bytes
A symbol representing the name of the cryptographic hash function used to create the first argument.
A public key of some encoding.
An unencoded signature

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

procedure
(check-signature #:trust-public-key? trust-public-key?
#:trust-unsigned trust-unsigned
#:verify-signature verify-signature
#:trust-bad-digest trust-bad-digest
sig
int)
→ symbol?
  trust-public-key? : (-> input-port? any/c)
  trust-unsigned : any/c
  verify-signature : verify-signature/c
  trust-bad-digest : any/c
  sig : (or/c #f signature?)
  int : (or/c #f integrity?)

'skip and 'skip-unsigned are not equivalent. check-signature only handles a lack of a signature when sig or int is malformed.

Returns

'skip if the check was skipped.
'signature-verified when trusting the public key and the signature.
'signature-unverified when trusting the public key but not the signature.
'blocked-public-key when distrusting the public key.
'unsigned if sig or int are missing too much information to conclude that a signature is present.
'skip-unsigned is a combination of 'skip and 'unsigned. int and/or sig are missing information, but this is considered permissable when trust-unsigned is #t.

value
signature-check-passed? : predicate/c

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

value
current-verify-signature : (parameter/c verify-signature/c)

A parameter holding the current way to verify a signature.

If (signature-ffi-available?!) is #t, the default value is signature-ffi-verify-signature. Otherwise, (const #f).

value
current-make-signature : (parameter/c make-signature/c)

A parameter holding the current way to make a signature. The default value returns an empty byte string.

15.2 Signature Checking FFI🔗ℹ

(require denxi/signature/ffi)

package: denxi

denxi/signature/ffi is a private module that defines FFI bindings for a bundled library.

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

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

value
signature-ffi-make-signature! : make-signature/c

Returns bytes for a new signature.

value
signature-ffi-verify-signature! : verify-signature/c

Returns #t if a signature was verified by a public key.

procedure
(signature-ffi-get-find-signature-size!) → any/c

Returns a foreign function for computing the expected size of a signature, or #f if the function could not load.

procedure
(signature-ffi-get-make-md-context!) → any/c

Returns a foreign function for allocating a message digest context, or #f if the function could not load.

procedure
(signature-ffi-get-start-signature!) → any/c

Returns a foreign function for starting use of a cipher algorithm, or #f if the function could not load.

Each call must be paired with a call to the function returned from (signature-ffi-get-end-signature!).

procedure
(signature-ffi-get-end-signature!) → any/c

Returns a foreign function for concluding use of a cipher algorithm, or #f if the function could not load.

procedure
(signature-ffi-get-verify-signature!) → any/c

Returns a foreign function for verifying a signature using library-specific data types, or #f if the function could not load.

15.2.1 Signature Foreign Functions🔗ℹ

To be included.

15.3 Signature Prototyping🔗ℹ

(require denxi/signature/snake-oil)

package: denxi

value
snake-oil-public-key : bytes?
value
snake-oil-private-key : bytes?
value
snake-oil-private-key-password : bytes?

An intentionally-leaked RSA keypair, with a password for the private key. The private key is encrypted using AES-128 (CBC).

Each key is PEM-encoded.

Use only for prototyping signature creation and verification. Distrust for all other purposes.

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

15.1	Signature Checking Primitives
15.2	Signature Checking FFI
15.3	Signature Prototyping