# Key management

This chapter is dedicated to the cipher key management, a subpart of the standard security module.

## 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 like 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.

### 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.

### Supported key type

Key | Description
--- | ---
KSYM | Symmetric cipher key
KRSA | Asymmetric RSA cipher key
KMAC | Message authentication key
KDSA | 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.

### Key size nature

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

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 needs to be distinguished and therefore making 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 an 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.

### Key format method argument

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

### 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 like 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.

### 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 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 a 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)