Sagittarius provides a comprehensive set of cryptographic libraries. Currently the libraries support below:
Block cipher
Asymmetric cipher
Cryptographic hash functions
Cryptographically secure pseudo random number generators (CSPRNG)
Signature generation / verification
Key generate, agreement and import/export
MAC
X.509 CSR, CRL and certificate
PKCS#5 via PBKDF
PKCS#8
PKCS#12 keystore
PEM
Various KDFs
Not like legacy (crypto) and (math) libraries, these libraries are
split per components. Users need to combine some libraries to achieve
their goals.
This section shows some basic examples how to use the crypto graphic libraries.
This example encrypts and decrypts a plain text with a radomly generated secret key. The encryption scheme is AES-256 and encryption mode is CTR.
(import (rnrs)
(sagittarius crypto ciphers)
(sagittarius crypto keys))
;; Randomly generates AES-256 secret key.
(define key (generate-symmetric-key *scheme:aes-256*))
;; Initial Vector (use randomly generated one in production code)
(define iv
(make-bytevector (block-cipher-descriptor-block-length *scheme:aes-256*) 1))
;; AES-256 cipher with CTR mode, without padding
(define aes-cipher
(make-block-cipher *scheme:aes-256* *mode:ctr* no-padding))
;; Cipher parameter.
;; NOTE, IV will be copied so modifying original IV doesn't affect the result
(define parameter
(make-cipher-parameter
(make-iv-parameter iv)
(make-counter-mode-parameter *ctr-mode:big-endian*)))
(define (encrypt cipher key parameter plain-text)
(block-cipher-init! cipher (cipher-direction encrypt) key parameter)
(let ((cipher-text (block-cipher-encrypt-last-block cipher plain-text)))
(block-cipher-done! cipher)
cipher-text))
(define (decrypt cipher key parameter cipher-text)
(block-cipher-init! cipher (cipher-direction decrypt) key parameter)
(let ((plain-text (block-cipher-decrypt-last-block cipher cipher-text)))
(block-cipher-done! cipher)
plain-text))
(define plain-text (string->utf8 "Hello Sagittarius Scheme!"))
(decrypt aes-cipher key parameter (encrypt aes-cipher key parameter plain-text))
;; -> A bytevector of UTF-8 representation of `plain-text`
This example shows how to use a string password as a key (Password-Based Encryption Scheme, a.k.a. PBES). PBES is just a block cipher using a derived key. To do so, you need to use KDF, Key Derivation Function.
(import (rnrs)
(sagittarius crypto ciphers)
(sagittarius crypto keys)
(sagittarius crypto kdfs) ;; for PBKDF2
(sagittarius crypto digests) ;; for digests, e.g. SHA-256
(sagittarius crypto mac)) ;; for MAC, NOTE: PRF = MAC
;; If everyone uses this kind of password, then it'd be almost impossibe
;; to crack :)
(define password "You can't guess this password! It's so strong!! :D")
;; PRF
(define prf (mac->prf-provider *mac:hmac* :digest *digest:sha-256*))
(define (derive-key scheme password)
;; I'm not sure if this is a bad practice or not, but for simplicity
;; we use hashed password as a salt
(define md (make-message-digest *digest:sha-256*))
(define bv (string->utf8 password))
(define salt (digest-message md bv))
;; 310,000 iteration, required by FIPS-140
(pbkdf-2 bv salt 310000
(block-cipher-descriptor-suggested-key-length scheme)
:prf prf))
(define key
(generate-symmetric-key *scheme:aes-256*
(derive-key *scheme:aes-256* password)))
;; The rest can be the same as above CTR mode example.
This example shows how to handle offline encryption mode.
(import (rnrs)
(sagittarius crypto ciphers)
(sagittarius crypto keys))
(define key (generate-symmetric-key *scheme:aes-256*))
;; GCM-SIV nonce size = 12
(define iv (make-bytevector 12))
;; AES-256-GCM-SIV
(define aes-cipher
(make-block-cipher *scheme:aes-256* *mode:gcm-siv* no-padding))
(define parameter
(make-cipher-parameter
(make-iv-parameter iv)
;; empyt AAD :)
(make-aad-parameter #vu8())))
(define (encrypt-messages . messages)
(for-each (lambda (message)
;; output space is not needed, and this procedure returns 0
(block-cipher-encrypt! aes-cipher message 0 #vu8() 0)) messages)
(let* ((out-size (block-cipher-last-block-size aes-cipher 0))
(out (make-bytevector out-size)))
;; passing dummy block
(block-cipher-encrypt-last-block! aes-cipher #vu8() 0 out 0)
(values out (block-cipher-done/tag aes-cipher))))
(block-cipher-init! aes-cipher (cipher-direction encrypt) key parameter)
(let-values (((enc tag) (encrypt-messages (string->utf8 "Hello, GCM-SIV") (string->utf8 "\nI'm done"))))
(block-cipher-init! aes-cipher (cipher-direction decrypt) key (make-cipher-parameter parameter (make-tag-parameter tag)))
(let* ((size (block-cipher-last-block-size aes-cipher enc))
(msg (make-bytevector size)))
(block-cipher-decrypt-last-block! aes-cipher enc 0 msg 0)
(block-cipher-done/tag! aes-cipher tag)
(utf8->string msg)))
;; "Hello, GCM-SIV\nI'm done"
This example encrypts and decrypts a plain text with a randomly generated secret key. The encryption scheme is ChaCha20 Poly1305.
(import (rnrs)
(sagittarius crypto ciphers)
(sagittarius crypto keys))
;; Randomly generates AES-256 secret key.
(define key (generate-symmetric-key *scheme:aes-256*))
This example encrypts and decrypts a plain text with a randomly generated RSA key pair.
(import (rnrs)
(sagittarius crypto ciphers)
(sagittarius crypto keys)
(sagittarius crypto digests))
;; Randomly genrates RSA key pair. Default 2048 bits
(define key-pair (generate-key-pair *key:rsa*))
;; Making RSA cipher with OAEP encoding (default) with SHA-256
(define rsa-cipher
(make-asymmetric-cipher *scheme:rsa* :digest *digest:sha-256*))
;; Encryption can only be done by a public key
(define (encrypt cipher key plain-text)
(asymmetric-cipher-init! cipher key)
(let ((cipher-text (asymmetric-cipher-encrypt-bytevector cipher plain-text)))
(asymmetric-cipher-done! cipher)
cipher-text))
;; Decryption can only be done by a private key
(define (decrypt cipher key cipher-text)
(asymmetric-cipher-init! cipher key)
(let ((plain-text (asymmetric-cipher-decrypt-bytevector cipher cipher-text)))
(asymmetric-cipher-done! cipher)
plain-text))
(define message (string->utf8 "Hello Sagittarius Scheme"))
(decrypt rsa-cipher (key-pair-private key-pair)
(encrypt rsa-cipher (key-pair-public key-pair) message))
;; -> A bytevector of UTF-8 representation of `plain-text`
In the libraries, hash is called digest. So, from now on we use digest instead of hash.
Below example shows how to generate a digest of SHA-256.
(import (rnrs)
(sagittarius crypto digests))
(define md (make-message-digest *digest:sha-256*))
(digest-message md (string->utf8 "Hello Sagittarius Scheme"))
;; -> #vu8(65 109 154 253 119 192 195 187 255 90 75 208 135 51 25 43 106 121 236 172 96 233 38 189 154 240 32 8 116 58 169 237)
Also below example shows how to generate a digest of SHAKE-256, which generates a variable length digest.
(import (rnrs)
(sagittarius crypto digests))
(define md (make-message-digest *digest:shake-256*))
;; Generates 32 bytes digests
(digest-message md (string->utf8 "Hello Sagittarius Scheme") 32)
;; -> #vu8(127 141 98 85 40 216 103 129 10 71 136 179 158 103 163 218 109 65 244 77 119 4 109 54 135 126 225 162 188 58 16 64)
Below example shows how to generate a random integer.
(import (rnrs)
(sagittarius crypto random))
;; Pseudo random generator, it returns the same value each execution
(define prng (pseudo-random-generator *prng:chacha20*))
;; Secure random generator, it returns random value each execution
;; (define prng (secure-random-generator *prng:chacha20*))
;; range of 0 <= r < 100
(random-generator-random-integer prng 100)
;; -> each time the same result as it's pseudo random, not secure random
The key library provides key operations for both symmetric and asymmetric keys.
The key library, this library exports the procedures listed below sections.
Sagittarius crypto library uses hierachial key structure. The hierarchy of the key type is below.
+--------------+
| <crypto-key> |
+------+-------+
|
+--------------+-------------+
| |
+--------+--------+ +--------+---------+
| <symmetric-key> | | <asymmetric-key> |
+-----------------+ +--------+---------+
|
+--------+--------+
| |
+-------+------+ +-------+------+
| <public-key> | | <private-key |
+--------------+ +--------------+
Returns #t if the given obj is an instance of <crypto-key>,
otherwise #f.
Returns #t if the given obj is an instance of <symmetric-key>,
otherwise #f.
Returns #t if the given obj is an instance of <asymmetric-key>,
otherwise #f.
Returns #t if the given obj is an instance of <public-key>,
otherwise #f.
Returns #t if the given obj is an instance of <private-key>,
otherwise #f.
Creates a symmetric key of the value of bv.
The key can be used for any of the symmetric ciphers supported by
Sagittarius, however it is users' responsibility to align the key
size. If you want to make sure the bv has the right key size,
consier using generate-symmetric-key method.
Retrieves the raw key value of the given key.
Generates a symmetric key suitable for the given block cipher scheme, randomly.
Creates a symmetric from the bytevector, this method checks the key size if it's appropriate for the given cipher or not.
Creates a key wrap procedure using given scheme and key. The optional keyword parameter iv is used as an initial vector if provided.
Creates an AES key wrap procedure.
Creates an Camellia key wrap procedure.
Creates a key unwrap procedure using given scheme and key. The optional keyword parameter iv is used as an initial vector if provided.
Creates an AES key unwrap procedure.
Creates an Camellia key unwrap procedure.
Returns #t if the given obj is a key pair, otherwise #f.
key-pair?
)
Returns the private key of the given kp.
Returns the public key of the given kp.
Generates a key pair of the given scheme. Followings are the supported schemes:
Those are RSA, DSA, ECDSA, Ed5519, Ed448, X25519 and X448 respectively.
For convenience *scheme:rsa has the same effect as *key:rsa.
A macro returns a symbol representation of format. The format must be
either raw or subject-public-key-info.
raw:
Imports/exports raw public key.
subject-public-key-info:
Imports/exports subject public key info.
Enum set of the public-key-format.
Returns #t if the given obj is a member of public-key-format enum.
Imports a public from the given <bytevector> or <port> which must be
a valid subject public key info.
The returning public key type is detected via the OID inside of the
subject public key info.
Imports RSA key from given <bytevector> or <port>. The optional format
specifies the format of the given key. Default value is raw.
Exports RSA key from the given <rsa-public-key>. The optional format
controls the format of the exporting key. Default value is raw.
Imports DSA key from given <bytevector> or <port>. The optional
format specifies the format of the given key. Default value is
subject-public-key-info.
If raw is specified, then optional argument parameter must be specified
and it must be <dsa-key-parameter>
Exports DSA key from the given <dsa-public-key>. The optional
format controls the format of the exporting key. Default value
is subject-public-key-info.
Imports ECDSA key from given <bytevector> or <port>. The optional
format specifies the format of the given key. Default value is
subject-public-key-info.
If raw format is specified, then optional parameter ec-parameter must be
specified. Below are the supported EC parameters.
After ec-parameter: represents the parameter name.
Exports ECDSA key from the given <ecdsa-public-key>. The optional
format controls the format of the exporting key. Default value
is subject-public-key-info.
Imports Ed25519 or Ed448 public key from the given <bytevector> or <port>.
The optional format controls the key format, default is raw.
Exports Ed25519 or Ed448 key from the given <eddsa-public-key>. The optional
format controls the format of the exporting key. Default value
is raw.
If the first form is used, then the method automatically detects the key type.
Imports X25519 or X448 public key from the given <bytevector> or <port>.
The optional format controls the key format, default is raw.
Exports X25519 or X448 key from the given <rfc7748-public-key>. The optional
format controls the format of the exporting key. Default value
is raw.
If the first form is used, then the method automatically detects the key type.
A macro returns a symbol representation of format. The format must be
either raw or private-key-info.
raw:
Imports/exports raw public key.
private-key-info:
Imports/exports private key info or one asymmetric key.
Enum set of the private-key-format.
Returns #t if the given obj is a member of private-key-format enum.
Imports a private key from the <bytevector> or <port> which must
be a valid private key info or one asymmetric key.
The returning private key type is detected by the OID inside of the
private key info.
Imports a RSA private key from the <bytevector> or <port>. The
format of the input must be a raw RSAPrivateKey.
Exporting RSA private key is only supported with CRT key.
Exports the given <rsa-crt-private-key>. The optional format controls
the format of the exporting key. Default value is raw.
Imports a DSA private key from the <bytevector> or <port>. The
format of the input must be a raw DSAPrivateKey.
Exports the given <dsa-private-key>. The optional format controls
the format of the exporting key. Default value is raw.
Imports a ECDSA private key from the <bytevector> or <port>. The
format of the input must be a raw ECPrivateKey.
If the given raw key doesn't contain EC parameter, then the optional
ec-parameter must be provided.
Exports the given <ecdsa-private-key>. The optional format controls
the format of the exporting key. Default value is raw.
Imports a Ed25519 or Ed448 private key from the <bytevector> or <port>.
Exports the given <eddsa-private-key>. The optional format controls
the format of the exporting key. Default value is raw.
If the first form is used, then the exporting key type is detected
from the given key.
Calculate a secret key from the given private key and public key.
The cipher library provides both symmetric and asymmetric cipher operations.
The cipher library, this library exports the procedures listed below sections.
Cipher parameters are parameters to pass to the cipher, such as Initial Vector (IV).
All the parameter value retriever accept optional argument. If it's
provided and the parameter is not or does not contain the target
parameter, then the default value is returned, otherwise &assertion
is signalled.
NOTE: The cipher parameters are only used on symmetric ciphers. Asymmetric ciphers use keywords.
Returns #t if the given obj is a cipher parameter, otherwise #f.
A cipher parameter can be a simple parameter or composite parameter like the condition system.
Creates a composite cipher parameter whose contents are given parameters.
Returns #t if the given obj is a round cipher parameter, otherwise #f.
This parameter is used all the modes.
Creates a round cipher parameter with the given round.
Retrieves the round field of the given parameter.
Returns #t if the given obj is a iv cipher parameter, otherwise #f.
This parameter is used by CBC, CFB, OFB, CTR, LRW F8 and GCM, and all of the modes require it.
bytevector?
)
Creates a IV cipher parameter with the given iv. The iv is copied during the creation so modifying the original value does not affect the parameter.
Retrieves the iv field of the given parameter.
Returns #t if the given obj is a counter mode cipher parameter,
otherwise #f.
This parameter is used by CTR mode and if it's not provided, then
*ctr-mode:big-endian* is used.
Creates a counter mode parameter with the given mode. The mode must be one of the following:
These modes are little-endian, big-endian, and IPSec ESP described RFC 3686, respectively.
Retrieves the counter-mode field of the given parameter.
Returns #t if the given obj is a tweak cipher parameter, otherwise #f.
This parameter is used by LRW mode, and it's a required parameter.
Creates a tweak cipher parameter with the given tweak. The tweak is copied during the creation so modifying the original value does not affect the parameter.
Retrieves the tweak field of the given parameter.
Returns #t if the given obj is a salt cipher parameter, otherwise #f.
This parameter is used by F8 mode, and it's a required parameter.
Creates a salt cipher parameter with the given salt. The salt is copied during the creation so modifying the original value does not affect the parameter.
Retrieves the salt field of the given parameter.
Returns #t if the given obj is a nonce cipher parameter, otherwise #f.
This parameter is used by EAX, OCB and OCB3. EAX doesn't require it, others require it.
Creates a nonce cipher parameter with the given nonce. The nonce is copied during the creation so modifying the original value does not affect the parameter.
Retrieves the nonce field of the given parameter.
Returns #t if the given obj is a aad cipher parameter, otherwise #f.
This parameter is used by EAX and GCM. It's an optional parameter.
Creates a aad cipher parameter with the given aad. The aad is copied during the creation so modifying the original value does not affect the parameter.
Retrieves the aad field of the given parameter.
Returns #t if the given obj is a tag length cipher parameter,
otherwise #f.
This parameter is used by OCB3 and it's a required parameter.
Creates a tag length cipher parameter with the given tag-length.
Retrieves the tag-length field of the given parameter.
Returns #t if the given obj is a tag length cipher parameter,
otherwise #f.
This parameter is used by CCM and GCM-SIV (on decryption), and it's a required parameter.
integer?
)
Creates a tag length cipher parameter with the given tag.
Retrieves the tag field of the given parameter.
Returns #t if the given obj is a cipher descriptor, otherwise #f.
A cipher descriptor is an object which holds encryption scheme information,
such as algorithm, key length, etc.
This object itself doesn't provide any cipher operations, to execute
them, users need to create a cipher object.
Returns the name of the given descriptor.
Returns #t if the given obj is a cipher object, otherwise #f.
A cipher object is an actual working object to operate cipher operation.
A cipher may holds operation state, and it is users' responsibility to
make sure not to mix up the state.
A macro returns a symbol representation of direction. The direction
must be either encrypt or decrypt.
Symmetric cipher can be either block cipher or stream cipher.
Returns #t if the given obj is a symmetric cipher descriptor,
otherwise #f.
Returns minimum key length of the given descriptor's algorithm.
Returns maximum key length of the given descriptor's algorithm.
Returns #t if the given obj is a symmetric cipher object, otherwise #f.
Returns #t if the given obj is a block cipher descriptor,
otherwise #f.
Currently, below encryption algorithms are supported:
Some of the algorithms are considered as broken cipher, such as DES.
It is users' responsibility to use those ciphers.
NOTE: NIST recommends to use AES.
Returns block size of the given descriptor's algorithm.
block-cipher-descriptor?
) :optional size
Returns suggested key length of the given descriptor's algorithm.
Most of the time, this returns the result of
the symmetric-cipher-descriptor-max-key-length procedure.
If the optional argument size is provided, then it check the size is valid length of the key length.
Returns #t if the given obj is a mode descriptor, otherwise #f.
Currently, below encryption modes are supported.
Mode descriptors for ECB, CBC, CFB, OFB, CTR, LRW and F8 respectively.
Mode descriptor for EAX, OCB, OCB3, GCM, GCM-SIV and CCM respectively. These are authenticated encryption with assiciated data (AEAD) modes.
GCM-SIV and CCM are offline mode, which means it requires to know
all the input ahead. So, cipher encryption or decryption procedures
don't return encrypted or decrypted values. Only the last block
handling will do. This also implies that the last block handling
may require output space more than input block size. To know the
required space, use block-cipher-last-block-size procedure. See the example
for the detail usage.
Returns the name of the given descriptor.
Returns #t if the given obj is a block cipher object, otherwise #f.
Creates a block cipher object of scheme encryption scheme and
mode encryption mode.
padding is used to encrypt or decrypt the last block of the plain text.
Returns the block length of the given cipher.
Initialise the given cipher for the given direction purpose with
the given key and parameter.
The direction must be a symbol returned by the cipher-direction macro.
Initialise the give cipher. This procedure is an analogy to the
block-cipher-init!, the difference is this procedure returns a
copy of the given cipher.
Encrypts the given plain text pt from the position of ps, and store the
cipher text into ct from the position of cs. Then returns the byte
size of the encrypted plain text.
The encryption is executed by the given cipher.
Encrypts the given plain text pt from the position of ps, and
returns the cipher text.
The encryption is executed by the given cipher.
NOTE: the given pt length and result cipher text length may differ if the pt length is not multiple of the cipher block size.
Returns the required output space in bytes.
This procedure is useful when the encryption mode is GCM-SIV or CCM.
Encrypts the given plain text pt from the position of ps, and store the
cipher text into ct from the position of cs. Then returns the byte
size of the encrypted plain text.
The encryption is executed by the given cipher.
This procedure consumes all the plain text, and applies padding if needed.
block-cipher?
) (
pt
bytevector?
) :optional (
ps
0)
Encrypts the given plain text pt from the position of ps, and
returns the cipher text.
The encryption is executed by the given cipher.
This procedure consumes all the plain text, and applies padding if needed.
Decrypts the given cipher text ct from the position of cs, store the plain text info pt from the position of cs. Then returns the byte size of the decrypted cipher text. The decryption is executed by the given cipher.
Decrypts the given cipher text ct from the position of cs, and
returns the plain text.
The decryption is executed by the given cipher.
NOTE: the given ct length and result plain text length may differ if the ct length is not multiple of the cipher block size.
Decrypts the given cipher text ct from the position of cs, store the plain text info pt from the position of cs. Then returns the byte size of the decrypted cipher text.
This procedure applies unpadding if the cipher is created with padding.
block-cipher?
) (
ct
bytevector?
) :optional (
cs
0)
Decrypts the given cipher text ct from the position of cs, and
returns the plain text.
The decryption is executed by the given cipher.
This procedure applies unpadding if the cipher is created with padding.
Cleanup the given cipher and make it neutral state.
Updating Additional Authentication Data aad of the given cipher.
Optional arguments restricts the range of the aad.
This procedure is effective on authenticated encryption modes.
Updating Initial Vector iv of the given cipher.
Optional arguments restricts the range of the iv.
This procedure is effective only GCM mode.
Returns the max tag length of the given cipher. If the cipher doesn't
support authentication tag, then it returns 0.
If the cipher is encryption mode, then the procedure stores the authentication tag into the give tag of the position starting start.
If the cipher is decryption mode, then the procedure validates the given tag against the cipher's authentication tag starting from the position of start.
This procedure is only for encryption mode.
Stores the cipher's authentication tag into the given tag,
starting position of start.
Returns #t if the given obj is a stream cipher descriptor, otherwise #f.
Currently, below encryption algorithms are supported:
Returns #t if given the descriptor is a AEAD stream cipher, otherwise #f.
Returns #t if the given obj is a stream cipher object, otherwise #f.
Creates a stream cipher object of scheme encryption scheme.
Returns #t if the given obj is an asymmetric cipher descriptor,
otherwise #f.
Currently, below asymmetric encryption algorithms are supported:
Returns #t if the given obj is an asymmetric cipher, otherwise #f.
asymmetric-cipher-descriptor?
:key
encoding
:allow-other-keys
Creates an asymmetric cipher of scheme.
The encoding specifies its encoding algorithm, default is oaep-encoding.
Initialise the given cipher with the given key.
Initialise the given cipher with the given key. This procedure is an
analogy to the asymmetric-cipher-init!, the differ is this procedure
returns a copy of the given cipher.
Encrypts the given bytevector bv with the given cipher from the position of start and returns a bytevector.
Decrypts the given bytevector bv with the given cipher from the position of start and returns a bytevector.
Cleanup the given cipher.
Provides OAEP encoding scheme. This can be used for :encoding keyword's
argument of the make-asymmetric-cipher procedure.
This encoding scheme accepts the following keyword arguments:
:digest
A digest descriptor to be generate a digest for label provided by :label
keyword. Default value is *digest:sha-1*
:label
A label. Default value is #vu8().
:mgf
MGF function. Default value is mgf-1.
:mgf-digest
A digest descriptor to be used by the :mgf's argument. Default value is
*digest:sha-1*.
:prng
A pseudo random generator to generate padding. Default value is
(secure-random-generator *prng:chacha20*).
Provides PKCS#1.5 encoding scheme. This can be used for :encoding keyword's
arguments of the make-asymmetric-cipher procedure.
This encoding scheme accepts the following keyword arguments:
:prng
A pseudo random generator to generate padding. Default value is
(secure-random-generator *prng:chacha20*).
MGF-1 procedure. This can be used to :mgf keyword's argument of the
oaep-encoding.
The digest library provides cryptographic hash functions.
The digest library, this library exports the procedures listed below sections.
A digest descriptor describes the characteristic of the digest, such as name, digest size (if applicable), block size and OID (if exists).
Returns #t if the given obj is a digest descriptor, otherwise #f.
Returns the human readable name of the descriptor.
Returns the digest size of the descriptor. Some of the digests, e.g. SHAKE, don't have fixed digest size.
Returns the block size of the descriptor.
Returns the OID of the descriptor. If the digest doesn't have OID, then
it returns #f.
Blow are the digest descriptors supported by this library:
We supports weak / broken digest algorithms, such as MD5. It is users' responsibility to choose appropriate algorithm.
Message Digest is a stateful object which ingests input and provides digests.
Returns #t if the given obj is a message digest, otherwise #f.
Creates a message digest of the algorithm descriptor.
Returns the digest descriptor of given md.
Returns the digest size of given md.
Returns the digest of the given msg.
The optional argument length is only required for the variable
length digest algorithms, such as SHAKE. Otherwise, the value will be
ignored.
Digests the given msg, then fill the result into the out.
Optional argument start and length specify the start position of the
out and the length of the filling.
Below procedures are low level APIs which can be used not to allocate
entire input buffer, say using get-bytevector-n! instead of
get-bytevector-all.
Initialises the given md. This procedure rests the previous input as well.
Ingests the given msg into md.
Optional argument start and length controls the range of the msg.
Fill the result digest of md into the out.
Optional argument start and length controls the range of the out.
Returns a freshly allocated bytevector whose content is the result of
md, digest.
Optional argument length is only used for the variable length digest
algorithm, such as SHAKE. Otherwise it will be ignored.
The random library provides cryptographically secure random number generator (CSPRNG) operations.
The random library, this library exports the procedures listed below sections.
PRNG descriptor is a representation of pseudo random generator (PRNG).
Returns #t if the given obj is a PRNG descriptor, otherwise #f.
Returns a human readable name of the given descriptor.
Below are the supported PRNGs.
These are the PRNG algorithms, Yarrow, Fortuna RC4, Sober-128 and ChaCha20, respectively.
This is a system, platform dependent, PRNG. For example, this PRNG reads
from file descriptor of /dev/urandom on Linux or other POSIX environment
if the device exists.
Ths PRNG is slow as it requires I/O. Also can't be pseudo random generator described below.
Random generator has a hierachical class structure. If you only use the provided PRNGs, you don't have to care about it. However, if you want to make a custom algorithm which is not supported by the library, then you may need to know how to enhance it. Creating a custom random generator is described the below section.
<random-generator>
|
+---------------------------+------------------------+
| | |
<builtin-random-generator> <secure-random-generator> <custom-random-generator>
| |
+-------------+-------------+
|
<builtin-secure-random-generator>
Returns #t if the given obj is a random generator, otherwise #f.
Returns #t if the given obj is a builtin random generator, otherwise #f.
Returns #t if the given obj is a secure random generator, otherwise #f.
Returns #t if the given obj is a custom random generator, otherwise #f.
Returns a bytevector of length size filled with random data read from the given random-generator.
Reads random data from random-generator, and fill them into out.
If optional arguments starts and length are specified, then it specifies
the range of the output bytevector.
Add entropy seed to the given random-generator.
If optional arguments starts and length are specified, then it specifies
the range of the seed bytevector.
Returns a random integer of range 0 <= n <= bound.
Creates a pseudo or secure random generator, respectively.
If the given descriptor is PRNG descrptor, then these procedure
creates builtin random generator ignoreing the given opts.
If the given descriptor is not PRNG descrptor, then these procedure
call make-custom-random-generator method passing descriptor and
opts.
If secure-random-generator is used, then make-custom-random-generator
receives :secure-random keyword argument with value of #t, so that
the receiver can handle it properly.
Gets the state of given <random-generator> if it's supported.
By default this method returns #f, means not supported.
Sets the given state represented by <any> to <random-generator>
if it's supported.
By default this method does nothing and returns #f, means not supported.
The signature library provides signature generation / verification operations.
The signature library, this library exports the procedures listed below sections.
Below are the algorithms supported by the library.
These algorithms can be used both signer and verifier.
Returns #t if the given obj is a signer, otherwise #f.
Creates a signer of the scheme. The scheme must be one of the signature algorithms listed above. The key must be an appropriate private key for the specified scheme.
opts must be a keyword arguments, the procedure ignores unsupported keywords. The supporting keyword arguments and its scheme are below
:digest
For all signature algorithms. Specifying digest algorithm. Most of
the algorithm uses *digest:sha-256* as its default digest algorithm.
:encoder
For *signature:rsa*. Specifying signature encoding, default value
is pkcs1-emsa-pss-encode.
:k-generator
For *signature:dsa* and *signature:ecdsa*. Specifying k generator.
It uses random generator as default value.
:der-encode
For *signature:dsa* and *signature:ecdsa*. Specifying if the result
signature is DER encoded or not. Default value is #t.
:scheme
For *signature:eddsa*. Specifying EdDSA scheme.
:context
For *signature:eddsa* *signature:ed25519ctx*, *signature:ed25519ph*,
*signature:ed448*, and *signature:ed448ph*.
Specifying context, default value is #vu8().
For the scheme specific procedures such as k-generator, see the below
sections.
Signs the given message with signer and returns the signature.
signer?
)
Initialises the given signer
Feeds the given message to the signer. The optional arguments specifies the range of the message to feed.
signer?
)
Signs the accumulated message of signer and returns a bytevector.
Returns #t if the given obj is a verifier, otherwise #f.
Creates a verifier of the scheme. The scheme must be one of the signature algorithms listed above. The key must be an appropriate public key for the specified scheme.
opts must be a keyword arguments, the procedure ignores unsupported keywords. The supporting keyword arguments and its scheme are below
:digest
For all signature algorithms. Specifying digest algorithm. Most of
the algorithm uses *digest:sha-256* as its default digest algorithm.
:verifier
For *signature:rsa*. Specifying signature encoding, default value
is pkcs1-emsa-pss-verify.
:der-encode
For *signature:dsa* and *signature:ecdsa*. Specifying if the result
signature is DER encoded or not. Default value is #t.
:scheme
For *signature:eddsa*. Specifying EdDSA scheme.
:context
For *signature:eddsa* *signature:ed25519ctx*, *signature:ed25519ph*,
*signature:ed448*, and *signature:ed448ph*.
Specifying context, default value is #vu8().
verifier?
) (
message
bytevector?
) (
signature
bytevector?
)
Verifies if the given signature is valid signature of the given message with verifier.
It returns #t if the given signature is a valid signature.
If the signature verification is failed, then returns #f.
If the signature format is not valid, then raise an error.
Initialises the given verifier.
Feeds the given message to the verifier. The optional arguments specifies the range of the message to feed.
Verifies the given signature against the accumulated messgage.
It returns #t if the given signature is a valid signature.
If the signature verification is failed, then returns #f.
If the signature format is not valid, then raise an error.
These procedures are RSA signature specific, i.e. :encoder and :verifier
keyword arguments, the keyword arguments specified in these procedures
are passed via either make-signer or make-verifier.
PKCS#1 EMSA PSS encode. The keyword arguments specifies its salt, MGF and digest algorithm of the MGF.
PKCS#1 EMSA PSS verify. The keyword arguments specifies its salt, MGF and digest algorithm of the MGF.
PKCS#1 EMSA PKCS1-v1_5 encode.
PKCS#1 EMSA PKCS1-v1_5 verify.
MGF1 function, the same as the one exported from (sagittarius crypto ciphers).
Creates a random k-generator.
Creates a RFC 6979 determistic k-generator.
The below bindings are string representaion of OIDs which can be used
to create X.509 algorithm identifier, i.e. make-x509-algorithm-identifier,
described in X.509 library.
The name must be descriptive enough to see which algorithm of OID it represents.
The Message Authentication Code, MAC, library provides MAC generation / verification operations.
The MAC library, this library exports the procedures listed below sections.
Below are the MAC algorithms supported by the library.
Returns #t if the given obj is MAC object, otherwise #f.
Creates a MAC object of algorithm type.
key must be an appropriate shared secret per type. At this moment,
all the algorithms require bytevector.
mac?
)
Returns the type of given mac.
mac?
)
Returns MAC size of the given mac, if the MAC size is fixed,
otherwise #f.
Only KMAC is variable length.
mac?
)
Returns OID of the mac, if it has, otherwise #f.
Generates MAC of given message by mac.
Optional argument length specifies the length of returning bytevector.
NOTE: length doesn't guarantee the bytevector is filled with MAC. If the MAC size is shorter than length, then excess values are filled with 0.
mac?
) (
message
bytevector?
) (
out
bytevector?
) :optional
start
length
Generates MAC of given message by mac and fills it in the out from position start to length count.
Verifies if the given auth-mac is MAC of message by mac and returns #t
if the MAC is verified, otherwise signals an error.
mac?
)
Initialises the given mac. If this procedure is called during the message processing, then the previous state will be reset.
Processes the given message with mac.
Optional arguments specifies the range of message to be processed.
Generates MAC by mac and fills it into the out from position _start to length count.
The X.509 library provides X.509 certificate, CRL, CSR and some other related operations.
The X.509 library, this library exports the procedures listed below sections.
Returns #t if the given obj is X.509 certificate, otherwise #f.
Converts the given bytevector bv to X.509 certificate. The bytevector must be a valid X.509 certificate structure otherwise an error is signalled.
Reads X.509 certificate from the given binary input port bin. The data must be a valid X.509 certificate structure otherwise an error is signalled.
Converts the given X.509 certificate certificate to a bytevector.
Writes the given X.509 certificate into out if specified, otherwise
(current-output-port).
Checks if the given X.509 certificate is expired on the given when
if specified, otherwise (current-date).
Retrieves IssuerDn of the given certificate as X.509 name.
Retrieves SubjectDn of the given certificate as X.509 name.
Retrieves public key of the given certificate.
Retrieves validity of the given certificate as X.509 validity.
Retrieves serial number of the given certificate.
Retrieves version of the given certificate.
The returning value indicates the version number, for example,
v1 certificate then the procedure returns 1.
Retrieves signature of the given certificate.
Retrieves signature algorithm of the given certificate as X.509 algorithm identifier.
Retrieves extensions of the given certificate as a list of X.509 extension.
Validates the given certificate against the given validator.
validator must be a procedure accepts one argument, certificate.
Creates a signature validator.
Creates a validity validator.
Optional argument when specifies in which period of time the certificate
validity. Default value is (current-date).
x509-certificate?
) (
ca-certificate
x509-certificate?
)
Returns t if the given certificate is signed by the ca-certificate,
otherwise #t.
Checks if the given certificate is revoked on the given crl.
If the optional argument date is provided, then the procedure checks on
the given date. Default value is (current-date).
Returns #t if the given obj is X.509 certificate template, otherwise #f.
Builds an X.509 certificate template. field and its value must be one or more of the followings:
issuer-dn
X.509 name, represents IssuerDn. Required.
subject-dn
X.509 name, represents SubjectDn. Required.
serial-number
Integer, represents serial number. Required.
not-before
Date, represents not before. Required.
not-after
Date, represents not after. Required.
public-key
Public key of the certificate. Required.
issuer-unique-id
Bytevector, represents issuer unique Id. Optional.
subject-unique-id
Bytevector, represents subject unique Id. Optional.
extentions
List of X.509 extensions. Optional.
Signs the given template with aid algorithm and private-key, then returns X.509 certificate.
Returns #t if the given obj is X.509 certificate, otherwise #f.
Converts the given bytevector bv to X.509 CSR. The bytevector must be a valid X.509 CSR otherwise an error is signalled.
Reads X.509 CSR from the given binary input port bin. The data must be a valid X.509 CSR structure otherwise an error is signalled.
Converts the given X.509 CSR csr to a bytevector.
Writes the given X.509 CSR into out if specified, otherwise
(current-output-port).
Retrieves version of the given csr.
The returning value indicates the version number, for example,
v1 certificate then the procedure returns 1.
Retrieves SubjectDn of the given csr as X.509 name.
Retrieves public key of the given csr.
Retrieves list of attributes of the given csr as list of X.509 attributes.
Retrieves signature of the given csr.
Retrieves signature algorithm of the given csr as X.509 algorithm identifier.
Validates the given csr against the given validator.
validator must be a procedure accepts one argument, csr.
X.509 CSR signature validator. It validates the signature of the target X.509 CSR.
Returns #t if the given obj is X.509 CSR template, otherwise #f.
Builds an X.509 CSR template. field and its value must be one or more of the followings:
subject-dn
X.509 name, represents SubjectDn. Required.
attributes
List of X.509 attributes. Optional.
Signs the given template with aid algorithm and the private key of
the signing-key-pair, then returns X.509 CSR.
The returning X.509 CSR contains the public key of the signing-key-pair.
Returns #t if the given obj is X.509 CRL, otherwise #f.
Converts the given bytevector bv to X.509 CRL. The bytevector must be a valid X.509 CRL structure otherwise an error is signalled.
Reads X.509 CRL from the given binary input port bin. The data must be a valid X.509 CRL structure otherwise an error is signalled.
Converts the given X.509 CRL crl to a bytevector.
x509-certificate-revocation-list?
) :optional
out
Writes the given X.509 CRL into out if specified, otherwise
(current-output-port).
Retrieves IssuerDn of the given crl as X.509 name.
Retrieves this update of the given crl as date.
Retrieves next update of the given crl as date.
x509-certificate-revocation-list?
)
Retrieves X.509 revoked certificate of the given crl as list.
Retrieves X.509 extensions of the given crl as X.509 extension list.
x509-certificate-revocation-list?
)
Retrieves signature algorithm the given crl as X.509 algorithm identifier.
Retrieves signature of the given crl.
x509-certificate-revocation-list?
)
validator
...
Validates the given crl with the given validator, if the validation failed, then the procedure signals an error.
Creates a X.509 CRL validator which verifies the signature with the given public-key.
Creates a X.509 CRL validator which checks if the issuer DN is issuer or not.
Returns #t if the given obj is X.509 revoked certificate, otherwise #f.
Creates a X.509 revoked certificate.
Retrieves serial number of the given rc.
Retrieves revocation date of the given rc as date.
Retrieves CRL entry extensions of the given rc as X.509 extension list.
Returns #t if the given obj is X.509 CRL template, otherwise #f.
Builds an X.509 CRL template. field and its value must be one or more of the followings:
issuer-dn
X.509 name, represents IssuerDn. Required.
this-update
Date, represents this update. Required.
next-update
Date, represents next update. Optional.
revoked-certificate
A list of X.509 revoked certificate, represents revoked certificates. Required.
crl-extensions
A list of X.509 extensions, represents CRL extensions. Optional.
Signs the given template with aid algorithm and private-key, then returns X.509 CRL.
Returns #t if the given obj is X.509 name, otherwise #f.
Creates X.509 name from the given components.
A component must be a list of either:
Symbol representation of well-known name, such as CN, and string value
Or string representation of OID and string value.
Below are the supported symbols:
CN
Common name
L
Locality name
ST
State or province name
O
Origanisation name
OU
Origanisation unit name
STREET
Street address
DC
Domain component
UID
User ID
Name
Name
SURNAME
Surname
GIVENNAME
Given name
T
Title
DN
DN qualifier
SERIALNUMBER
Serial number
Pseudonym
Pseudonym
E
Email address
Converts given name to string representation.
Converts given dn to X509 names.
Returns #t if the given obj is X.509 validity, otherwise #f.
Creates a X.509 validity of the range of not-after and not-after.
Retrieves not before of validity as date.
Retrieves not after of validity as date.
returns #t if the given obj is x.509 algorithm identifier,
otherwise #f.
oid must be a valid string representaion of oid.
creates a x.509 algorithm identifier of _oid.
if optional parameter is passed, then it has to be a valid x.509 algorithm
identifier parameter.
Retrieves OID of aid.
Retrieves parameters of aid.
returns #t if the given obj is subject public key info, otherwise #f.
Converts given spki to a public key.
Converts given public-key to a subject public key info.
Converts given bv to a subject public key info.
The bytevector must be a valid SubjectPublicKeyInfo structure. Otherwise,
an error is signalled.
Converts given spki to a bytevector.
Returns #t if the given obj is X.509 attribute, otherwise #f.
Retrieves type of the attr.
Retrieves values of the attr. The retrieved value may not be usable as it is.
oid must be a string representaion of OID or object identifier.
Returns a predicate for a X.509 attribute list. The predicate
checks if the given X.509 attribute has oid or not.
Creates PKCS#9 challenge password attribute of the value password.
x509-extension must be X.509 extension.
Creates PKCS#9 extension request attribute of the value x509-extensions.
Converts PKCS#9 extension request attribute to list of X.509 extensions.
If the attr does not have appropriate attribute type, the procedure
signals an error.
The above object identifiers can be use for x509-attribute-of procedure.
Returns #t if the given obj is X.509 extension, otherwise #f.
Retrieves id of the ext.
Retrieves critical of the ext.
Retrieves value of the ext.
Object identifiers of X.509 extension. The name must be descritive enough to see which extension's OID it is.
oid must be a string representaion of OID or object identifier.
Creates a predicate for a list of X.509 extensions.
The keystore library provides keystore operation. More precisely, PKCS#12.
PKCS#12 keystore is very flexible format, and there's no standard convension, but just de-fact. For example, PKCS#12 itself doesn't require the entry to be key/value, however most of the existing library uses the format as key/value map.
This library provides the de-fact convension layer. If you want to
use raw PKCS#12 format, see (sagittarius crypto pkcs keystore).
The keystore library, this library exports the procedures listed blow sections.
Returns #t if the given obj is PKCS#12 keystore, otherwise #f.
Creates an empty PKCS#12 keystore.
Reads PKCS#12 keystore from in, if provided, otherwise (current-input-port).
The password must be a valid password for the reading PKCS#12, otherwise an error is signalled.
Converts given bv to PKCS#12 keystore.
The password must be a valid password for the reading PKCS#12, otherwise an error is signalled.
Converts the given ks to a bytevector using the given password as both integrity and privacy exchange key.
Writes the given ks to out if provided, otherwise (current-output-port),
using the given password as both integrity and privacy exchange key.
pkcs12-keystore?
) (
alias
string?
) (
password
string?
)
Retrieves a private key associated to alias from ks decrypting with the given password.
If the alias doesn't exist in the ks, then returns #f.
certs must be a list of X.509 certificates.
Stores the given key into the ks associating with alias. The key is encrypted with the password.
The certs must be a valid (chain) certificate(s) for the given key.
Retrieves a certificate associated to alias from ks.
If the alias doesn't exist in the ks, then returns #f.
Stores the given cert into the given ks associating with alias.
Retrieves certificate chain associated to alias from the ks.
If there's no certificate associated to alias, then it returns ().
Removes the entry associated to alias from the ks.
Removes all entries from the ks.
The KDF, Key Derivation Function, library provides various KDF algorithms.
The KDF library, this library exports the procedures listed below sections.
_P_and S must be bytevectors.
c and dk-len must be non-negative integers.
PBKDF1
_P_and S must be bytevectors.
c and dk-len must be non-negative integers.
PBKDF2
scheme must be a MAC scheme, e.g. *mac:hmac*.
Provides a PRF generator which accepts S, secret,
based on the given scheme.
The opts will be passed to the MAC generation.
HKDF
PKCS12 KDF