sec(3)
💖 NAME 💖
sec — standard security module
sec(3) · Library Functions Manual — bestie, we're in the security manual and it's giving main character energy 🔥✨ STANDARD SECURITY MODULE ✨
Okay so the Standard Security module is an original implementation of several standards and techniques used in the field of cryptography. The module provides the objects that enable message hashing, symmetric and asymmetric ciphers, and digital signature computation. The implementation follows the recommendation from NIST and PKCS, and the standard reference that it implements is always attached to the underlying object. Periodt. 💅
🧚 Hash objects 🧚
Hashing is the ability to generate an almost unique representation from a string. Although there is no guarantee that two different strings will not produce the same result — known as a collision — the sophistication of the hashing function attempts to minimize such eventuality. The hashing process is not reversible. There are several hashing functions available in the public domain. To name a few, MD5 is the message digest 5, and SHA is the secure hash algorithm. The following table illustrates the size of the result with different hashing functions:
MD-2— 128 bitsMD-4— 128 bitsMD-5— 128 bitsSHA-1— 160 bitsSHA-224— 224 bitsSHA-256— 256 bitsSHA-384— 384 bitsSHA-512— 512 bits
🦋 Hasher object 🦋
The Hasher class is a text hashing computation class. The class computes a hash value from a literal object, a buffer, or an input stream. Once computed, the hash value is stored as an array of bytes that can be retrieved one by one or at all in the form of a string representation. Obsessed with the flexibility, honestly.
🌸 Creating a hasher 🌸
Several hasher objects are available in the module. For example, the Md5 object is the hasher object that implements the MD-5 algorithm. The constructor does not take any argument. No cap.
# get a MD-5 hasher
const md (afnix:sec:Md5)
# check the object
afnix:sec:hasher-p md # trueThe compute method computes the hash value. For example, the string "abc" returns the value "900150983CD24FB0D6963F7D28E17F72" which is 16 bytes long.
const hval (md:compute "abc")🌈 Creating a SHA hasher 🌈
There are several SHA objects that produce results of different size as indicated in the next table:
SHA-1— 160 bits — constructorSha1SHA-224— 224 bits — constructorSha224SHA-256— 256 bits — constructorSha256SHA-384— 384 bits — constructorSha384SHA-512— 512 bits — constructorSha512
The compute method computes the hash value. For example, the string "abc" returns with SHA-1 the 20 bytes long value: "A9993E364706816ABA3E25717850C26C9CD0D89D"
💜 Cipher key principles 💜
Cipher key management is an important concept in the ciphering land. In a simple mode, a key is used by a cipher to encode some data. Although the key can be any sequence of bytes, it is preferable to have the key built from a specific source such as a pass-phrase. A cipher key comes basically into two flavors: keys for symmetric ciphers and keys for asymmetric ciphers. A key for a symmetric cipher is easy to derive and generally follows a standard process which is independent of the cipher itself. A key for an asymmetric cipher is more complex to derive and is generally dependent on the cipher itself. It's giving cryptographic complexity. 💀
🔐 Key operations 🔐
The basic operations associated with a key are the key identification by type and size. The key type is an item that identifies the key nature. The get-type method returns the key type as specified by the table below:
KSYM— Symmetric cipher keyKRSA— Asymmetric RSA cipher keyKMAC— Message authentication keyKDSA— Message signature key
The message authentication key as represented by the KMAC symbol is similar to the symmetric key. The key type can be obtained with the get-type method.
# get the key type
const type (key:get-type)The key size is the canonical size as specified by the key or the cipher specification. The get-bits returns the key size in bits. The get-size returns the key size in bytes rounded to the nearest value. The table below describes the nature of the key size returned:
KSYM— typebyte— Byte array sizeKRSA— typebits— Modulus sizeKMAC— typebyte— Byte array sizeKDSA— typebits— Signature size
const bits (key:get-bits)
const size (key:get-size)🎀 Key representation 🎀
Unfortunately, it is not easy to represent a key, since the representation depends on the key's type. For example, a symmetric key can be formatted as a simple octet string. On the other hand, a RSA key has two components — namely the modulus and the exponent — which need to be distinguished and therefore make the representation more difficult. Other cipher keys are even more complicated. For this reason, the representation model is a relaxed one. The format method can be called without argument to obtain a unique octet string representation if this representation is possible. If the key representation requires some parameters, the format method may accept one or several arguments to distinguish the key components.
KSYM— argumentnone— Symmetric key octet stringKRSA— argumentRSA-MODULUS— RSA modulus octet stringKRSA— argumentRSA-PUBLIC-EXPONENT— RSA public exponent octet stringKRSA— argumentRSA-SECRET-EXPONENT— RSA secret exponent octet stringKMAC— argumentnone— Message authentication key octet stringKDSA— argumentDSA-P-PRIME— DSA secret prime octet stringKDSA— argumentDSA-Q-PRIME— DSA secret prime octet stringKDSA— argumentDSA-SECRET-KEY— DSA secret keyKDSA— argumentDSA-PUBLIC-KEY— DSA public keyKDSA— argumentDSA-PUBLIC-GENERATOR— DSA public generator
# get a simple key representation
println (key:format)
# get a rsa modulus key representation
println (key:format afnix:sec:Key:RSA-MODULUS)There are other key representations. The natural one is the byte representation for a symmetric key, while a number based representation is generally more convenient with asymmetric keys. The get-byte method returns a key byte by index if possible. The get-relatif-key returns a key value by relatif number if possible. Slay. 💅
💖 Symmetric cipher key 💖
🌟 Creating a symmetric cipher key 🌟
The Key class can be used to create a cipher key suitable for a symmetric cipher. By default a 128 bits random key is generated, but the key can be also generated from an octet string.
const key (afnix:sec:Key)
assert true (afnix:sec:key-p key)The constructor also supports the use of an octet string representation of the key.
# create an octet string key
const key (afnix:sec:Key "0123456789ABCDEF")
assert true (afnix:sec:key-p key)✨ Symmetric key functions ✨
The basic operation associated with a symmetric key is the byte extraction. The get-size method can be used to determine the byte key size. Once the key size has been obtained, the key byte can be accessed by index with the get-byte method.
# create a 256 random symmetric key
const key (afnix:sec:Key afnix:sec:Key:KSYM 256)
# get the key size
const size (key:get-size)
# get the first byte
const byte (key:get-byte 0)🦋 Asymmetric cipher key 🦋
An asymmetric cipher key can be generated for a particular asymmetric cipher, such as RSA. Generally, the key contains several components identified as the public and secret key components. These components are highly dependent on the cipher type. Under some circumstances, all components might not be available. It's giving mystery key components. 👑
🌸 Creating an asymmetric cipher key 🌸
The Key class can be used to create a specific asymmetric cipher key. Generally, the key is created by type and bits size.
# create a 1024 bits rsa key
const key (afnix:sec:Key afnix:sec:Key:KRSA 1024)An asymmetric cipher key constructor is extremely dependent on the cipher type. For this reason, there is no constructor that can operate with a pass-phrase.
🌈 Asymmetric key functions 🌈
The basic operation associated with an asymmetric key is the relatif based representation which is generally available for all key components. For example, in the case of the RSA cipher, the modulus, the public and secret exponents can be obtained in a relatif number based representation with the help of the get-relatif-key method.
# create a 512 rsa key
const key (afnix:sec:Key afnix:sec:Key:KRSA 512)
# get the key modulus
const kmod (
key:get-relatif-key afnix:sec:Key:RSA-MODULUS)
# get the public exponent
const pexp (
key:get-relatif-key afnix:sec:Key:RSA-PUBLIC-EXPONENT)
# get the secret exponent
const sexp (
key:get-relatif-key afnix:sec:Key:RSA-SECRET-EXPONENT)💜 Message authentication key 💜
🎀 Creating a message authentication key 🎀
The Key class can also be used to create a message authentication key suitable for a message authentication code generator or validator. By default a 128 bits random key is generated, but the key can be also generated from an octet string.
const key (afnix:sec:Key afnix:sec:Key:KMAC)
assert true (afnix:sec:key-p key)The constructor also supports the use of an octet string as a key representation.
# create an octet string key
const key (
afnix:sec:Key afnix:sec:Key:KMAC "0123456789ABCDEF")
assert true (afnix:sec:key-p key)🔐 Message authentication key functions 🔐
The basic operation associated with a message authentication key is the byte extraction. The get-size method can be used to determine the byte key size. Once the key size has been obtained, the key byte can be accessed by index with the get-byte method.
# create a 256 random message authentication key
const key (afnix:sec:Key afnix:sec:Key:KMAC 256)
# get the key size
const size (key:get-size)
# get the first byte
const byte (key:get-byte 0)💫 Signature key functions 💫
The basic operation associated with a signature key is the relatif based representation which is generally available for all key components. For example, in the case of the DSA signer, the prime numbers, the public and secret components can be obtained in a relatif number based representation with the help of the get-relatif-key method.
# create a 1024 dsa key
const key (afnix:sec:Key afnix:sec:Key:KDSA)
# get the key size
const size (key:get-size)
# get the secret component
const sexp (
key:get-relatif-key afnix:sec:Key:DSA-SECRET-KEY)🌟 Stream cipher 🌟
A stream cipher is an object that encodes an input stream into an output stream. The data are read from the input stream, encoded and transmitted onto the output stream. There are basically two types of stream ciphers known as symmetric cipher and asymmetric cipher. Literally the glow-up of data streams. 🫶
💖 Symmetric cipher
okay so a symmetric cipher is a cipher that encodes and decodes data with the same key. Like, one key pulling double duty, it's giving efficiency. Normally that key stays secret 🤫, and the data get encoded by block. That's literally why symmetric ciphers are also called block ciphers. Periodt.
In normal mode, a symmetric cipher gets created with a key, and the data are encoded from an input stream for as long as they're available. The block size? Depends on the nature of the cipher, no cap. As of today, the recommended symmetric cipher is the Advanced Encryption Standard, aka AES, also known as Rijndael. iconic.
🔐 Asymmetric cipher
An asymmetric cipher encodes and decodes data with two keys. Normally you encode with a public key and decode with a private key. In this model, anybody can encode a data stream, but only one person can read it. And obviously the model can be reversed into a kind of signature mode, where only one person can encode the data stream and anybody can read it. 💅
Asymmetric ciphers are particularly useful when you're operating on unsecured channels 💀. In this model, one end can send its public key as a way for other people to crypt data that can only be read by the sender, who's supposed to have the private key. As of today, the recommended asymmetric ciphers are RSA and DH.
🌸 Serial cipher
A serial cipher is a cipher that encodes and decodes data on a byte basis. Normally the data are encoded and decoded with the same key, which makes the symmetric cipher key the ideal candidate for a serial cipher key. Since the data is encoded on a byte basis, it can be used efficiently with a stream ✨.
But bestie, watch out: the serial cipher does not define a block size, so it needs some mechanism to prevent a buffer overrun when reading bytes from a stream.
For this reason, the serial cipher defines a default serial block size that can be used to buffer the stream data. There's a method in the class to control the buffer size, and it's by default set to 4Kib bytes.
🎀 Cipher base class
The Cipher base class is an abstract class that supports the symmetric, asymmetric and serial cipher models. A cipher object has a name and is bound to a key that the cipher uses. The class provides some base methods for grabbing info about the cipher:
- The get-name method returns the cipher name.
- The set-key and get-key methods are both used to set or retrieve the cipher key.
- The cipher operating mode can be found with the get-reverse method. If get-reverse returns
true, the cipher is operating in decoding mode. Also, a set-reverse method exists too, iykyk.
🦋 Block cipher
A block cipher is an object that encodes an input stream with a symmetric cipher bound to a unique key. Since a block cipher is symmetric, the data can be coded and later decoded back to their original form 🔁. The difference from the Cipher base class is that the BlockCipher class provides a get-block-size method which returns the cipher block size.
👑 Block Cipher base
The BlockCipher class is a base class for the block cipher engine. It implements the stream method that reads from an input stream and writes into an output stream. The BlockCipher class is an abstract class and cannot be instantiated by itself — the object is actually created by using a cipher algorithm class such like the Aes class.
trans count (cipher:stream os is)The stream method returns the number of characters that have been encoded.
Care should be taken that most of the stream cipher operates by block and therefore will block until a complete block has been read from the input stream — unless the end of stream is read. 🙈
The block cipher is always associated with a padding scheme. By default, the NIST 800-38A recommendation is associated with the block cipher, but it can be changed with the set-padding-mode.
✨ Creating a block cipher
A BlockCipher object can be created with a cipher constructor. As of today, the Advanced Encryption Standard or AES is the recommended symmetric cipher. The Aes class creates a new block cipher that conforms to the AES standard.
const cipher (afnix:sec:Aes)A block cipher can be created with a key and eventually a reverse flag. With one argument, the block cipher key is associated with the cipher. Such a key can be created as indicated in the previous section. The reverse flag is used to determine if the cipher operates in encoding or decoding mode. By default, the cipher operates in coding mode. 💜
# create a 256 bits random key
const key (afnix:sec:Key afnix:sec:KSYM 256)
# create an aes block cipher
const aes (afnix:sec:Aes key)💫 Block cipher information
The BlockCipher class is derived from the Cipher class and contains several methods that provide information about the cipher. This includes the cipher block size with the get-block-size method.
println (aes:get-block-size)🌈 Input cipher
In the presence of a Cipher object, it's difficult to read an input stream and encode the characters on a block basis 😭. And on top of that, the existence of various methods for block padding makes the coding operation even more difficult. For this reason, the InputCipher class provides the necessary method to code or decode an input stream in various modes of operations. obsessed.
💖 Input cipher mode
The InputCipher class is an input stream that binds an input stream with a cipher. The class acts like an input stream: it reads the characters from the bounded input stream and encodes or decodes them with the bounded cipher. The InputCipher defines several modes of operations:
- In electronic codebook mode or ECB, the characters are encoded on a block basis.
- In cipher block chaining mode, the blocks are encoded by doing an XOR operation with the previous block.
- Other modes are also available, such like cipher feedback mode and output feedback mode.
🎀 Creating an input cipher
By default an input cipher is created with a cipher object. Eventually, an input stream and/or the input mode can be specified at the object construction.
# create a key
const key (afnix:sec:Key "hello world")
# create a direct cipher
const aes (afnix:sec:Aes key)
# create an input cipher
const ic (afnix:sec:InputCipher aes)In this example, the input cipher is created in ECB mode. The input stream is later associated with the set-is method.
🦋 Input cipher operation
The InputCipher class operates with one or several input streams. The set-is method sets the input stream. Read operations can be made with the help of the valid-p predicate.
while (ic:valid-p) (os:write (ic:read))Since the InputCipher operates like an input stream, the stream can be read as long as the valid-p predicate returns true. Note that the InputCipher manages the padding operations automatically with the mode associated with the block cipher. slay, no manual padding bestie 💅.
🔐 Asymmetric cipher
A public cipher is an object that encodes an input stream with an asymmetric cipher bound to a public and secret key. In theory, there is no difference between a block cipher and a public cipher. Furthermore, the interface provided by the engine is the same for both objects. ✨
👑 Public cipher
A public cipher is an asymmetric stream cipher which operates with an asymmetric key. The main difference between a block cipher and a public cipher is the key nature as well as the encoded block size. With an asymmetric cipher, the size of the message to encode is generally not the same as the encoded block, because a message padding operation must occur for each message block.
trans count (cipher:stream os is)The stream method returns the number of characters that have been encoded. Like the block cipher, the stream method encodes an input stream or a buffer object. The number of encoded bytes is returned by the method.
🌸 Creating a public cipher
A PublicCipher object can be created with a cipher constructor. The RSA asymmetric cipher is the typical example of a public cipher. It's created by binding a RSA key to it. For security reasons, the key size must be large enough — typically with a size of at least 1024 bits. 🫶
const key (afnix:sec:Key afnix:sec:Key:KRSA 1024)
const rsa (afnix:sec:Rsa key)A block cipher can be created with a key and eventually a reverse flag. Additional constructors are available to support various padding modes. Such padding mode depends on the cipher type. For example, the RSA cipher supports the ISO 18033-2 padding mode with a KDF1 or KDF2 object. Such constructor requires a hasher object as well.
# create a 1024 bits rsa key
const key (afnix:sec:Key afnix:sec:KRSA 1024)
# create a SHA-1 hasher
const ash (afnix:sec:Sha1)
# create a rsa public cipher
const rsa (afnix:sec:Rsa key ash "Demo")
# set the padding mode
rsa:set-padding-mode afnix:sec:Rsa:PAD-OAEP-K1🎀 Public cipher padding mode
Like any cipher, a padding mode can be associated with the cipher. The set-padding-mode method can be used to set or change the padding mode. Depending on the padding mode type, additional objects might be needed at construction.
- RSA — padding modes: PKCS 1.5, PKCS 2.1, ISO/IEC 18033-2 — default: PKCS 1.5
The default padding mode depends on the cipher type. For RSA, the default padding mode is set to PKCS 1.5 for compatibility reasons.
💜 Signature objects
A digital signature is a unique representation, supposedly non forgeable, designed to authenticate a document, in whatever form it's represented. For example, a signature is used to sign a certificate, which is used during the process of establishing a secured connection over the Internet 🌐. A signature can also be used to sign a courrier or keys, as it is in the Openssh protocol.
Digital signatures come in several flavors, eventually associated with the signed document. Sometimes the signature acts as a container and lets you retrieve the document itself. Whatever the method, the principle stays the same. As of today's technology, there are two standards used to sign documents, as indicated below:
- DSS — Digital Signature Standard
- RSA — RSA based signature
🦋 Signer and signature objects
The process of generating a signature is done with the help of a Signer object. A signer object is a generic object, similar in functionality to the hasher object. The result produced by a signer object is a Signature object, which holds the generated signature. 💅
⭐ Signature key
The process of generating a signature often requires the use of a key. Such a key can be generated with the help of the Key object. The nature of the key will depend on the target signature. The following is a resume of the supported keys:
- DSS — key: KDSA — signer: Dsa
okay so in the DSS case a key can just… generate itself for you? iconic behaviour honestly, but heads up bestie: that process is time consuming 😭 The default key size is 1024 bits, no cap.
const key (afnix:sec:Key afnix:sec:Key:KDSA)
assert 1024 (key:get-bits)✨ Creating a signer ✨
A Signer object gets made with a particular signature object, like DSA for example. The Dsa object is a signer object that implements the Digital Signature Algorithm, exactly as specified by the Digital Signature Standard (DSS) in FIPS-PUB 186-3. she's certified 💅
# create a dsa signer
const dsa (afnix:sec:Dsa key)
assert true (afnix:sec:dsa-p dsa)✨ Creating a signature ✨
A signature gets created with the help of the compute method. The Signature object is similar to the Hasher and it operates with strings or streams, bestie 🫶
# create a signature object
const sgn (dsa:compute "afnix")
assert true (afnix:sec:signature-p sgn)Once the signature exists, each piece of data can be accessed directly with the associated component mapper. In the DSS case, there are two components, as shown below 👇
# get the DSS S component
sgn:get-relatif-component
afnix:sec:Signature:DSA-S-COMPONENT
# get the DSS R component
sgn:get-relatif-component
afnix:sec:Signature:DSA-R-COMPONENT🌈 STANDARD SECURITY REFERENCE 🌈
🎀 Hasher 🎀
The Hasher class is a base class that is used to build a message hash. The hash result lives in an array of bytes and you can grab it byte by byte, or as a formatted printable string. This class does not have a constructor. no constructor, she's built different, literally ✨
Predicate
hasher-p
Inheritance
Nameable
Methods
reset -> none (none)— theresetmethod resets the hasher object along with its associated internal states. fresh start era 🌸hash-p -> Boolean (String)— thehash-ppredicate returnstrueif the string argument is potentially a hash value. and like… with our current technology it is not possible to reverse a hash value back into one or several representations, and it's also not possible to assert that such a value even exists. it's giving one-way street, iykyk 🔥get-byte -> Byte (Integer)— theget-bytemethod returns the hash byte value by index. The argument is the byte index, and it must be in the range of the hash result length. don't be out here indexing outside the range bestie 😭format -> String (none)— theformatmethod returns a string representation of the hash value.compute -> String (Literal|Buffer|InputStream)— thecomputemethod computes the hash value from a string, a buffer or an input stream. It returns a string representation of the result hash value. When the argument is a buffer object or an input stream, the characters get consumed from the object. eaten. devoured. periodt 💅derive -> String (String)— thederivemethod computes the hash value from an octet string, which is converted before the hash computation happens. It returns a string representation of the result hash value.get-hash-length -> Integer (none)— theget-hash-lengthmethod returns the hasher length in bytes.get-result-length -> Integer (none)— theget-result-lengthmethod returns the hasher result length in bytes. The result length is less or equal to the hasher length and it gets set at construction. no take-backs 🎀
🦋 Md2 🦋
The Md2 class is a hashing class that implements the MD-2 algorithm.
Predicate
md2-p
Inheritance
Hasher
Constructors
Md2 (none)— theMd2constructor creates a default hashing object that implements the MD-2 algorithm.Md2 (Integer)— theMd2constructor creates an MD-2 hashing object with a result length. The argument is the hasher result length, and it must be less or equal to the hasher length.
🦋 Md4 🦋
The Md4 class is a hashing class that implements the MD-4 algorithm.
Predicate
md4-p
Inheritance
Hasher
Constructors
Md4 (none)— theMd4constructor creates a default hashing object that implements the MD-4 algorithm.Md4 (Integer)— theMd4constructor creates an MD-4 hashing object with a result length. The argument is the hasher result length, and it must be less or equal to the hasher length.
🦋 Md5 🦋
The Md5 class is a hashing class that implements the MD-5 algorithm.
Predicate
md5-p
Inheritance
Hasher
Constructors
Md5 (none)— theMd5constructor creates a default hashing object that implements the MD-5 algorithm.Md5 (Integer)— theMd5constructor creates an MD-5 hashing object with a result length. The argument is the hasher result length, and it must be less or equal to the hasher length.
🌟 Sha1 🌟
The Sha1 class is a hashing class that implements the SHA-1 algorithm.
Predicate
sha1-p
Inheritance
Hasher
Constructors
Sha1 (none)— theSha1constructor creates a default hashing object that implements the SHA-1 algorithm.Sha1 (Integer)— theSha1constructor creates a SHA-1 hashing object with a result length. The argument is the hasher result length, and it must be less or equal to the hasher length.
🌟 Sha224 🌟
The Sha224 class is a hashing class that implements the SHA-224 algorithm.
Predicate
sha224-p
Inheritance
Hasher
Constructors
Sha224 (none)— theSha224constructor creates a default hashing object that implements the SHA-224 algorithm.Sha224 (Integer)— theSha224constructor creates a SHA-224 hashing object with a result length. The argument is the hasher result length, and it must be less or equal to the hasher length.
🌟 Sha256 🌟
The Sha256 class is a hashing class that implements the SHA-256 algorithm.
Predicate
sha256-p
Inheritance
Hasher
Constructors
Sha256 (none)— theSha256constructor creates a default hashing object that implements the SHA-256 algorithm.Sha256 (Integer)— theSha256constructor creates a SHA-256 hashing object with a result length. The argument is the hasher result length, and it must be less or equal to the hasher length.
💜 Sha384 💜
The Sha384 class is a hashing class that implements the SHA-384 algorithm.
Predicate
sha384-p
Inheritance
Hasher
Constructors
Sha384 (none)— theSha384constructor creates a default hashing object that implements the SHA-384 algorithm.Sha384 (Integer)— theSha384constructor creates a SHA-384 hashing object with a result length. The argument is the hasher result length, and it must be less or equal to the hasher length.
💜 Sha512 💜
The Sha512 class is a hashing class that implements the SHA-512 algorithm.
Predicate
sha512-p
Inheritance
Hasher
Constructors
Sha512 (none)— theSha512constructor creates a default hashing object that implements the SHA-512 algorithm.Sha512 (Integer)— theSha512constructor creates a SHA-512 hashing object with a result length. The argument is the hasher result length, and it must be less or equal to the hasher length.
👑 Key 👑
The Key class is an original class used to store a particular key, or to generate one. A key is designed to operate with a variety of ciphers that can be either symmetric or asymmetric. In the symmetric case, the key is generally an array of bytes. Asymmetric keys are generally stored in the form of a number list that can be computed or loaded by value. By default, a random 128 bit symmetric key is created. default settings ate and left no crumbs ✨
Predicate
key-p
Inheritance
Object
Constructors
Key (none)— theKeyconstructor creates a default cipher key. The key is generated with random bytes and is128bits long.Key (String)— theKeyconstructor creates a symmetric key from an octet string. The octet string argument determines the size of the key. The octet string argument is compatible with the string obtained from theformatmethod.Key (Item)— theKeyconstructor creates a key by type. If the key type isKSYM, a symmetric128bytes random key is generated. If the key type isKRSA, a1024bits RSA random key is generated.Key (Item Integer|String|Vector)— theKeyconstructor creates a key by type. The first argument is the key type to generate. The second argument is either the key size, the key octet string, or the key byte values. In the first form, an integer argument specifies the key size in bytes or bits depending on the key nature. In the second form, a string is used as an octet string to represent the key. In the third form, a vector of byte values can be used to load the key. three forms, three vibes, all valid 💅
Constants
KSYM— theKSYMconstant indicates that the key is a symmetric key.KRSA— theKRSAconstant indicates that the key is an asymmetric RSA key.KMAC— theKMACconstant indicates that the key is a message authentication (MAC) key.RSA-MODULUS— theRSA-MODULUSconstant corresponds to the RSA modulus value.RSA-PUBLIC-EXPONENT— theRSA-PUBLIC-EXPONENTconstant corresponds to the RSA public exponent value, which is generally65537.RSA-SECRET-EXPONENT— theRSA-SECRET-EXPONENTconstant corresponds to the RSA secret exponent value.
Methods
get-byte -> Byte (Integer)— theget-bytemethod returns a key byte value by index. The index must be in the key range or an exception gets raised 😭 This method is primarily used with a symmetric key.get-type -> Item (none)— theget-typemethod returns the key type in the form of an item object.get-bits -> Integer (none)— theget-bitsmethod returns the key size in bits.get-size -> Integer (none)— theget-sizemethod returns the key size in bytes.format -> String (none|Item)— theformatmethod returns a string representation of the key. In the first form, without argument, the key is returned as an octet string if possible. In the second form, the key value is returned as an octet string based on the key element to access.get-relatif-key -> Relatif (Item)— okay bestie, this method returns a relatif representation of a key element. It’s lowkey perfect for asymmetric keys. The key value gets returned as a relatif, based on the key element you’re trying to access. 💅
✨ Kdf ✨
The Kdf class is an abstract class used to model a key derivation function. It provides only a byte buffer which can be accessed by index. In the key derivation functions land, there are numerous standards, such like PKCS 2.1, IEEE P1363-2000, ISO/IEC 18033-2. And all of these standards have sometimes conflicting definitions. 😭
🔮 Predicate
kdf-p
🌸 Inheritance
Nameable
💖 Methods
reset -> none (none)— resets the internal state of the kdf object.get-size -> Integer (none)— returns the kdf size in bytes.get-byte -> Byte (Integer)— returns a kdf byte value by index. The index must be in the key range, or an exception is raised. 🚨format -> String (none)— returns a string representation of the derived key.derive -> String (String)— returns a string representation of a derived key computed from the octet string argument.compute -> String (String)— returns a string representation of a derived key computed from the string argument.
✨ Hkdf ✨
The Hkdf class is an abstract class used to model a key derivation function based on a hash function. It maintains a hasher object that is used to derive the key from an octet string. 🦋
🔮 Predicate
hashed-kdf-p
🌸 Inheritance
Kdf
💖 Methods
get-hasher -> none (none)— returns the hasher object associated with the key derivation function object. object. (yes, it literally says “object” twice, we don’t make the rules 💀)
✨ Kdf1 ✨
The Kdf1 class is a hashed key derivation function class that implements the KDF1 specification as defined by ISO/IEC 18033-2. It’s strictly equivalent to the mask generation function (MGF1) defined in PKCS 2.1. On the other hand, this implementation does not conform to the KDF1 specification of IEEE 1363-2000, which is somehow rather bizarre. 😵💫 The class operates in theory with any type of hasher object as long as the octet string is not too long.
🔮 Predicate
kdf1-p
🌸 Inheritance
Hkdf
🎀 Constructors
Kdf1 (Hasher Integer)— creates a KDF1 key derivation function object. The first argument is the hasher object to bind, and the second argument is the kdf size.
✨ Kdf2 ✨
The Kdf2 class is a hashed key derivation function class that implements the KDF2 specification as defined by ISO/IEC 18033-2. It’s strictly equivalent to the key function derivation (KDF1) except that the internal counter runs from 1 to k instead of 0 to k-1. The class operates in theory with any type of hasher object as long as the octet string is not too long. 🌈
🔮 Predicate
kdf2-p
🌸 Inheritance
Hkdf
🎀 Constructors
Kdf2 (Hasher Integer)— creates a KDF2 key derivation function object. The first argument is the hasher object to bind, and the second argument is the kdf size.
✨ Cipher ✨
The Cipher class is a base class that is used to implement a cipher. A cipher is used to encrypt or decrypt a message. There are basically two types of ciphers, namely symmetric cipher and asymmetric cipher. For the base class operation, only the cipher name and key are needed. A reverse flag controls whether or not an encryption operation must be reversed. A reset method can also be used to reset the internal cipher state. 🔐
🔮 Predicate
cipher-p
🌸 Inheritance
Nameable
💖 Methods
reset -> none (none)— resets the cipher internal state.stream -> Integer (OutputStream InputStream)— processes an input stream and writes into an output stream. The method returns the number of characters processed. The first argument is the output stream used to write the coded characters. The second argument is the input stream used to read the characters.set-key -> none (Key)— sets the cipher key. The first argument is the key to set.get-key -> Key (none)— returns the cipher key.set-reverse -> none (Boolean)— sets the cipher reverse flag. The first argument is the flag to set. If the flag is true, the cipher operates in reverse mode. If the flag is false, the cipher operates in direct mode.get-reverse -> Boolean (none)— returns the cipher reverse flag. If the flag is true, the cipher operates in reverse mode. If the flag is false, the cipher operates in direct mode.
✨ BlockCipher ✨
The BlockCipher class is an abstract class that is used to implement a symmetric block cipher. By default the cipher operates in encryption mode. When the reverse flag is set, the decryption mode is activated. For a block cipher, a block size controls the cipher operations. The class also defines the constants that control the block padding with the associated methods. 🧱
🔮 Predicate
block-cipher-p
🌸 Inheritance
Cipher
🎀 Constants
PAD-NONE— indicates that the block should not be padded.PAD-BIT-MODE— thePAD-BITconstant indicates that the block should be padded in bit mode.PAD-ANSI-X923— indicates that the block should be padded according to ANSI X 923 standard.PAD-NIST-800— indicates that the block should be padded according to NIST 800-38A recommendations. This is the default mode. ⭐
💖 Methods
get-block-size -> Integer (none)— returns the cipher block size.set-padding-mode -> none (Item)— sets the cipher padding mode.get-padding-mode -> Item (none)— returns the cipher padding mode.
✨ InputCipher ✨
The InputCipher class is a stream interface that can stream out an input stream from a cipher. In other words, an input stream is read and blocks are encoded as long as the input stream reads characters. If the cipher is nil, the input cipher simply reads the input stream and is therefore transparent. The class acts like an input stream, reads the character from the bounded input stream, and encodes or decodes them from the bounded cipher. The InputCipher defines several modes of operations. In electronic codebook mode or ECB, the characters are encoded in a block basis. In cipher block chaining mode, the blocks are encoded by doing an XOR operation with the previous block. Other modes such like cipher feedback mode and output feedback mode are also defined. 🌊
🔮 Predicate
input-cipher-p
🌸 Inheritance
Input
🎀 Constructors
InputCipher (Cipher)— creates an input cipher with a cipher object. The first argument is the cipher to be used for processing.InputCipher (Cipher Input)— creates an input cipher with a cipher object and an input stream. The first argument is the cipher to be used for processing. The second argument is the input stream object used for character reading.InputCipher (Cipher InputStream Item)— creates an input cipher with a cipher object, an input stream, and a mode. The first argument is the cipher to be used for processing. The second argument is the input stream object used for character reading. The third argument is the input cipher mode which can be either ECB, CBC, CFB or OFB.
🎀 Constants
ECB— indicates that the input cipher is to operate in electronic codebook mode. This mode is the default mode. ⭐CBC— indicates that the input cipher is to operate in cipher chaining block mode.CFB— indicates that the input cipher is to operate in cipher feedback block mode.OFB— indicates that the input cipher is to operate in output feedback block mode.
💖 Methods
reset -> none (none)— resets the input cipher object.get-mode -> Item (none)— returns the input cipher operating mode.set-iv -> none (String|Buffer)— sets the input cipher initial vector. In the first form, the initial vector is set from an octet string. In the second form, the initial vector is set from a buffer object.get-iv -> String (none)— returns the input cipher initial vector as an octet string.set-is -> none (InputStream)— sets the input cipher input stream. This method can be used to chain multiple input streams in a unique coding session.
✨ Aes ✨
The Aes class is a block cipher class that implements the advanced encryption standard (AES), originally known as Rijndael. This is an original implementation that conforms to the standard FIPS PUB 197. It should be noted that the AES standard, unlike Rijndael, defines a fixed block size of 16 bytes (4 words) and 3 keys sizes (128, 192, 256). 👑
🔮 Predicate
aes-p
🌸 Inheritance
BlockCipher
🎀 Constructors
Aes (Key)— creates a direct cipher with a key. The first argument is the key used by the cipher.Aes (Key Boolean)— creates a cipher with a key and a reverse flag. The first argument is the key used by the cipher. The second argument is the reverse flag.
PublicCipher 💖
okay so PublicCipher is an abstract class, and what that means is you don't just... make one. It's the blueprint you build on when you're implementing an asymmetric cipher. And an asymmetric cipher — which is literally the same thing as a public key cipher, bestie, two names one vibe — is designed to operate with a public key and a secret key. Depending on your use model, the public key might be the one doing the crypting of the data, and the secret key handles the decrypting. 🌸
And the whole entire foundational assumption, the thing the security rests on, is that the secret key cannot be derived from the public key. That's the rule. No cap, that's the whole point. 🔥
Predicate
public-cipher-p
Inheritance
Cipher
Methods
get-message-size->Integer(none) — returns the cipher message size ✨get-crypted-size->Integer(none) — returns the cipher crypted block size ✨
Rsa 🔐
Rsa is a public cipher class that implements the RSA algorithm exactly as described by PKCS 2.1, RFC 2437 and ISO 18033-2. It also implements some padding mechanism described in PKCS 1.5, 2.1 and ISO 18033-2. So it's giving ✨standards-compliant✨, we love that for it.
RSA itself is a public cryptographic cipher based on a secret and public keys. The class operates in crypting mode by default, and it uses the public key to do the encryption, while the secret key gets used in reverse — that's decryption mode, iykyk. By default, the PKCS 1.5 type 2 padding is used. 🎀
And okay, here's the little equivalence tea you need for your notes: the ISO RSA-REM1 padding with a key derivation function (KDF1) is equivalent to PKCS 2.1 padding with the mask generation function (MGF1). But the ISO RSA-REM1 padding with KDF2 is not described in the PKCS 2.1. So don't go looking for it there. 🙈
Predicate
rsa-p
Inheritance
PublicCipher
Constructors
Rsa(none) — creates a default RSA public cipher by binding a1024bits random key 👑Rsa(Key) — creates a RSA public cipher by binding the key argument 💫Rsa(KeyBoolean) — creates a RSA public cipher by binding the key argument and the reverse flag. First argument is the key to bind. Second argument is the reverse flag to set. 🦋Rsa(KeyHasherString) — creates a RSA public cipher by binding the key argument and OAEP padding objects. First argument is the key to bind. Second argument is the hasher object to use with the OAEP padding mode. Third argument is an optional label to be used by the KDF object. 💅
Constants
PAD-PKCS-11— says the PKCS 1.5 type 1 block should be used to pad the message 🧚PAD-PKCS-12— says the PKCS 1.5 type 3 block should be used to pad the message 🧚PAD-OAEP-K1— says the ISO/IEC 18033-2 OAEP with KDF1 should be used to pad the message 🌈PAD-OAEP-K2— says the ISO/IEC 18033-2 OAEP with KDF2 should be used to pad the message 🌈
Methods
get-hasher->Hasher(none) — returns the hasher object used by the OAEP padding modeset-hasher->none(Hasher) — sets the hasher object used by the OAEP padding modeget-padding-mode->Item(none) — returns the cipher padding modeset-padding-mode->none(Item) — sets the cipher padding modeget-padding-label->String(none) — returns the cipher padding labelset-padding-label->none(String) — sets the cipher padding labelget-padding-seed->String(none) — returns the cipher padding seedset-padding-seed->none(String) — sets the cipher padding seedpkcs-primitive->Relatif(Integer|Relatif) — computes a relatif value from a relatif argument, by either crypting or decrypting the argument.
okay the original description for this one just ends with the word "seed." floating there all alone like 🫠 and honestly? we're preserving it. every detail stays, even the mysterious ones. 💀
Signer ✍️
Signer is a base class, and you use it to build a message signature. The signature result gets stored in a special signature object, and that object is algorithm dependent — so like, it changes depending on which algorithm you're running. Main character energy, but for each algorithm separately. 👑
Predicate
signer-p
Inheritance
Nameable
Methods
reset->none(none) — resets the signer object along with its associated internal states 🔄compute->Signature(Literal|Buffer|InputStream) — computes the signature from a string, a buffer or an input stream. Returns a signature object. And heads up: when the argument is a buffer object or an input stream, the characters are consumed from the object. So, like, they're gone. Plan accordingly bestie. 😭derive->Signature(String) — computes the signature from an octet string, which gets converted before the signature computation. Returns a signature object. ✨
Signature 🎀
Signature is a container class designed to store a message signature. The signature object is produced by a signing process, and that process is implemented in the form of a digital signature algorithm — something like RSA or DSA. It's a little treasure box for your signature. 🫶
Predicate
signature-p
Inheritance
Object
Constructors
Signature(none) — creates an empty signature 🫧
Constants
NIL— indicates that the signature is a null signature 💀DSA— indicates that the signature is conforming to DSS ✅DSA-S-COMPONENT— corresponds to the DSA S component value 🌟DSA-R-COMPONENT— corresponds to the DSA R component value 🌟
Methods
reset->none(none) — resets the signature object to a null signature 🔄format->String(Item) — returns a string representation of the signature component. The signature component comes back as an octet string, based on the signature component you're accessing. 🧚get-relatif-component->Relatif(Item) — returns a relatif representation of a signature component ✨
Dsa 🦋
Dsa is an original implementation of the Digital Signature Standard (DSS) as published in FIPS PUB 186-3. She's not a wrapper, she's the real thing. 💅
This class implements the Digital Signature Algorithm (DSA) with an approved key length of 1024, 2048 and 3072 bits, with a 160, 224 and 256 bits hash function which is part of the SHA family. So pick your size, it's got range. 🌈
Predicate
dsa-p
Inheritance
Signer
Constructors
Dsa(none) — creates a signer object with a default DSA key 🎀Dsa(Key) — creates a signer object with a DSA key as its argument 🔑Dsa(KeyRelatif) — creates a signer object with a DSA key as its first argument and a fixed k argument as specified by DSS ⭐
and that's the whole page bestie, you made it to the end 🥳 this was from the AFNIX Module manual, AFNIX flavour, landing in section sec(3) — go forth and cipher responsibly, mwah 💖✨👑
📦 where this page comes from
- debian trixie: afnix 3.8.0-1.1 · AFNIX
- ubuntu noble: afnix 3.8.0-1 · AFNIX
- ubuntu resolute: afnix 3.8.0-1.1ubuntu1 · AFNIX
- ubuntu stonking: afnix 3.8.0-1.1ubuntu1 · AFNIX
- Copyright (c) 1999-2023 Amaury Darsch
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms