include/rtl/cipher.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef INCLUDED_RTL_CIPHER_H
  21 #define INCLUDED_RTL_CIPHER_H
  22
  23 #include <sal/config.h>
  24
  25 #include <sal/saldllapi.h>
  26 #include <sal/types.h>
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 /*========================================================================
  33  *
  34  * rtlCipher interface.
  35  *
  36  *======================================================================*/
  37 /** Cipher Handle opaque type.
  38  */
  39 typedef void* rtlCipher;
  40
  41
  42 /** Cipher Algorithm enumeration.
  43     @see rtl_cipher_create()
  44  */
  45 enum __rtl_CipherAlgorithm
  46 {
  47     rtl_Cipher_AlgorithmBF,
  48     rtl_Cipher_AlgorithmARCFOUR,
  49     rtl_Cipher_AlgorithmInvalid,
  50     rtl_Cipher_Algorithm_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
  51 };
  52
  53 /** Cipher Algorithm type.
  54  */
  55 typedef enum __rtl_CipherAlgorithm rtlCipherAlgorithm;
  56
  57
  58 /** Cipher Mode enumeration.
  59     @see rtl_cipher_create()
  60  */
  61 enum __rtl_CipherMode
  62 {
  63     rtl_Cipher_ModeECB,
  64     rtl_Cipher_ModeCBC,
  65     rtl_Cipher_ModeStream,
  66     rtl_Cipher_ModeInvalid,
  67     rtl_Cipher_Mode_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
  68 };
  69
  70 /** Cipher Mode type.
  71  */
  72 typedef enum __rtl_CipherMode rtlCipherMode;
  73
  74
  75 /** Cipher Direction enumeration.
  76     @see rtl_cipher_init()
  77  */
  78 enum __rtl_CipherDirection
  79 {
  80     rtl_Cipher_DirectionBoth,
  81     rtl_Cipher_DirectionDecode,
  82     rtl_Cipher_DirectionEncode,
  83     rtl_Cipher_DirectionInvalid,
  84     rtl_Cipher_Direction_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
  85 };
  86
  87 /** Cipher Direction type.
  88  */
  89 typedef enum __rtl_CipherDirection rtlCipherDirection;
  90
  91
  92 /** Error Code enumeration.
  93  */
  94 enum __rtl_CipherError
  95 {
  96     rtl_Cipher_E_None,
  97     rtl_Cipher_E_Argument,
  98     rtl_Cipher_E_Algorithm,
  99     rtl_Cipher_E_Direction,
 100     rtl_Cipher_E_Mode,
 101     rtl_Cipher_E_BufferSize,
 102     rtl_Cipher_E_Memory,
 103     rtl_Cipher_E_Unknown,
 104     rtl_Cipher_E_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
 105 };
 106
 107 /** Error Code type.
 108  */
 109 typedef enum __rtl_CipherError rtlCipherError;
 110
 111
 112 /** Create a cipher handle for the given algorithm and mode.
 113     @see rtlCipherAlgorithm
 114     @see rtlCipherMode
 115
 116     @param  Algorithm [in] cipher algorithm.
 117     @param  Mode      [in] cipher mode.
 118     @return Cipher handle, or 0 upon failure.
 119  */
 120 SAL_DLLPUBLIC rtlCipher SAL_CALL rtl_cipher_create (
 121     rtlCipherAlgorithm Algorithm,
 122     rtlCipherMode      Mode
 123 ) SAL_THROW_EXTERN_C();
 124
 125
 126 /** Inititialize a cipher for the given direction.
 127     @see rtlCipherDirection
 128
 129     @param  Cipher    [in] cipher handle.
 130     @param  Direction [in] cipher direction.
 131     @param  pKeyData  [in] key material buffer.
 132     @param  nKeyLen   [in] key material length in bytes.
 133     @param  pArgData  [in] initialization vector buffer.
 134     @param  nArgLen   [in] initialization vector length in bytes.
 135     @return rtl_Cipher_E_None upon success.
 136  */
 137 SAL_DLLPUBLIC rtlCipherError SAL_CALL rtl_cipher_init (
 138     rtlCipher           Cipher,
 139     rtlCipherDirection  Direction,
 140     const sal_uInt8    *pKeyData, sal_Size nKeyLen,
 141     const sal_uInt8    *pArgData, sal_Size nArgLen
 142 ) SAL_THROW_EXTERN_C();
 143
 144
 145 /** Encode a buffer under a given cipher algorithm.
 146     @pre Initialized for a compatible cipher direction.
 147     @see     rtl_cipher_init()
 148
 149     @param  Cipher  [in]  cipher handle.
 150     @param  pData   [in]  plaintext buffer.
 151     @param  nDatLen [in]  plaintext length in bytes.
 152     @param  pBuffer [out] ciphertext buffer.
 153     @param  nBufLen [in]  ciphertext length in bytes.
 154     @return rtl_Cipher_E_None upon success.
 155  */
 156 SAL_DLLPUBLIC rtlCipherError SAL_CALL rtl_cipher_encode (
 157     rtlCipher   Cipher,
 158     const void *pData,   sal_Size nDatLen,
 159     sal_uInt8  *pBuffer, sal_Size nBufLen
 160 ) SAL_THROW_EXTERN_C();
 161
 162
 163 /** Decode a buffer under a given cipher algorithm.
 164     @pre Initialized for a compatible cipher direction.
 165     @see     rtl_cipher_init()
 166
 167     @param  Cipher  [in]  cipher handle.
 168     @param  pData   [in]  ciphertext buffer.
 169     @param  nDatLen [in]  ciphertext length in bytes.
 170     @param  pBuffer [out] plaintext buffer.
 171     @param  nBufLen [in]  plaintext length in bytes.
 172     @return rtl_Cipher_E_None upon success.
 173  */
 174 SAL_DLLPUBLIC rtlCipherError SAL_CALL rtl_cipher_decode (
 175     rtlCipher   Cipher,
 176     const void *pData,   sal_Size nDatLen,
 177     sal_uInt8  *pBuffer, sal_Size nBufLen
 178 ) SAL_THROW_EXTERN_C();
 179
 180
 181 /** Destroy a cipher handle.
 182     @param  Cipher [in] cipher handle to be destroyed.
 183     @return None. Cipher handle destroyed and invalid.
 184  */
 185 SAL_DLLPUBLIC void SAL_CALL rtl_cipher_destroy (
 186     rtlCipher Cipher
 187 ) SAL_THROW_EXTERN_C();
 188
 189
 190 /*========================================================================
 191  *
 192  * rtl_cipherBF (Blowfish) interface.
 193  *
 194  *======================================================================*/
 195 /** Create a Blowfish cipher handle for the given mode.
 196
 197     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 SAL_DLLPUBLIC 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 SAL_DLLPUBLIC 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 SAL_DLLPUBLIC 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 SAL_DLLPUBLIC 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 SAL_DLLPUBLIC 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
 253     The RC4 symmetric stream cipher algorithm is specified in
 254     Bruce Schneier: Applied Cryptography, 2nd edition, ch. 17.1
 255
 256     @see rtl_cipher_create()
 257
 258     @param  Mode [in] cipher mode. Must be rtl_Cipher_ModeStream.
 259     @return Cipher handle, or 0 upon failure.
 260  */
 261 SAL_DLLPUBLIC rtlCipher SAL_CALL rtl_cipher_createARCFOUR (
 262     rtlCipherMode Mode
 263 ) SAL_THROW_EXTERN_C();
 264
 265
 266 /** Inititialize a RC4 cipher for the given direction.
 267     @see rtl_cipher_init()
 268  */
 269 SAL_DLLPUBLIC rtlCipherError SAL_CALL rtl_cipher_initARCFOUR (
 270     rtlCipher          Cipher,
 271     rtlCipherDirection Direction,
 272     const sal_uInt8 *pKeyData, sal_Size nKeyLen,
 273     const sal_uInt8 *pArgData, sal_Size nArgLen
 274 ) SAL_THROW_EXTERN_C();
 275
 276
 277 /** Encode a buffer under the RC4 cipher algorithm.
 278     @see rtl_cipher_encode()
 279  */
 280 SAL_DLLPUBLIC rtlCipherError SAL_CALL rtl_cipher_encodeARCFOUR (
 281     rtlCipher   Cipher,
 282     const void *pData,   sal_Size nDatLen,
 283     sal_uInt8  *pBuffer, sal_Size nBufLen
 284 ) SAL_THROW_EXTERN_C();
 285
 286
 287 /** Decode a buffer under the RC4 cipher algorithm.
 288     @see rtl_cipher_decode()
 289  */
 290 SAL_DLLPUBLIC rtlCipherError SAL_CALL rtl_cipher_decodeARCFOUR (
 291     rtlCipher   Cipher,
 292     const void *pData,   sal_Size nDatLen,
 293     sal_uInt8  *pBuffer, sal_Size nBufLen
 294 ) SAL_THROW_EXTERN_C();
 295
 296
 297 /** Destroy a RC4 cipher handle.
 298     @see rtl_cipher_destroy()
 299  */
 300 SAL_DLLPUBLIC void SAL_CALL rtl_cipher_destroyARCFOUR (
 301     rtlCipher Cipher
 302 ) SAL_THROW_EXTERN_C();
 303
 304
 305 /*========================================================================
 306  *
 307  * The End.
 308  *
 309  *======================================================================*/
 310
 311 #ifdef __cplusplus
 312 }
 313 #endif
 314
 315 #endif /* ! INCLUDED_RTL_CIPHER_H */
 316
 317 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */