table of contents
sec(3) | AFNIX Module | sec(3) |
NAME¶
sec - standard security moduleSTANDARD SECURITY MODULE¶
The Standard Security module is an original implementation of several standards and techniques used in the field of cryptography. The module provides the objects than enables message hashing, symetric and assymetric 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. Hash objectsFunction | Result size |
MD-2 | 128 bits |
MD-4 | 128 bits |
MD-5 | 128 bits |
SHA-1 | 160 bits |
SHA-224 | 224 bits |
SHA-256 | 256 bits |
SHA-384 | 384 bits |
SHA-512 | 512 bits |
# 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
Hasher | Size | Constructor |
SHA-1 | 160 bits | Sha1 |
SHA-224 | 224 bits | Sha224 |
SHA-256 | 256 bits | Sha256 |
SHA-384 | 384 bits | Sha384 |
SHA-512 | 512 bits | Sha512 |
Key | Description |
KSYM | Symmetric cipher key |
KRSA | Asymmetric RSA cipher key |
KMAC | Message authentication key |
KDSA | Message signature key |
# 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.
Key | Type | Description |
KSYM | byte | Byte array size |
KRSA | bits | Modulus size |
KMAC | byte | Byte array size |
KDSA | bits | Signature size |
const bits (key:get-bits) const size (key:get-size)Key representation
Key | Argument | Description |
KSYM | none | Symmetric key octet string |
KRSA | RSA-MODULUS | RSA modulus octet string |
KRSA | RSA-PUBLIC-EXPONENT | RSA public exponent octet string |
KRSA | RSA-SECRET-EXPONENT | RSA secret exponent octet string |
KMAC | none | Message authentication key octet string |
KDSA | DSA-P-PRIME | DSA secret prime octet string |
KDSA | DSA-Q-PRIME | DSA secret prime octet string |
KDSA | DSA-SECRET-KEY | DSA secret key |
KDSA | DSA-PUBLIC-KEY | DSA public key |
KDSA | DSA-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. Symmetric cipher key
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
# 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
# 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
# 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
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
# 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
# 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
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 can be changed with the set-padding-mode. Creating a block cipher
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 key can be created as indicated in the previous section. The reverse flag is used to determine if the cipher operate 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
println (aes:get-block-size)Input cipher
# 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
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 automatically the padding operations with the mode associated with the block cipher. Asymmetric cipher
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
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 mode. 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-K1Public cipher padding mode
Cipher | Padding mode | Default |
RSA | PKCS 1.5, PKCS 2.1, ISO/IEC 18033-2 | PKCS 1.5 |
Standard | Name |
DSS | Digital Signature Standard |
RSA | RSA based signature |
Standard | Key | Signer |
DSS | KDSA | Dsa |
const key (afnix:sec:Key afnix:sec:Key:KDSA) assert 1024 (key:get-bits)Creating a signer
# create a dsa signer const dsa (afnix:sec:Dsa key) assert true (afnix:sec:dsa-p dsa)Creating a signature
# create a signature object const sgn (dsa:compute "afnix") assert true (afnix:sec:signature-p sgn)Once the signature is created, each data can be accessed directly with the associated component mapper. In the case of DSS, there are two components as show 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¶
Hasherhasher-p
Inheritance
Nameable
Methods
reset -> none (none)
The reset method reset the hasher object with its associated internal
states.
hash-p -> Boolean (String)
The hash-p predicate returns true if the string argument is potentially a hash
value. It is not possible, with our current technology, to reverse a hash
value to one or several representations, nor it is possible to assert that
such value exists.
get-byte -> Byte (Integer)
The get-byte method returns the hash byte value by index. The argument is the
byte index which must be in the range of the hash result length.
format -> String (none)
The format method return a string representation of the hash value.
compute -> String (Literal|Buffer|InputStream)
The compute method computes the hash value from a string, a buffer or an input
stream. The method returns a string representation of the result hash value.
When the argument is a buffer object or an input stream, the characters are
consumed from the object.
derive -> String (String)
The derive method computes the hash value from an octet string which is
converted before the hash computation. The method returns a string
representation of the result hash value.
get-hash-length -> Integer (none)
The get-hash-length method returns the hasher length in bytes.
get-result-length -> Integer (none)
The get-result-length method returns the hasher result length in bytes. The
result length is less or equal to the hasher length and is set at
construction.
Md2
md2-p
Inheritance
Hasher
Constructors
Md2 (none)
The Md2 constructor creates a default hashing object that implements the MD-2
algorithm.
Md2 (Integer)
The Md2 constructor creates a MD-2 hashing object with a result length. The
argument is the hasher result length that must be less or equal to the hasher
length.
Md4
md4-p
Inheritance
Hasher
Constructors
Md4 (none)
The Md4 constructor creates a default hashing object that implements the MD-4
algorithm.
Md4 (Integer)
The Md4 constructor creates a MD-4 hashing object with a result length. The
argument is the hasher result length that must be less or equal to the hasher
length.
Md5
md5-p
Inheritance
Hasher
Constructors
Md5 (none)
The Md5 constructor creates a default hashing object that implements the MD-5
algorithm.
Md5 (Integer)
The Md5 constructor creates a MD-5 hashing object with a result length. The
argument is the hasher result length that must be less or equal to the hasher
length.
Sha1
sha1-p
Inheritance
Hasher
Constructors
Sha1 (none)
The Sha1 constructor creates a default hashing object that implements the SHA-1
algorithm.
Sha1 (Integer)
The Sha1 constructor creates a SHA-1 hashing object with a result length. The
argument is the hasher result length that must be less or equal to the hasher
length.
Sha224
sha224-p
Inheritance
Hasher
Constructors
Sha224 (none)
The Sha224 constructor creates a default hashing object that implements the
SHA-224 algorithm.
Sha224 (Integer)
The Sha224 constructor creates a SHA-224 hashing object with a result length.
The argument is the hasher result length that must be less or equal to the
hasher length.
Sha256
sha256-p
Inheritance
Hasher
Constructors
Sha256 (none)
The Sha256 constructor creates a default hashing object that implements the
SHA-256 algorithm.
Sha256 (Integer)
The Sha256 constructor creates a SHA-256 hashing object with a result length.
The argument is the hasher result length that must be less or equal to the
hasher length.
Sha384
sha384-p
Inheritance
Hasher
Constructors
Sha384 (none)
The Sha384 constructor creates a default hashing object that implements the
SHA-384 algorithm.
Sha384 (Integer)
The Sha384 constructor creates a SHA-384 hashing object with a result length.
The argument is the hasher result length that must be less or equal to the
hasher length.
Sha512
sha512-p
Inheritance
Hasher
Constructors
Sha512 (none)
The Sha512 constructor creates a default hashing object that implements the
SHA-512 algorithm.
Sha512 (Integer)
The Sha512 constructor creates a SHA-512 hashing object with a result length.
The argument is the hasher result length that must be less or equal to the
hasher length.
Key
key-p
Inheritance
Object
Constructors
Key (none)
The Key constructor creates a default cipher key. The key is generated with
random bytes and is 128 bits long.
Key (String)
The Key constructor 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 the format method.
Key (Item)
The Key constructor creates a key by type. If the key type is KSYM, a symmetric
128 bytes random key is generated. If the key type is KRSA, a 1024 bits RSA
random key is generated.
Key (Item Integer|String|Vector)
The Key constructor 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 octet string to represent the key. In the third form, a
vector of byte values can be used to load the key.
Constants
KSYM
The KSYM constant indicates that the key is a symmetric key.
KRSA
The KRSA constant indicates that the key is a asymmetric RSA key.
KMAC
The KMAC constant indicates that the key is a message authentication (MAC)
key.
RSA-MODULUS
The RSA-MODULUS constant corresponds to the RSA modulus value.
RSA-PUBLIC-EXPONENT
The RSA-PUBLIC-EXPONENT constant corresponds to the RSA public exponent value
which is generally 65537.
RSA-SECRET-EXPONENT
The RSA-SECRET-EXPONENT constant corresponds to the RSA secret exponent
value.
Methods
get-byte -> Byte (Integer)
The get-byte method returns a key byte value by index. The index must be in the
key range or an exception is raised. This method is primarily used with
symmetric key.
get-type -> Item (none)
The get-type method returns the key type in the form of an item object.
get-bits -> Integer (none)
The get-bits method returns the key size in bits.
get-size -> Integer (none)
The get-size method returns the key size in bytes.
format -> String (none|Item)
The format method 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)
The get-relatif-key method returns a relatif representation of a key element.
This method is well suited for asymmetric key. The key value is returned as a
relatif based on the key element to access.
Kdf
kdf-p
Inheritance
Nameable
Methods
reset -> none (none)
The reset method reset the internal state of the kdf object.
get-size -> Integer (none)
The get-size method returns the kdf size in bytes.
get-byte -> Byte (Integer)
The get-byte method returns a kdf byte value by index. The index must be in the
key range or an exception is raised.
format -> String (none)
The format method returns a string representation of the derived key.
derive -> String (String)
The derive method returns a string representation of a derived key computed from
the octet string argument.
compute -> String (String)
The compute method returns a string representation of a derived key computed
from the string argument.
Hkdf
hashed-kdf-p
Inheritance
Kdf
Methods
get-hasher -> none (none)
The get-hasher method returns the hasher object associated with the key
derivation function object. object.
Kdf1
kdf1-p
Inheritance
Hkdf
Constructors
Kdf1 (Hasher Integer)
The Kdf1 constructor 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
kdf2-p
Inheritance
Hkdf
Constructors
Kdf2 (Hasher Integer)
The Kdf2 constructor 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
cipher-p
Inheritance
Nameable
Methods
reset -> none (none)
The reset method reset the cipher internal state.
stream -> Integer (OutputStream InputStream)
The stream method process an input stream and write into an output stream. The
method returns the number of character 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)
The set-key method sets the cipher key. The first argument is the key to
set.
get-key -> Key (none)
The get-key method returns the cipher key.
set-reverse -> none (Boolean)
The set-reverse method 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)
The get-reverse method 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
block-cipher-p
Inheritance
Cipher
Constants
PAD-NONE
The PAD-NONE constant indicates that the block should not be padded.
PAD-BIT-MODE
The PAD-BIT constant indicates that the block should be padded in bit
mode.
PAD-ANSI-X923
The PAD-ANSI-X923 constant indicates that the block should be padded according
to ANSI X 923 standard.
PAD-NIST-800
The PAD-NIST-800 constant indicates that the block should be padded according to
NIST 800-38A recommendations. This is the default mode.
Methods
get-block-size -> Integer (none)
The get-block-size method returns the cipher block size.
set-padding-mode -> none (Item)
The set-padding-mode method sets the cipher padding mode.
get-padding-mode -> Item (none)
The get-padding-mode method returns the cipher padding mode.
InputCipher
input-cipher-p
Inheritance
Input
Constructors
InputCipher (Cipher)
The InputCipher constructor creates an input cipher with a cipher object. The
first argument is the cipher to used for processing.
InputCipher (Cipher Input)
The InputCipher constructor creates an input cipher with a cipher object and an
input stream. The first argument is the cipher to used for processing. The
second argument is the input stream object used for the character
reading.
InputCipher (Cipher InputStream Item)
The InputCipher constructor creates an input cipher with a cipher object, an
input stream and a mode. The first argument is the cipher to used for
processing. The second argument is the input stream object used for the
character reading. The third argument is the input cipher mode which can be
either ECB, CBC, CFB or OFB.
Constants
ECB
The ECB constant indicates that the input cipher is to operate in electronic
codebook mode. This mode is the default mode.
CBC
The CBC constant indicates that the input cipher is to operate in cipher
chaining block mode.
CFB
The CFB constant indicates that the input cipher is to operate in cipher
feedback block mode.
OFB
The OFB constant indicates that the input cipher is to operate in output
feedback block mode.
Methods
reset -> none (none)
The reset method reset the input cipher object.
get-mode -> Item (none)
The get-mode method returns the input cipher operating mode.
set-iv -> none (String|Buffer)
The set-iv method 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)
The get-iv method returns the input cipher initial vector as an octet
string.
set-is -> none (InputStream)
The set-is method sets the input cipher input stream. This method can be used to
chain multiple input streams in a unique coding session.
Aes
aes-p
Inheritance
BlockCipher
Constructors
Aes (Key)
The Aes constructor creates a direct cipher with a key. The first argument is
the key used by the cipher.
Aes (Key Boolean)
The Aes constructor 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
public-cipher-p
Inheritance
Cipher
Methods
get-message-size -> Integer (none)
The get-message-size method returns the cipher message size.
get-crypted-size -> Integer (none)
The get-crypted-size method returns the cipher crypted block size.
Rsa
rsa-p
Inheritance
PublicCipher
Constructors
Rsa (none)
The Rsa constructor creates a default RSA public cipher by binding a 1024 bits
random key.
Rsa (Key)
The Rsa constructor creates a RSA public cipher by binding the key
argument.
Rsa (Key Boolean)
The Rsa constructor creates a RSA public cipher by binding the key argument and
the reverse flag. The first argument is the key to bind. The second argument
is the reverse flag to set.
Rsa (Key Hasher String)
The Rsa constructor creates a RSA public cipher by binding the key argument and
OAEP padding objects. The first argument is the key to bind. The second
argument is hasher object to use with the OAEP padding mode. The third
argument is an optional label to be used by the KDF object.
Constants
PAD-PKCS-11
The PAD-PKCS-11 constant indicates that the PKCS 1.5 type 1 block should be used
to pad the message.
PAD-PKCS-12
The PAD-PKCS-12 constant indicates that the PKCS 1.5 type 3 block should be used
to pad the message.
PAD-OAEP-K1
The PAD-OAEP-K1 constant indicates that the ISO/IEC 18033-2 OAEP with KDF1
should be used to pad the message.
PAD-OAEP-K2
The PAD-OAEP-K2 constant indicates that the ISO/IEC 18033-2 OAEP with KDF2
should be used to pad the message.
Methods
get-hasher -> Hasher (none)
The get-hasher method returns the hasher object used by the OAEP padding
mode.
set-hasher -> none (Hasher)
The set-hasher method sets the hasher object used by the OAEP padding
mode.
get-padding-mode -> Item (none)
The get-padding-mode method returns the cipher padding mode.
set-padding-mode -> none (Item)
The set-padding-mode method sets the cipher padding mode.
get-padding-label -> String (none)
The get-padding-label method returns the cipher padding label.
set-padding-label -> none (String)
The set-padding-mode method sets the cipher padding label.
get-padding-seed -> String (none)
The get-padding-seed method returns the cipher padding seed.
set-padding-seed -> none (String)
The set-padding-seed method sets the cipher padding seed.
pkcs-primitive -> Relatif (Integer|Relatif)
The pkcs-primitive method compute a relatif value from a relatif argument by
either crypting or decrypting the argument. seed.
Signer
signer-p
Inheritance
Nameable
Methods
reset -> none (none)
The reset method reset the signer object with its associated internal
states.
compute -> Signature
(Literal|Buffer|InputStream)
The compute method computes the signature from a string, a buffer or an input
stream. The method returns a signature object. When the argument is a buffer
object or an input stream, the characters are consumed from the object.
derive -> Signature (String)
The derive method computes the signature from an octet string which is converted
before the signature computation. The method returns a signature object.
Signature
signature-p
Inheritance
Object
Constructors
Signature (none)
The Signature constructor creates an empty signature.
Constants
NIL
The NIL constant indicates that the signature is a null signature.
DSA
The DSA constant indicates that the signature is conforming to DSS.
DSA-S-COMPONENT
The DSA-S-COMPONENT constant corresponds to the DSA S component value.
DSA-R-COMPONENT
The DSA-R-COMPONENT constant corresponds to the DSA R component value.
Methods
reset -> none (none)
The reset method reset the signature object to a null signature.
format -> String (Item)
The format method returns a string representation of the signature component.
The signature component is returned as an octet string based on the signature
component to access.
get-relatif-component -> Relatif (Item)
The get-relatif-component method returns a relatif representation of a signature
component.
Dsa
dsa-p
Inheritance
Signer
Constructors
Dsa (none)
The Dsa constructor creates a signer object with a default DSA key.
Dsa (Key)
The Dsa constructor creates a signer object with a DSA key as its
argument.
Dsa (Key Relatif)
The Dsa constructor creates a signer object with a DSA key as its first argument
and a fixed k argument as specified by DSS.
2012-03-26 | AFNIX |