1
<?xml version="1.0" encoding="UTF-8"?>
3
<!-- ====================================================================== -->
4
<!-- = chapter-2.xml = -->
5
<!-- = standard security module guide - chapter 2 = -->
6
<!-- ====================================================================== -->
7
<!-- = This program is free software; you can redistribute it and/or = -->
8
<!-- = modify it provided that this copyright notice is kept intact. = -->
9
<!-- = This program is distributed in the hope that it will be useful but = -->
10
<!-- = without any warranty; without even the implied warranty of = -->
11
<!-- = merchantability or fitness for a particular purpose. In no event = -->
12
<!-- = shall the copyright holder be liable for any direct, indirect, = -->
13
<!-- = incidental or special damages arising in any way out of the use = -->
14
<!-- = of this software. = -->
15
<!-- ====================================================================== -->
16
<!-- = copyright (c) 1999-2011 - amaury darsch = -->
17
<!-- ====================================================================== -->
19
<chapter module="sec" number="2">
20
<title>Key management</title>
23
This chapter is dedicated to the cipher key management, a subpart
24
of the <em>standard security</em> module.
27
<!-- cipher key principles -->
29
<title>Cipher key principles</title>
32
Cipher key management is an important concept in the ciphering land.
33
In a simple mode, a key is used by a cipher to encode some data.
34
Although the key can be any sequence of bytes, it is preferable to
35
have the key built from a specific source such like a
36
pass-phrase. A cipher key comes basically into two flavors: keys
37
for symmetric ciphers and keys for asymmetric ciphers. A key for
38
a symmetric cipher is easy to derive and generally follows a
39
standard process which is independent of the cipher itself. A key
40
for an asymmetric cipher is more complex to derive and is
41
generally dependent on the cipher itself.
44
<!-- key operations -->
46
<title>Key operations</title>
49
The basic operations associated with a key are the key
50
identification by type and size. The key type is an item that
51
identifies the key nature. The <code>get-type</code> method
52
returns the key type as specified by the table below.
56
<title>Supported key type</title>
57
<tr><th>Key</th><th>Description</th></tr>
58
<tr><td>KSYM</td> <td>Symmetric cipher key</td></tr>
59
<tr><td>KRSA</td> <td>Asymmetric RSA cipher key</td></tr>
60
<tr><td>KMAC</td> <td>Message authentication key</td></tr>
61
<tr><td>KDSA</td> <td>Message signature key</td></tr>
65
The message authentication key as represented by
66
the <code>KMAC</code> symbol is similar to the symmetric
67
key. The key type can be obtained with the <code>get-type</code>
73
const type (key:get-type)
77
The key size is the canonical size as specified by the key or
78
the cipher specification. The <code>get-bits</code> returns the
79
key size in bits. The <code>get-size</code> returns the key size
80
in bytes rounded to the nearest value. The table below describes
81
the nature of the key size returned.
85
<title>Key size nature</title>
86
<tr><th>Key</th> <th>Type</th> <th>Description</th></tr>
87
<tr><td>KSYM</td> <td>byte</td> <td>Byte array size</td></tr>
88
<tr><td>KRSA</td> <td>bits</td> <td>Modulus size</td></tr>
89
<tr><td>KMAC</td> <td>byte</td> <td>Byte array size</td></tr>
90
<tr><td>KDSA</td> <td>bits</td> <td>Signature size</td></tr>
94
const bits (key:get-bits)
95
const size (key:get-size)
99
<!-- key representation -->
101
<title>Key representation</title>
104
Unfortunately, it is not easy to represent a key, since the
105
representation depends on the key's type. For
106
example, a symmetric key can be formatted as a simple octet
107
string. On the other hand, a RSA key has two components; namely
108
the modulus and the exponent, which needs to be
109
distinguished and therefore making the representation more
110
difficult. Other cipher keys are even more complicated. For this
111
reason, the representation model is a relaxed
112
one. The <code>format</code> method can be called without
113
argument to obtain an unique octet string representation if this
114
representation is possible. If the key representation requires
115
some parameters, the format method may accept one or several
116
arguments to distinguish the key components.
120
<title>Key format method argument</title>
121
<tr><th>Key</th> <th>Argument</th> <th>Description</th></tr>
122
<tr><td>KSYM</td> <td>none</td>
123
<td>Symmetric key octet string</td></tr>
124
<tr><td>KRSA</td> <td>RSA-MODULUS</td>
125
<td>RSA modulus octet string</td></tr>
126
<tr><td>KRSA</td> <td>RSA-PUBLIC-EXPONENT</td>
127
<td>RSA public exponent octet string</td></tr>
128
<tr><td>KRSA</td> <td>RSA-SECRET-EXPONENT</td>
129
<td>RSA secret exponent octet string</td></tr>
130
<tr><td>KMAC</td> <td>none</td>
131
<td>Message authentication key octet string</td></tr>
132
<tr><td>KDSA</td> <td>DSA-P-PRIME</td>
133
<td>DSA secret prime octet string</td></tr>
134
<tr><td>KDSA</td> <td>DSA-Q-PRIME</td>
135
<td>DSA secret prime octet string</td></tr>
136
<tr><td>KDSA</td> <td>DSA-SECRET-KEY</td>
137
<td>DSA secret key</td></tr>
138
<tr><td>KDSA</td> <td>DSA-PUBLIC-KEY</td>
139
<td>DSA public key</td></tr>
140
<tr><td>KDSA</td> <td>DSA-PUBLIC-GENERATOR</td>
141
<td>DSA public generator</td></tr>
145
# get a simple key representation
147
# get a rsa modulus key representation
148
println (key:format afnix:sec:Key:RSA-MODULUS)
152
There are other key representations. The natural one is the byte
153
representation for a symmetric key, while a number based
154
representation is generally more convenient with asymmetric
155
keys. The <code>get-byte</code> method returns a key byte by
156
index if possible. The <code>get-relatif-key</code> returns a
157
key value by relatif number if possible.
162
<!-- symmetric cipher key -->
164
<title>Symmetric cipher key</title>
166
<!-- creating a symmetric cipher key -->
168
<title>Creating a symmetric cipher key</title>
171
The <code>Key</code> class can be used to create a cipher key
172
suitable for a symmetric cipher. By default a 128 bits random
173
key is generated, but the key can be also generated from an
178
const key (afnix:sec:Key)
179
assert true (afnix:sec:key-p key)
183
The constructor also supports the use of an octet string
184
representation of the key.
188
# create an octet string key
189
const key (afnix:sec:Key "0123456789ABCDEF")
190
assert true (afnix:sec:key-p key)
194
<!-- symmetric key functions -->
196
<title>Symmetric key functions</title>
199
The basic operation associated with a symmetric key is the byte
200
extraction. The <code>get-size</code> method can be used to
201
determine the byte key size. Once the key size has been
202
obtained, the key byte can be accessed by index with
203
the <code>get-byte</code> method.
207
# create a 256 random symmetric key
208
const key (afnix:sec:Key afnix:sec:Key:KSYM 256)
211
const size (key:get-size)
213
const byte (key:get-byte 0)
218
<!-- asymmetric cipher key -->
220
<title>Asymmetric cipher key</title>
223
An asymmetric cipher key can be generated for a particular
224
asymmetric cipher, such like RSA. Generally, the key contains
225
several components identified as the public and secret key
226
components. These components are highly dependent on the cipher
227
type. Under some circumstances, all components might not be available.
230
<!-- creating an asymmetric cipher key -->
232
<title>Creating an asymmetric cipher key</title>
235
The <code>Key</code> class can be used to create a specific
236
asymmetric cipher key. Generally, the key is created by type and
241
# create a 1024 bits rsa key
242
const key (afnix:sec:Key afnix:sec:Key:KRSA 1024)
246
An asymmetric cipher key constructor is extremely dependent on
247
the cipher type. For this reason, there is no constructor that
248
can operate with a pass-phrase.
252
<!-- asymmetric key functions -->
254
<title>Asymmetric key functions</title>
257
The basic operation associated with a asymmetric key is the relatif
258
based representation which is generally available for all key
259
components. For example, in the case of the RSA cipher, the
260
modulus, the public and secret exponents can be obtained in a
261
relatif number based representation with the help of
262
the <code>get-relatif-key</code> method.
266
# create a 512 rsa key
267
const key (afnix:sec:Key afnix:sec:Key:KRSA 512)
269
# get the key modulus
270
const kmod (key:get-relatif-key afnix:sec:Key:RSA-MODULUS)
271
# get the public exponent
272
const pexp (key:get-relatif-key afnix:sec:Key:RSA-PUBLIC-EXPONENT)
273
# get the secret exponent
274
const sexp (key:get-relatif-key afnix:sec:Key:RSA-SECRET-EXPONENT)
279
<!-- message authentication key -->
281
<title>Message authentication key</title>
283
<!-- creating a message authentication key -->
285
<title>Creating a message authentication key</title>
288
The <code>Key</code> class can also be used to create a message
289
authentication key suitable for a message authentication code
290
generator or validator. By default a 128 bits random
291
key is generated, but the key can be also generated from an octet
296
const key (afnix:sec:Key afnix:sec:Key:KMAC)
297
assert true (afnix:sec:key-p key)
301
The constructor also supports the use of an octet string
302
as a key representation.
306
# create an octet string key
307
const key (afnix:sec:Key afnix:sec:Key:KMAC "0123456789ABCDEF")
308
assert true (afnix:sec:key-p key)
312
<!-- message authentication key functions -->
314
<title>Message authentication key functions</title>
317
The basic operation associated with a message authentication key
318
is the byte extraction. The <code>get-size</code> method can be
319
used to determine the byte key size. Once the key size has been
320
obtained, the key byte can be accessed by index with
321
the <code>get-byte</code> method.
325
# create a 256 random message authentication key
326
const key (afnix:sec:Key afnix:sec:Key:KMAC 256)
329
const size (key:get-size)
331
const byte (key:get-byte 0)
335
<!-- signature key functions -->
337
<title>Signature key functions</title>
340
The basic operation associated with a signature key is the
341
relatif based representation which is generally available for all key
342
components. For example, in the case of the DSA signer, the
343
prime numbers, the public and secret components can be obtained in a
344
relatif number based representation with the help of
345
the <code>get-relatif-key</code> method.
349
# create a 1024 dsa key
350
const key (afnix:sec:Key afnix:sec:Key:KDSA)
353
const size (key:get-size)
354
# get the secret component
355
const sexp (key:get-relatif-key afnix:sec:Key:DSA-SECRET-KEY)
added
removed
src/mod/sec/doc/chapter-2.xml
