Coverage report: /home/ellis/comp/ext/ironclad/src/generic.lisp

KindCoveredAll%
expression044 0.0
branch00nil
Key
Not instrumented
Conditionalized out
Executed
Not executed
 
Both branches taken
One branch taken
Neither branch taken
1
 ;;;; generic.lisp -- generic function definitions
2
 (in-package :crypto)
3
 
4
 ;;; Authenticated encryption
5
 (defgeneric process-associated-data (mode data &key start end)
6
   (:documentation "Update the internal state of MODE with the contents of DATA
7
 between START and END so that they are taken into consideration in the
8
 authentication tag."))
9
 
10
 (defgeneric produce-tag (mode &key tag tag-start)
11
   (:documentation "Return the authentication tag of the data processed by MODE
12
 so far. If TAG is provided, the computed tag will be placed into TAG starting at
13
 TAG-START."))
14
 
15
 ;;; Ciphers
16
 (defgeneric verify-key (cipher key)
17
   (:documentation "Return T if KEY is a valid encryption key for CIPHER."))
18
 
19
 (defgeneric schedule-key (cipher key)
20
   (:documentation "Schedule KEY for CIPHER, filling CIPHER with any
21
 round keys, etc. needed for encryption and decryption."))
22
 
23
 (defgeneric key-lengths (cipher)
24
   (:documentation "Return a list of possible lengths of a key for
25
 CIPHER.  CIPHER may either be a cipher name as accepted by
26
 MAKE-CIPHER or a cipher object as returned by MAKE-CIPHER.  NIL
27
 is returned if CIPHER does not name a known cipher or is not a
28
 cipher object."))
29
 
30
 (defgeneric block-length (cipher)
31
   (:documentation "Return the number of bytes in an encryption or
32
 decryption block for CIPHER.  CIPHER may either be a cipher name
33
 as accepted by MAKE-CIPHER or a cipher object as returned by
34
 MAKE-CIPHER.  NIL is returned if CIPHER does not name a known
35
 cipher or is not a cipher object."))
36
 
37
 (defgeneric encrypted-message-length (cipher mode length &optional handle-final-block)
38
   (:documentation "Return the length a message of LENGTH would be if it
39
 were to be encrypted (decrypted) with CIPHER in MODE.  HANDLE-FINAL-BLOCK
40
 indicates whether we are encrypting up to and including the final block
41
  (so that short blocks may be taken into account, if applicable).
42
 
43
 Note that this computation may involve MODE's state."))
44
 
45
 (defgeneric mode-crypt-functions (cipher mode)
46
   (:documentation "Returns two functions that perform encryption and
47
 decryption, respectively, with CIPHER in MODE.  The lambda list of each
48
 function is (IN OUT IN-START IN-END OUT-START HANDLE-FINAL-BLOCK).
49
 HANDLE-FINAL-BLOCK is as in ENCRYPT and DECRYPT; the remaining parameters
50
 should be self-explanatory.  Each function, when called, returns two values:
51
 the number of octets processed from IN and the number of octets processed
52
 from OUT.  Note that for some cipher modes, IN and OUT may be different."))
53
 
54
 (defgeneric valid-mode-for-cipher-p (cipher mode))
55
 
56
 (defgeneric encrypt (cipher plaintext ciphertext &key plaintext-start plaintext-end ciphertext-start handle-final-block &allow-other-keys)
57
   (:documentation "Encrypt the data in PLAINTEXT between PLAINTEXT-START and
58
 PLAINTEXT-END according to CIPHER. Places the encrypted data in
59
 CIPHERTEXT, beginning at CIPHERTEXT-START. Less data than
60
 (- PLAINTEXT-END PLAINTEXT-START) may be encrypted, depending on the
61
 alignment constraints of CIPHER and the amount of space available in
62
 CIPHERTEXT."))
63
 
64
 (defgeneric decrypt (cipher ciphertext plaintext &key ciphertext-start ciphertext-end plaintext-start handle-final-block &allow-other-keys)
65
   (:documentation "Decrypt the data in CIPHERTEXT between CIPHERTEXT-START and
66
 CIPHERTEXT-END according to CIPHER. Places the decrypted data in
67
 PLAINTEXT, beginning at PLAINTEXT-START. Less data than
68
 (- CIPHERTEXT-END CIPHERTEXT-START) may be decrypted, depending on the
69
 alignment constraints of CIPHER and the amount of space available in
70
 PLAINTEXT."))
71
 
72
 ;;; Digests
73
 (defgeneric digest-file (digest-spec pathname &rest args &key buffer start end digest digest-start)
74
   (:documentation "Return the digest of the contents of the file named by
75
 PATHNAME using the algorithm DIGEST-NAME.
76
 
77
 If DIGEST is provided, the digest will be placed into DIGEST starting at
78
 DIGEST-START. DIGEST must be a (SIMPLE-ARRAY (UNSIGNED-BYTE 8) (*)). An error
79
 will be signaled if there is insufficient room in DIGEST.
80
 
81
 If BUFFER is provided, the portion of BUFFER between START and END will be used
82
 to hold data read from the stream."))
83
 
84
 (defgeneric digest-stream (digest-spec stream &rest args &key buffer start end digest digest-start)
85
   (:documentation "Return the digest of the contents of STREAM using the algorithm
86
 DIGEST-NAME.  STREAM-ELEMENT-TYPE of STREAM should be (UNSIGNED-BYTE 8).
87
 
88
 If DIGEST is provided, the digest will be placed into DIGEST starting at
89
 DIGEST-START.  DIGEST must be a (SIMPLE-ARRAY (UNSIGNED-BYTE 8) (*)).
90
 An error will be signaled if there is insufficient room in DIGEST.
91
 
92
 If BUFFER is provided, the portion of BUFFER between START and END will
93
 be used to hold data read from the stream."))
94
 
95
 (defgeneric digest-sequence (digest-spec sequence &rest args &key start end digest digest-start)
96
   (:documentation "Return the digest of the subsequence of SEQUENCE
97
 specified by START and END using the algorithm DIGEST-SPEC.
98
 SEQUENCE can be any vector with an element-type of (UNSIGNED-BYTE 8).
99
 
100
 If DIGEST is provided, the digest will be placed into DIGEST starting at
101
 DIGEST-START.  DIGEST must be a (SIMPLE-ARRAY (UNSIGNED-BYTE 8) (*)).
102
 An error will be signaled if there is insufficient room in DIGEST."))
103
 
104
 (defgeneric copy-digest (digester &optional copy)
105
   (:documentation "Return a copy of DIGESTER.  If COPY is not NIL, it
106
 should be of the same type as DIGESTER and will receive the copied data,
107
 rather than creating a new object.  The copy is a deep copy, not a
108
 shallow copy as might be returned by COPY-STRUCTURE."))
109
 
110
 (defgeneric update-digest (digester thing &key &allow-other-keys)
111
   (:documentation "Update the internal state of DIGESTER with THING.
112
 The exact method is determined by the type of THING."))
113
 
114
 (defgeneric produce-digest (digester &key digest digest-start)
115
   (:documentation "Return the hash of the data processed by
116
 DIGESTER so far.
117
 
118
 If DIGEST is provided, the hash will be placed into DIGEST starting at
119
 DIGEST-START.  DIGEST must be a (SIMPLE-ARRAY (UNSIGNED-BYTE 8) (*)).
120
 An error will be signaled if there is insufficient room in DIGEST."))
121
 
122
 (defgeneric digest-length (digest)
123
   (:documentation "Return the number of bytes in a digest generated by DIGEST."))
124
 
125
 ;;; Key derivation functions
126
 (defgeneric derive-key (kdf passphrase salt iteration-count key-length)
127
   (:documentation "Given a key derivation function object (produced by
128
 MAKE-KDF), a PASSWORD, a SALT and an ITERATION-COUNT, return the password digest
129
 as a byte array of length KEY-LENGTH."))
130
 
131
 ;;; Message authentication codes
132
 (defgeneric update-mac (mac thing &key &allow-other-keys)
133
   (:documentation "Update the internal state of MAC with THING.
134
 The exact method is determined by the type of THING."))
135
 
136
 (defgeneric produce-mac (mac &key digest digest-start)
137
   (:documentation "Return the hash of the data processed by
138
 MAC so far.
139
 
140
 If DIGEST is provided, the hash will be placed into DIGEST starting at
141
 DIGEST-START. DIGEST must be a (SIMPLE-ARRAY (UNSIGNED-BYTE 8) (*)).
142
 An error will be signaled if there is insufficient room in DIGEST."))
143
 
144
 ;;; Padding
145
 (defgeneric add-padding-bytes (padding text start block-offset block-size)
146
   (:documentation "Add padding to the block in TEXT beginning at position
147
 START.  Padding is done according to PADDING and assumes that text
148
 prior to BLOCK-OFFSET is user-supplied.
149
 
150
 This function assumes that the portion of TEXT from START to
151
  (+ START BLOCK-SIZE) is writable."))
152
 
153
 (defgeneric count-padding-bytes (padding text start block-size)
154
   (:documentation "Return the number of bytes of padding in the block in
155
 TEXT beginning at START.  The padding algorithm used for the block is
156
 PADDING."))
157
 
158
 ;;; Pseudo random number generators
159
 (defgeneric make-prng (name &key seed)
160
   (:documentation "Create a new NAME-type random number generator,
161
   seeding it from SEED.  If SEED is a pathname or namestring, read data
162
   from the indicated file; if it is sequence of bytes, use those bytes
163
   directly; if it is :RANDOM then read from /dev/random; if it
164
   is :URANDOM then read from /dev/urandom; if it is NIL then the
165
   generator is not seeded."))
166
 
167
 (defgeneric prng-random-data (num-bytes prng)
168
   (:documentation "Generate NUM-BYTES bytes using PRNG"))
169
 
170
 (defgeneric prng-reseed (seed prng)
171
   (:documentation "Reseed PRNG with SEED; SEED must
172
   be (PRNG-SEED-LENGTH PRNG) bytes long.")
173
   (:method (seed prng) (declare (ignorable seed prng))))
174
 
175
 (defgeneric prng-seed-length (prng)
176
   (:documentation "Length of seed required by PRNG-RESEED.")
177
   (:method (prng) (declare (ignorable prng)) 0))
178
 
179
 ;;; Public key cryptography
180
 (defgeneric make-public-key (kind &key &allow-other-keys)
181
   (:documentation "Return a public key of KIND, initialized according to
182
 the specified keyword arguments."))
183
 
184
 (defgeneric destructure-public-key (public-key)
185
   (:documentation "Return a plist containing the elements of a PUBLIC-KEY."))
186
 
187
 (defgeneric make-private-key (kind &key &allow-other-keys)
188
   (:documentation "Return a private key of KIND, initialized according to
189
 the specified keyword arguments."))
190
 
191
 (defgeneric destructure-private-key (private-key)
192
   (:documentation "Return a plist containing the elements of a PRIVATE-KEY."))
193
 
194
 (defgeneric generate-key-pair (kind &key num-bits &allow-other-keys)
195
   (:documentation "Generate a new key pair. The first returned
196
 value is the secret key, the second value is the public key. If KIND
197
 is :RSA or :DSA, NUM-BITS must be specified. If /kind/ is :ELGAMAL,
198
 NUM-BITS must be specified unless COMPATIBLE-WITH-KEY is specified."))
199
 
200
 (defgeneric make-signature (kind &key &allow-other-keys)
201
   (:documentation "Build the octet vector representing a signature
202
 from its elements."))
203
 
204
 (defgeneric destructure-signature (kind signature)
205
   (:documentation "Return a plist containing the elements of a SIGNATURE."))
206
 
207
 (defgeneric generate-signature-nonce (key message &optional parameters)
208
   (:documentation "Generate a one-time use number for a signature (the k
209
 parameter in DSA or ECDSA signatures)."))
210
 
211
 (defgeneric sign-message (key message &key start end &allow-other-keys)
212
   (:documentation "Produce a key-specific signature of MESSAGE; MESSAGE is a
213
 (VECTOR (UNSIGNED-BYTE 8)).  START and END bound the extent of the
214
 message."))
215
 
216
 (defgeneric verify-signature (key message signature &key start end &allow-other-keys)
217
   (:documentation "Verify that SIGNATURE is the signature of MESSAGE using
218
 KEY.  START and END bound the extent of the message."))
219
 
220
 (defgeneric make-message (kind &key &allow-other-keys)
221
   (:documentation "Build the octet vector representing a message
222
 from its elements."))
223
 
224
 (defgeneric destructure-message (kind message)
225
   (:documentation "Return a plist containing the elements of
226
 an encrypted MESSAGE."))
227
 
228
 (defgeneric encrypt-message (cipher-or-key message &key start end &allow-other-keys)
229
   (:documentation "Encrypt a MESSAGE with a CIPHER or a public KEY. START and
230
 END bound the extent of the message. Returns a fresh octet vector."))
231
 
232
 (defgeneric decrypt-message (cipher-or-key message &key start end n-bits &allow-other-keys)
233
   (:documentation "Decrypt a MESSAGE with a CIPHER or a private KEY. START and
234
 END bound the extent of the message. Returns a fresh octet vector. N-BITS can be
235
 used to indicate the expected size of the decrypted message."))
236
 
237
 (defgeneric diffie-hellman (private-key public-key)
238
   (:documentation "Compute a shared secret using Alice's PRIVATE-KEY and Bob's PUBLIC-KEY"))