1
  
2
  
3
  
4
  
5
  
6
  
7
  
8
  
9
  
10
  
11
  
12
  
13
  
14
  
15
  
16
  
17
  
18
  
19
  
20
  
21
  
22
  
23
  
24
  
25
  
26
  
27
  
28
  
29
  
30
  
31
  
32
  
33
  
34
  
35
  
36
  
37
  
38
  
39
  
40
  
41
  
42
  
43
  
44
  
45
  
46
  
47
  
48
  
49
  
50
  
51
  
52
  
53
  
54
  
55
  
56
  
57
  
58
  
59
  
60
  
61
  
62
  
63
  
64
  
65
  
66
  
67
  
68
  
69
  
70
  
71
  
72
  
73
  
74
  
75
  
76
  
77
  
78
  
79
  
80
  
81
  
82
  
83
  
84
  
85
  
86
  
87
  
88
  
89
  
90
  
91
  
92
  
93
  
94
  
95
  
96
  
97
  
98
  
99
  
100
  
101
  
102
  
103
  
104
  
105
  
106
  
107
  
108
  
109
  
110
  
111
  
112
  
113
  
114
  
115
  
116
  
117
  
118
  
119
  
120
  
121
  
122
  
123
  
124
  
125
  
126
  
127
  
128
  
129
  
130
  
131
  
132
  
133
  
134
  
135
  
136
  
137
  
138
  
139
  
140
  
141
  
142
  
143
  
144
  
145
  
146
  
147
  
148
  
149
  
150
  
151
  
152
  
153
  
154
  
155
  
156
  
157
  
158
  
159
  
160
  
161
  
162
  
163
  
164
  
165
  
166
  
167
  
168
  
169
  
170
  
171
  
172
  
173
  
174
  
175
  
176
  
177
  
178
  
179
  
180
  
181
  
182
  
183
  
184
  
185
  
186
  
187
  
188
  
189
  
190
  
191
  
192
  
193
  
194
  
195
  
196
  
197
  
198
  
199
  
200
  
201
  
202
  
203
  
204
  
205
  
206
  
207
  
208
  
209
  
210
  
211
  
212
  
213
  
214
  
215
  
216
  
217
  
218
  
219
  
220
  
221
  
222
  
223
  
224
  
225
  
226
  
227
  
<--! -*-html-*- --> 
 
<section title="The Pike Crypto Toolkit"> 
 
<section title="Introduction"> 
 
The Crypto module provides an object-oriented framwork for encryption 
and related functionality. More specifically, its objects han be 
classified as follows: 
 
<dl> 
  <dt> Block ciphers  
  <dd> encrypt data in chunks of typically 8 bytes, using a secret 
      key.  
  <dt> Stream ciphers  
  <dd> operate on the data to be encrypted one byte at a time, for 
      exemple by xoring it with a sequence of pseudorandom bytes. 
  <dt> Cryptographic hash functions 
  <dd> transform a bytesequence of arbitrary length into a short 
      string of a fixed length of typically 16 or 20 bytes, in such a 
      way that it is practically impossible to find two distinct 
      strings with the same hash value.  
  <dt> Public key algorithms  
  <dd> can support both encryption and digital signatures. 
  <dt> Abstract building blocks  
  <dd> for combining ciphers (mainly for block ciphers). These objects 
      behave like block ciphers, but delegate encryption to one or 
      several underlying objects, in some way.  
 
      For example, block ciphers are often used in a feedback mode. 
      The ciphers by themselves know nothing about these different 
      "modes of operation", instead this knowledge is abstracted into 
      separate objects. If you want IDEA in Cipher Block Chaining 
      mode, you combine an IDEA object and a CBC object. 
 
      <p> There are also other objects for cascading ciphers, useful for 
      example you can build a triple-DES object by using three DES 
      objects in sequence.  
  <dt> Randomness  
  <dd> is essential for many cryptographic application. The toolkit 
      includes a few different random number generators, with varying 
      degrees of true randomness. 
  <dt> Frontend objects  
  <dd> that handle things like padding messages, or make it more 
      convenient to use popular combinations of ciphers, feedback 
      modes, etc. 
</dl> 
 
</section> 
<section title="Block ciphers"> 
 
The block ciphers included in the current version are DES, IDEA and 
CAST128 (note that IDEA is patented, see <a 
href="http://www.ascom.ch/systec">Ascom Tech</a> for details). 
All block ciphers have a common set of methods. 
 
<method name="crypt_block"> 
<man_syntax> 
string o->crypt_block(string <i>blocks</i>); 
</man_syntax> 
 
<man_description> 
Encrypts or decrypts an even number of block, using the current key. 
If more than one block is given, they are encrypted/decrypted 
independently, i.e. in <i>Electronic Code Book</i> (ECB) mode. 
</man_description> 
 
