▼Crypto:   Cryptographic Operations
►7 Miscellaneous Utilities
On this page:
7.1 Main Utilities
7.1.1 Input to Cryptographic Operations
input/  c
bytes-range
7.1.2 Random Bytes
crypto-random-bytes
7.1.3 Security Strength Levels
security-strength/  c
security-level/  c
security-level->strength
security-strength->level
7.2 PEM Reading
read-pem
7.3 Bech32 Encoding and Decoding
bech32-encode
bech32-decode
7.4 age Encryption
age-encrypt
age-decrypt
  top  contents    up   

7 Miscellaneous Utilities🔗ℹ

7.1 Main Utilities🔗ℹ

The utilities in this section are provided by the main crypto module.

7.1.1 Input to Cryptographic Operations🔗ℹ

value

input/c : contract?

Contract for valid input data to an operation such as digest, encrypt, etc. The operations are defined in terms of bytestrings, but other values are accepted and converted as following:
Note that fixed-sized data such as keys, IVs, etc are not represented as input/c.

struct

(struct bytes-range (bs start end))

  bs : bytes?
  start : exact-nonnegative-integer?
  end : exact-nonnegative-integer?
Alias for slice, bytes-slice?, etc.

Changed in version 1.9 of package crypto-lib: Converted to alias for slice. Previously, bytes-range was a distinct struct type.

7.1.2 Random Bytes🔗ℹ

procedure

(crypto-random-bytes n) → bytes?

  n : exact-nonnegative-integer?
For convenience, this library re-exports crypto-random-bytes from racket/random.

Added in version 1.2 of package crypto-lib.

7.1.3 Security Strength Levels🔗ℹ

value

security-strength/c : contract? = exact-nonnegative-integer?

Represents the estimated security strength, measured in bits, of a cryptographic primitive. The strength rating of primitives generally follows the guidelines specified by NIST SP 800-57 Part 1 (Section 5.6: Guidance for Cryptographic Algorithm and Key-Size Selection). See also security-level/c.

Note: The security strength of a cryptographic primitive is generally not the same as its key size or its output size. Furthermore, reasoning in terms of security bits requires considering all parts of a system: for example, if a message has only 20 bits of entropy, then taking the SHA-512 of it still only has 20 bits of entropy.

Added in version 1.8 of package crypto-lib.

value

security-level/c : contract? = (integer-in 0 5)

Represents a security level comparable to an OpenSSL security level. The levels correspond to the ranges of security strength ratings as follows:

Level

    

Bits

    

Includes*

0

    

< 80

    

SHA-1

1

    

≥ 80 but < 112

    

RSA≥1024, ECC≥160

2

    

≥ 112 but < 128

    

RSA≥2048, ECC≥224, SHA-224

3

    

≥ 128 but < 192

    

RSA≥3072, ECC≥256, SHA-256

4

    

≥ 192 but < 256

    

RSA≥7680, ECC≥384, SHA-384

5

    

≥ 256

    

RSA≥15360, ECC≥512, SHA-512

The “Includes” column is incomplete and imprecise. For example, SHA-256 is rated at 128 bits of security in contexts where collision resistance is required (for example, in a digital signature) but 256 bits when it is not (for example, with HMAC).

Added in version 1.8 of package crypto-lib.

procedure

(security-level->strength level) → security-strength/c

  level : security-level/c
Converts a security level to the minimum value of its security strength range.

Added in version 1.8 of package crypto-lib.

procedure

(security-strength->level strength) → security-level/c

  strength : security-strength/c
Converts a security strength rating to the security level that contains it.

Added in version 1.8 of package crypto-lib.

7.2 PEM Reading🔗ℹ

 (require crypto/pem) package: crypto-lib

Added in version 1.7 of package crypto-lib.

procedure

(read-pem in [decode #:only only-kinds])

 → (or/c (cons/c bytes? any/c) eof)
  in : input-port?
  decode : (-> bytes? any/c) = base64-decode
  only-kinds : (or/c #f (listof bytes?)) = #f
Reads a single PEM-encapsulated datum from in, decodes it using decode, and returns a pair containing the encapulation boundary label and the decoded result. Data before the starting encapsulation boundary is discarded. If no starting encapsulation boundary is found before the end of input, eof is returned. If the ending encapsulation boundary is missing or has the wrong label, an error is raised.

For example, the encapsulation boundaries for an X.509 certificate are lines consisting of #"-----BEGIN CERTIFICATE-----" and #"-----END CERTIFICATE-----", and the label returned is #"CERTIFICATE".

Note: This format is the PEM-based “textual encoding” [RFC7468] used for encoding cryptographic keys, certificates, etc. It is commonly called “PEM” although it is not completely compatible with the original PEM format.

7.3 Bech32 Encoding and Decoding🔗ℹ

 (require crypto/util/bech32) package: crypto-lib

Added in version 1.9 of package crypto-lib.

This module implements an encoder and decoder for the Bech32 format, which is used by the age encryption tool to encode X25519 public and private keys.

procedure

(bech32-encode hrp data) → string?

  hrp : string?
  data : bytes?
Encodes the “human-readable part” (hrp) with the given data. If hrp contains disallowed characters, or if the result would be longer than 90 characters, an exception is raised.

Example:
> (bech32-encode "age" #"1234567890abcdef1234567890UVWXYZ")

"age1xyerxdp4xcmnswfsv93xxer9vccnyve5x5mrwwpexp24v46ct9dq3wvnf4"

procedure

(bech32-decode s) → (list/c string? bytes?)

  s : string?
Decodes the Bech32 string s, producing a “human-readable part” string and a data byte string.

If s is not a well-formed Bech32 string, an exception is raised. In particular, s must be between 8 and 90 characters long, it must not contain a mixture of lowercase and uppercase letters, and it must end with a valid checksum.

Examples:
> (bech32-decode "age1xyerxdp4xcmnswfsv93xxer9vccnyve5x5mrwwpexp24v46ct9dq3wvnf4")

'("age" #"1234567890abcdef1234567890UVWXYZ")

> (bech32-decode "age1xyerxdp4xcmnswfsv93xxer9vccnyve5x5mrwwpexp24v46ct9dq3wvnf")

bech32-decode: invalid checksum

7.4 age Encryption🔗ℹ

 (require crypto/util/age) package: crypto-lib

Added in version 1.9 of package crypto-lib.

Implementation of age-encryption.org/v1, compatible with the age encryption tool.

X25519 keys can be imported and exported in age-compatible format using pk-key->datum and datum->pk-key with the 'age/v1-public and 'age/v1-private format symbols.

procedure

(age-encrypt recips data) → bytes?

  recips : (listof (or/c pk-key? (list/c 'scrypt bytes?)))
  data : (or/c input-port? bytes?)
Encrypts data to each recipient in recips. Each recipient must be either an X25519 public key (pk-key?) or (list 'scrypt passphrase). In addition, there must be at most one 'scrypt recipient, and if there is an 'scrypt recipient, it must be the only recipient; otherwise, an exception is raised.

procedure

(age-decrypt idents enc-data) → bytes?

  idents : (listof (or/c private-key? bytes?))
  enc-data : (or/c input-port? bytes?)
Decrypts enc-data using one of the identities listed in idents. Each identity must be either an X25519 private key (private-key?) or a byte string passphrase.

If decryption fails, an exception is raised.

  top  contents    up