xref: /aoo42x/main/sal/inc/rtl/cipher.h (revision b9fd132d)
1 /**************************************************************
2  *
3  * Licensed to the Apache Software Foundation (ASF) under one
4  * or more contributor license agreements.  See the NOTICE file
5  * distributed with this work for additional information
6  * regarding copyright ownership.  The ASF licenses this file
7  * to you under the Apache License, Version 2.0 (the
8  * "License"); you may not use this file except in compliance
9  * with the License.  You may obtain a copy of the License at
10  *
11  *   http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing,
14  * software distributed under the License is distributed on an
15  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16  * KIND, either express or implied.  See the License for the
17  * specific language governing permissions and limitations
18  * under the License.
19  *
20  *************************************************************/
21 
22 
23 
24 #ifndef _RTL_CIPHER_H_
25 #define _RTL_CIPHER_H_ "$Revision$"
26 
27 #include <sal/types.h>
28 
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32 
33 /*========================================================================
34  *
35  * rtlCipher interface.
36  *
37  *======================================================================*/
38 /** Cipher Handle opaque type.
39  */
40 typedef void* rtlCipher;
41 
42 
43 /** Cipher Algorithm enumeration.
44 	@see rtl_cipher_create()
45  */
46 enum __rtl_CipherAlgorithm
47 {
48 	rtl_Cipher_AlgorithmBF,
49 	rtl_Cipher_AlgorithmARCFOUR,
50 	rtl_Cipher_AlgorithmInvalid,
51 	rtl_Cipher_Algorithm_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
52 };
53 
54 /** Cipher Algorithm type.
55  */
56 typedef enum __rtl_CipherAlgorithm rtlCipherAlgorithm;
57 
58 
59 /** Cipher Mode enumeration.
60 	@see rtl_cipher_create()
61  */
62 enum __rtl_CipherMode
63 {
64 	rtl_Cipher_ModeECB,
65 	rtl_Cipher_ModeCBC,
66 	rtl_Cipher_ModeStream,
67 	rtl_Cipher_ModeInvalid,
68 	rtl_Cipher_Mode_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
69 };
70 
71 /** Cipher Mode type.
72  */
73 typedef enum __rtl_CipherMode rtlCipherMode;
74 
75 
76 /** Cipher Direction enumeration.
77 	@see rtl_cipher_init()
78  */
79 enum __rtl_CipherDirection
80 {
81 	rtl_Cipher_DirectionBoth,
82 	rtl_Cipher_DirectionDecode,
83 	rtl_Cipher_DirectionEncode,
84 	rtl_Cipher_DirectionInvalid,
85 	rtl_Cipher_Direction_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
86 };
87 
88 /** Cipher Direction type.
89  */
90 typedef enum __rtl_CipherDirection rtlCipherDirection;
91 
92 
93 /** Error Code enumeration.
94  */
95 enum __rtl_CipherError
96 {
97 	rtl_Cipher_E_None,
98 	rtl_Cipher_E_Argument,
99 	rtl_Cipher_E_Algorithm,
100 	rtl_Cipher_E_Direction,
101 	rtl_Cipher_E_Mode,
102 	rtl_Cipher_E_BufferSize,
103 	rtl_Cipher_E_Memory,
104 	rtl_Cipher_E_Unknown,
105 	rtl_Cipher_E_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
106 };
107 
108 /** Error Code type.
109  */
110 typedef enum __rtl_CipherError rtlCipherError;
111 
112 
113 /** Create a cipher handle for the given algorithm and mode.
114     @see rtlCipherAlgorithm
115     @see rtlCipherMode
116 
117 	@param  Algorithm [in] cipher algorithm.
118 	@param  Mode      [in] cipher mode.
119 	@return Cipher handle, or 0 upon failure.
120  */
121 rtlCipher SAL_CALL rtl_cipher_create (
122 	rtlCipherAlgorithm Algorithm,
123 	rtlCipherMode      Mode
124 ) SAL_THROW_EXTERN_C();
125 
126 
127 /** Inititialize a cipher for the given direction.
128     @see rtlCipherDirection
129 
130 	@param  Cipher    [in] cipher handle.
131 	@param  Direction [in] cipher direction.
132 	@param  pKeyData  [in] key material buffer.
133 	@param  nKeyLen   [in] key material length in bytes.
134 	@param  pArgData  [in] initialization vector buffer.
135 	@param  nArgLen   [in] initialization vector length in bytes.
136 	@return rtl_Cipher_E_None upon success.
137  */
138 rtlCipherError SAL_CALL rtl_cipher_init (
139 	rtlCipher           Cipher,
140 	rtlCipherDirection  Direction,
141 	const sal_uInt8    *pKeyData, sal_Size nKeyLen,
142 	const sal_uInt8    *pArgData, sal_Size nArgLen
143 ) SAL_THROW_EXTERN_C();
144 
145 
146 /** Encode a buffer under a given cipher algorithm.
147     @precond Initialized for a compatible cipher direction.
148 	@see     rtl_cipher_init()
149 
150 	@param  Cipher  [in]  cipher handle.
151 	@param  pData   [in]  plaintext buffer.
152 	@param  nDatLen [in]  plaintext length in bytes.
153 	@param  pBuffer [out] ciphertext buffer.
154 	@param  nBufLen [in]  ciphertext length in bytes.
155 	@return rtl_Cipher_E_None upon success.
156  */
157 rtlCipherError SAL_CALL rtl_cipher_encode (
158 	rtlCipher   Cipher,
159 	const void *pData,   sal_Size nDatLen,
160 	sal_uInt8  *pBuffer, sal_Size nBufLen
161 ) SAL_THROW_EXTERN_C();
162 
163 
164 /** Decode a buffer under a given cipher algorithm.
165     @precond Initialized for a compatible cipher direction.
166 	@see     rtl_cipher_init()
167 
168 	@param  Cipher  [in]  cipher handle.
169 	@param  pData   [in]  ciphertext buffer.
170 	@param  nDatLen [in]  ciphertext length in bytes.
171 	@param  pBuffer [out] plaintext buffer.
172 	@param  nBufLen [in]  plaintext length in bytes.
173 	@return rtl_Cipher_E_None upon success.
174  */
175 rtlCipherError SAL_CALL rtl_cipher_decode (
176 	rtlCipher   Cipher,
177 	const void *pData,   sal_Size nDatLen,
178 	sal_uInt8  *pBuffer, sal_Size nBufLen
179 ) SAL_THROW_EXTERN_C();
180 
181 
182 /** Destroy a cipher handle.
183 	@param  Cipher [in] cipher handle to be destroyed.
184 	@return None. Cipher handle destroyed and invalid.
185  */
186 void SAL_CALL rtl_cipher_destroy (
187 	rtlCipher Cipher
188 ) SAL_THROW_EXTERN_C();
189 
190 
191 /*========================================================================
192  *
193  * rtl_cipherBF (Blowfish) interface.
194  *
195  *======================================================================*/
196 /** Create a Blowfish cipher handle for the given mode.
197     @descr The Blowfish block cipher algorithm is specified in
198 	Bruce Schneier: Applied Cryptography, 2nd edition, ch. 14.3
199 
200 	@see rtl_cipher_create()
201  */
202 rtlCipher SAL_CALL rtl_cipher_createBF (
203 	rtlCipherMode Mode
204 ) SAL_THROW_EXTERN_C();
205 
206 
207 /** Inititialize a Blowfish cipher for the given direction.
208 	@see rtl_cipher_init()
209  */
210 rtlCipherError SAL_CALL rtl_cipher_initBF (
211 	rtlCipher          Cipher,
212 	rtlCipherDirection Direction,
213 	const sal_uInt8 *pKeyData, sal_Size nKeyLen,
214 	const sal_uInt8 *pArgData, sal_Size nArgLen
215 ) SAL_THROW_EXTERN_C();
216 
217 
218 /** Encode a buffer under the Blowfish cipher algorithm.
219 	@see rtl_cipher_encode()
220  */
221 rtlCipherError SAL_CALL rtl_cipher_encodeBF (
222 	rtlCipher   Cipher,
223 	const void *pData,   sal_Size nDatLen,
224 	sal_uInt8  *pBuffer, sal_Size nBufLen
225 ) SAL_THROW_EXTERN_C();
226 
227 
228 /** Decode a buffer under the Blowfish cipher algorithm.
229 	@see rtl_cipher_decode()
230  */
231 rtlCipherError SAL_CALL rtl_cipher_decodeBF (
232 	rtlCipher   Cipher,
233 	const void *pData,   sal_Size nDatLen,
234 	sal_uInt8  *pBuffer, sal_Size nBufLen
235 ) SAL_THROW_EXTERN_C();
236 
237 
238 /** Destroy a Blowfish cipher handle.
239 	@see rtl_cipher_destroy()
240  */
241 void SAL_CALL rtl_cipher_destroyBF (
242 	rtlCipher Cipher
243 ) SAL_THROW_EXTERN_C();
244 
245 
246 /*========================================================================
247  *
248  * rtl_cipherARCFOUR (RC4) interface.
249  *
250  *======================================================================*/
251 /** Create a RC4 cipher handle for the given mode.
252     @descr The RC4 symmetric stream cipher algorithm is specified in
253 	Bruce Schneier: Applied Cryptography, 2nd edition, ch. 17.1
254 
255 	@see rtl_cipher_create()
256 
257 	@param  Mode [in] cipher mode. Must be rtl_Cipher_ModeStream.
258 	@return Cipher handle, or 0 upon failure.
259  */
260 rtlCipher SAL_CALL rtl_cipher_createARCFOUR (
261 	rtlCipherMode Mode
262 ) SAL_THROW_EXTERN_C();
263 
264 
265 /** Inititialize a RC4 cipher for the given direction.
266 	@see rtl_cipher_init()
267  */
268 rtlCipherError SAL_CALL rtl_cipher_initARCFOUR (
269 	rtlCipher          Cipher,
270 	rtlCipherDirection Direction,
271 	const sal_uInt8 *pKeyData, sal_Size nKeyLen,
272 	const sal_uInt8 *pArgData, sal_Size nArgLen
273 ) SAL_THROW_EXTERN_C();
274 
275 
276 /** Encode a buffer under the RC4 cipher algorithm.
277 	@see rtl_cipher_encode()
278  */
279 rtlCipherError SAL_CALL rtl_cipher_encodeARCFOUR (
280 	rtlCipher   Cipher,
281 	const void *pData,   sal_Size nDatLen,
282 	sal_uInt8  *pBuffer, sal_Size nBufLen
283 ) SAL_THROW_EXTERN_C();
284 
285 
286 /** Decode a buffer under the RC4 cipher algorithm.
287 	@see rtl_cipher_decode()
288  */
289 rtlCipherError SAL_CALL rtl_cipher_decodeARCFOUR (
290 	rtlCipher   Cipher,
291 	const void *pData,   sal_Size nDatLen,
292 	sal_uInt8  *pBuffer, sal_Size nBufLen
293 ) SAL_THROW_EXTERN_C();
294 
295 
296 /** Destroy a RC4 cipher handle.
297 	@see rtl_cipher_destroy()
298  */
299 void SAL_CALL rtl_cipher_destroyARCFOUR (
300 	rtlCipher Cipher
301 ) SAL_THROW_EXTERN_C();
302 
303 
304 /*========================================================================
305  *
306  * The End.
307  *
308  *======================================================================*/
309 
310 #ifdef __cplusplus
311 }
312 #endif
313 
314 #endif /* !_RTL_CIPHER_H_ */
315 
316