<method name="query_block_size"> 
<man_syntax> 
int o->query_block_size(); 
</man_syntax> 
 
<man_description> 
Returns the block size of the cipher, in octets. A typical block size 
is 8 octets. A string passed to crypt_block() must have a length that 
is a multiple of the block size. 
</man_description> 
 
<method name="query_key_length"> 
<man_syntax> 
int o->query_key_length(); 
</man_syntax> 
 
<man_description> 
Returns the key size of the cipher, in octets. Note that some block 
ciphers, e.g. CAST128, have a variable key size. In this case, 
query_key_length returns the recommended key size, although keys of 
other lengths are accepted by the set_encrypt_key and set_decrypt_key 
methods. 
 
For DES, the real key length is seven octets (56 bits), but the DES 
standard mandates the use of parity bits. The query_key_length method 
lies about DES, and says that the key_size is eight octets (64 bits). 
See also <link to=des_parity>des_parity</link>. 
 
</man_description> 
 
<method name="set_encrypt_key"> 
<man_syntax> 
object o->set_encrypt_key(string <i>key</i>); 
</man_syntax> 
 
<man_description> 
Installs a key, and configures the object for doing encryption. For 
convenience, this method returns the object itself. 
</man_description> 
 
<method name="set_decrypt_key"> 
<man_syntax> 
object o->set_decrypt_key(string <i>key</i>); 
</man_syntax> 
 
<man_description> 
Installs a key, and configures the object for doing decryption. For 
convenience, this method returns the object itself. 
</man_description> 
 
The classes are <class name="Crypto.des"></class> <class 
name="Crypto.idea"></class> <class name="Crypto.cast"></class>. 
 
To encrypt the block "Pike des" using the DES-key '0123456789abcdef' 
(in hex), use 
<example language=pike> 
Crypto.des()->set_encrypt_key(Crypto.hex_to_string("0123456789abcdef")) 
            ->crypt_block("Pike DES"); 
</example> 
 
although most applications will not use the Crypto.des class directly. 
</section> 
 
<section name="Stream Ciphers"> 
 
Currently the only stream cipher in the toolkit is the RC4 cipher 
(also known as "arcfour").  
 
<class name="Crypto.rc4"> 
 
<method name="crypt"> 
<man_syntax> 
string Crypto.rc4->crypt(string <i>data</>); 
</man_syntax> 
 
<man_description> 
Encrypts or decrypts a string of data. 
</man_description> 
 
<method name="set_encrypt_key"> 
<man_syntax> 
object Crypto.rc4->set_encrypt_key(string <i>key</i>); 
</man_syntax> 
 
<man_description> 
Installs a key, and configures the object for doing encryption. For 
convenience, this method returns the object itself.  
</man_description> 
 
<method name="set_decrypt_key"> 
<man_syntax> 
object Crypto.rc4->set_decrypt_key(string <i>key</i>); 
</man_syntax> 
 
<man_description> 
Installs a key, and configures the object for doing decryption. For 
convenience, this method returns the object itself. 
</man_description> 
 
Because of the way RC4 works, set_encrypt_key and set_decrypt_key are 
actually equivalent. 
 
</section> 
 
<section name="Hash Functions"> 
 
Cryptographic hash functions are essential for many cryptographic 
applications, and are also useful in other contexts. The Toolkit 
includes the two most common, <i>MD5</i> and <i>SHA1</i>. They have 
the same methods. 
 
<method name="update"> 
 
<man_syntax> 
object o->update(string <i>data</i>); 
</man_syntax> 
 
<man_description> 
Processes some more data. For convenience, this method returns the 
object itself.  
</man_description> 
 
<method name="digest"> 
<man_syntax> 
string o->digest(); 
</man_syntax> 
 
<man_description> 
Returns the hash value, or <i>message digest</i>, corresponding to all 
the data that was previously passed to the update method. Also resets 
the hash object, so that it can be used to process a new message. 
</man_description> 
 
<method name="query_digest_size"> 
<man_syntax> 
int o->query_digest_size(); 
</man_syntax> 
 
<man_description> 
Returns the size, in octets, of the digests produced by this hash function. 
</man_description> 
 
<method name="create"> 
<man_syntax> 
void o->create(void|object) 
All block ciphers have a common set of methods 
 
<example type=pike> 
<caption>Creating an object encrypting using IDEA in CBC-mode</caption> 
Crypto(CBC(IDEA)-&gt;set_iv(iv)-&gt;set_encrypt_key(key) 
</example> 
<p> There is a pike implementation of <link to=ssl type=used_by>SSL (Secure 
socket Layer)</link> built on top of the crypto toolkit.</p> 
</description> 
 
<future> 
Compatibility with standards such as RSA Inc's PKCS (Public Key 
Cryptography Standards) might be useful. 
</future>