# Key management

This chapter is dedicated to the cipher key management, which is 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 dependant 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

# 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 | Array size
KRSA | bits | Modulus 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 hexadecimal 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 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 string byte value
KRSA | RSA-MODULUS | RSA modulus string byte value
KRSA | RSA-PUBLIC-EXPONENT | RSA public exponent string byte value
KRSA | RSA-SECRET-EXPONENT | RSA secret exponent string byte value

# 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 a pass-phrase.

const key (afnix:sec:Key) assert true (afnix:sec:key-p key)

The constructor also supports the use of a string message for the generation of the key.

# create a message key const key (afnix:sec:Key "hello world") 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 dependant 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)