1 /*===========================================================================
2  *
3  *                            PUBLIC DOMAIN NOTICE
4  *               National Center for Biotechnology Information
5  *
6  *  This software/database is a "United States Government Work" under the
7  *  terms of the United States Copyright Act.  It was written as part of
8  *  the author's official duties as a United States Government employee and
9  *  thus cannot be copyrighted.  This software/database is freely available
10  *  to the public for use. The National Library of Medicine and the U.S.
11  *  Government have not placed any restriction on its use or reproduction.
12  *
13  *  Although all reasonable efforts have been taken to ensure the accuracy
14  *  and reliability of the software and data, the NLM and the U.S.
15  *  Government do not and cannot warrant the performance or results that
16  *  may be obtained by using this software or data. The NLM and the U.S.
17  *  Government disclaim all warranties, express or implied, including
18  *  warranties of performance, merchantability or fitness for any particular
19  *  purpose.
20  *
21  *  Please cite the author in any work or product based on this material.
22  *
23  * ===========================================================================
24  */
25 
26 #ifndef _h_krypto_cipher_
27 #define _h_krypto_cipher_
28 
29 #include <krypto/extern.h>
30 #include <klib/defs.h>
31 
32 typedef struct KCipher KCipher;
33 
34 KRYPTO_EXTERN
35 rc_t CC KCipherAddref (const KCipher * self);
36 
37 KRYPTO_EXTERN rc_t CC KCipherRelease (const KCipher * self);
38 
39 KRYPTO_EXTERN rc_t CC KCipherBlockSize (const KCipher * self, size_t * bytes);
40 
41 KRYPTO_EXTERN rc_t CC KCipherSetEncryptKey (KCipher * self,
42                                             const void * user_key,
43                                             size_t user_key_size);
44 
45 KRYPTO_EXTERN rc_t CC KCipherSetDecryptKey (KCipher * self,
46                                             const void * user_key,
47                                             size_t user_key_size);
48 
49 /*
50  * Set the ivec (Initialization vector or feedback) for the cipher
51  * this is done automatically for the longer runs defined below.
52  *
53  * the size of ivec  must match KCipherBlockSize
54  *
55  * the ivec is copied into the cipher not used in place
56  */
57 KRYPTO_EXTERN
58  rc_t CC KCipherSetEncryptIVec (KCipher * self, const void * ivec);
59 
60 KRYPTO_EXTERN
61  rc_t CC KCipherSetDecryptIVec (KCipher * self, const void * ivec);
62 
63 
64 typedef void (*cipher_ctr_func)(void * ivec);
65 
66 KRYPTO_EXTERN rc_t CC KCipherSetEncryptCtrFunc (KCipher * self, cipher_ctr_func func);
67 
68 KRYPTO_EXTERN rc_t CC KCipherSetDecryptCtrFunc (KCipher * self, cipher_ctr_func func);
69 
70 /*
71  * 'in' can equal 'out'
72  */
73 KRYPTO_EXTERN rc_t CC KCipherEncrypt (KCipher * self, const void * in, void * out);
74 
75 KRYPTO_EXTERN rc_t CC KCipherDecrypt (KCipher * self, const void * in, void * out);
76 
77 
78 /* ====================
79  * longer runs of multiple blocks.
80  *
81  * The algorithms are well defined and standard in most cases.
82  *
83  * PT: plain text block
84  * CT: cipher text block
85  * EK: encryption key
86  * DK: decryption key (might be sthe same as EK)
87  * ENC: encrypt cipher function on a block using a key
88  * DEC: decrypt cipher function on a block using a key
89  * IV: initialization vector - used as feedback for chaining
90  * N:  number used once (nonce)
91  * FB: feedback is the next IV in a chained/feedback mode
92  */
93 
94 /* -----
95  * NOTE:
96  * 'in' can be the same as 'out' but other overlaps are dangers as a block at a
97  * time is written. The code does not look for overlaps at this point.
98  */
99 
100 /* ----------
101  * Electronic Code Book - simple cipher with no chaining feedback  just iterate
102  * simple encrypt/decrypt with the plain, text, cipher text and key/
103  *
104  * CT = ENC (PT,EK)
105  * PT = DEC (CT,DK)
106  */
107 
108 /* -----
109  * NOTE: currently an implmentation detail limits us to 8192 bit cipher block
110  * size.  Changing MAX_BLOCK_SIZE in cipher.c can up that limit without
111  * causing any other compatibility issues.
112  *
113  * Two local byte arrays are defined on the stack of 1024 bytes or 8192 bits.
114  */
115 KRYPTO_EXTERN rc_t CC KCipherEncryptECB (KCipher * self, const void * in, void * out,
116                                          uint32_t block_count);
117 
118 KRYPTO_EXTERN rc_t CC KCipherDecryptECB (KCipher * self, const void * in, void * out,
119                                          uint32_t block_count);
120 
121 /* ----------
122  * Cipher-Block Chaining
123  * CT = (FB = ENC (PT^IV, EK))
124  * PT = DEC ((FB = CT), DK)
125  *
126  */
127 KRYPTO_EXTERN rc_t CC KCipherEncryptCBC (KCipher * self, const void * in, void * out,
128                                          uint32_t block_count);
129 
130 KRYPTO_EXTERN rc_t CC KCipherDecryptCBC (KCipher * self, const void * in, void * out,
131                                          uint32_t block_count);
132 
133 /* ----------
134  * Propagating cipher-block chaining
135  * FB = PT ^ (CT = ENC ((PT^IV), EK))
136  * FB = CT ^ (PT = DEC (CT,DK) ^ IV)
137  */
138 
139 /* not yet implemented */
140 
141 /* ----------
142  * Cipher Feedback
143  * CT = (FB = PT) ^ ENC (IV, EK))
144  * PT = (FB = CT) ^ ENC (IV, DK)
145  *
146  * NOTE the use of the encrypt function for decryption
147  *
148  * Not implemented as the openssl does something different
149  */
150 KRYPTO_EXTERN
151 rc_t CC KCipherEncryptCFB (KCipher * self, const void * in, void * out,
152                            uint32_t block_count);
153 
154 KRYPTO_EXTERN
155 rc_t CC KCipherDecryptCFB (KCipher * self, const void * in, void * out,
156                            uint32_t block_count);
157 
158 KRYPTO_EXTERN
159 rc_t CC KCipherEncryptPCFB (KCipher * self, const void * in, void * out,
160                             uint32_t block_count);
161 
162 KRYPTO_EXTERN
163 rc_t CC KCipherDecryptPCFB (KCipher * self, const void * in, void * out,
164                             uint32_t block_count);
165 
166 /* ----------
167  * Output Feedback
168  * CT = PT ^ (FB = ENC (IV, EK))
169  * PT = CT ^ (FB = ENC (IV, DK))
170  *
171  * NOTE the use of the encrypt function for decryption
172  *
173  * Not implemented as the openssl does something different
174  */
175 KRYPTO_EXTERN
176 rc_t CC KCipherEncryptOFB (KCipher * self, const void * in, void * out,
177                            uint32_t block_count);
178 
179 KRYPTO_EXTERN
180 rc_t CC KCipherDecryptOFB (KCipher * self, const void * in, void * out,
181                            uint32_t block_count);
182 
183 /* ----------
184  * Counter
185  * IV is a nonce and not re-used as FB
186  * CT = PT ^ ENC (N, EK)
187  * PT = CT ^ ENC (N, DK)
188  *
189  * NOTE the use of the encrypt function for decryption
190  *
191  * nonce is a function that given an iv generates the next iv
192  *
193  */
194 KRYPTO_EXTERN
195 rc_t CC KCipherEncryptCTR (KCipher * self, const void * in,
196                            void * out, uint32_t block_count);
197 KRYPTO_EXTERN
198 rc_t CC KCipherDecryptCTR (KCipher * self, const void * in,
199                            void * out, uint32_t block_count);
200 
201 
202 
203 
204 #ifdef __cplusplus
205 }
206 #endif
207 
208 #endif /* #ifndef _h_krypto_cipher_ */
209