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.
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.
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.
Next: (bewaking password), Previous: (bewaking cli), Up: API