sal/inc/rtl/cipher.h

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