Next: (bewaking password), Previous: (bewaking cli), Up: API
Return #t when the loaded libgcrypt provides Argon2 (1.11 or newer).
Derive length bytes from the string password and bytevector salt with Argon2id, version 1.3 (19), as specified by RFC 9106.
#:key memory-kib: memory cost, in kibibytes (default 65536, i.e. 64 MiB). #:key iterations: time cost, i.e. number of passes (default 3). #:key parallelism: number of lanes (default 1). #:key secret: optional bytevector used as Argon2’s secret value, called K in RFC 9106. Bewaking’s own sealing does not use it, so that the sealed data can be opened with the passphrase alone; it is accepted because a caller with a second key may want it. #:key associated-data: optional bytevector used as Argon2’s associated data, called X in RFC 9106.
Raises an error when libgcrypt has no Argon2 support, when the parameters are out of range, or when the platform’s ‘unsigned long’ does not match the pointer width the parameter array is built from.
#:example ;; The Argon2id vector of RFC 9106, Section 5.3. (argon2id-derive (make-string 32 (integer->char 1)) (make-bytevector 16 2) 32 #:memory-kib 32 #:iterations 3 #:parallelism 4 #:secret (make-bytevector 8 3) #:associated-data (make-bytevector 12 4))
Decode the hexadecimal string value into a bytevector. Upper and lower case digits are both accepted. Raises an error when the input has an odd number of digits or contains a non-hexadecimal character.
Unlike ‘base16-decode‘ this returns the raw bytes, so it can read hexadecimal that stands for binary data rather than for text.
Decode the hexadecimal string value into a string. Upper and lower case digits are both accepted. Raises an error when the input has an odd number of digits or contains a non-hexadecimal character.
Return the lowercase hexadecimal encoding of the string value, one byte per two digits.
Decode the Base64 string value into a bytevector. Whitespace is ignored, up to two trailing padding characters are accepted, and anything else raises an error.
Decode the Base64 string value into a string. Whitespace is ignored and anything that is not Base64 raises an error.
Return the standard, padded, single-line Base64 encoding of the string value.
Return the lowercase hexadecimal encoding of bytes, one byte per two digits.
Return the standard, padded, single-line Base64 encoding of bytes.
Call thunk, passing an ordinary error to handler as a key and args list.
An asynchronous interrupt is not an ordinary error: a SIGINT arrives as ~(throw ’signal ...)~, and a ~(quit)~ or ~(exit)~ as ~’quit~. Those are rethrown untouched, so wrapping a long derivation in this helper does not make Ctrl-C stop working. Everything else — what ~error~ raises — is handed to handler, which is why the safe ~decrypt-token~-style wrappers can turn any failure into a value without swallowing the operator’s interrupt.
Best-effort human-readable text for an exception caught as key with args, for diagnostics that a person has to read.
Guile reports an ~error~ through a formatting list whose leading element is the report port, and versions differ on whether that list arrives flat in args or nested inside it, so both shapes are accepted. Falls back to a plain string argument, then to the exception key, so a diagnostic is never lost.
Return #t when the string or bytevector left holds the same bytes as the string or bytevector right.
Every byte of the shorter-length comparison is examined, and the differences are accumulated before the answer is decided, so the running time depends on the length only: an attacker who can time the check learns nothing about how many leading bytes were right. Lengths that differ answer #f at once, which is the one thing this cannot hide — compare fixed-length material, such as a PBKDF2/Argon2 digest, rather than a variable-length password.
Derive length bytes from the string password and the bytevector salt, with the key-derivation function described by kdf (see ‘kdf-spec’). Raises an error for an unknown derivation or for parameters the chosen derivation cannot use.
Open a Base16 string produced by ‘gcm-encrypt’ under the string key, and return the plaintext bytevector.
Which key derivation to use, and with which parameters, is read from the sealed payload itself, so nothing has to be configured to open it. The recorded parameters are checked before a key is derived from them. Raises an error when the payload is malformed or truncated, when its key derivation is unknown, or when the authentication tag does not match — as happens with a wrong key, altered ciphertext, or associated data that is not the same as when the payload was sealed.
Seal the bytevector plaintext under the string key, deriving the 32-byte AES-256-GCM key with kdf, and return a Base16 string that records which derivation was used and with which parameters.
#:key kdf: the key-derivation specification; see ‘kdf-spec’. #:key salt: the 16 salt bytes to use; defaults to fresh random bytes. #:key nonce: the 12 nonce bytes to use; defaults to fresh random bytes. It must never repeat under the same key, which is why it defaults to a fresh random value. #:key associated-data: optional bytevector that is authenticated together with the ciphertext but stored by the caller. Opening requires the identical bytes.
Return the HMAC-SHA256 of the string message under the string key, as a lowercase hexadecimal string.
Decrypt a Base64 string produced by ‘kdf-encrypt’ (or, for the PBKDF2
layout, by openssl enc -aes256 -pbkdf2 -a -A) under the string
key, returning the original plaintext string.
Which key derivation to use, and with which parameters, is read from the sealed payload itself, so nothing has to be configured to open old data. Raises an error when the payload is not sealed, when its parameters are out of range, or when the padding is invalid — as happens with a wrong key.
Encrypt the string plaintext under the string key, deriving the AES-256 key and IV with kdf, and return a Base64 string that records which derivation was used.
#:key kdf: the key-derivation specification; see ‘kdf-spec’. Defaults to PBKDF2, which produces the OpenSSL-compatible layout. #:key salt: the salt bytes to use, 8 for PBKDF2 and 16 for Argon2id; defaults to fresh random bytes.
Return the name of the key-derivation function named by kdf.
Return the salt length, in bytes, that the derivation named by kdf uses inside a sealed payload: 8 for the OpenSSL-compatible PBKDF2 layout, 16 for Argon2id. Callers that supply their own salt need this to size it.
Normalize a key-derivation specification into a complete alist.
kdf may be the symbol ~pbkdf2~ (the default), the symbol ~argon2id~, or an alist whose ~kdf~ entry names the function and whose remaining entries are its parameters, as in ~’((kdf . argon2id) (memory-kib . 262144))~. Missing parameters are filled in with the defaults, so the result can be handed straight to ‘kdf-encrypt’. Raises an error for an unknown KDF or an out-of-range parameter.
Decrypt a Base64 string produced by ‘openssl-encrypt’ (or by
openssl enc -aes256 -pbkdf2 -a -A) under the string key,
and return the original plaintext string. Raises an error when the
input is not in that format or when the padding is invalid, as happens
with a wrong key.
Encrypt the string plaintext under the string key and return
the result as a Base64 string, in the exact format produced by
openssl enc -aes256 -pbkdf2 -a -A -k KEY: an 8-byte random salt
in a Salted__ header followed by the AES-256-CBC ciphertext.
#:key salt: the 8 salt bytes to use; defaults to fresh random bytes.
Derive length bytes from the string password and bytevector salt using PBKDF2-HMAC-SHA256 over iterations iterations.
Return a bytevector of length cryptographically strong random bytes.
3
((kdf . argon2id) (memory-kib . 65536) (iterations . 3) (parallelism . 1))
65536
1
pbkdf2
12
16
Next: (bewaking password), Previous: (bewaking cli), Up: API