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 /** Cipher Handle opaque type.
  33  */
  34 typedef void* rtlCipher;
  35
  36 /** Cipher Algorithm enumeration.
  37     @see rtl_cipher_create()
  38  */
  39 enum __rtl_CipherAlgorithm
  40 {
  41     rtl_Cipher_AlgorithmBF,
  42     rtl_Cipher_AlgorithmARCFOUR,
  43     rtl_Cipher_AlgorithmInvalid,
  44     rtl_Cipher_Algorithm_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
  45 };
  46
  47 /** Cipher Algorithm type.
  48  */
  49 typedef enum __rtl_CipherAlgorithm rtlCipherAlgorithm;
  50
  51 /** Cipher Mode enumeration.
  52     @see rtl_cipher_create()
  53  */
  54 enum __rtl_CipherMode
  55 {
  56     rtl_Cipher_ModeECB,
  57     rtl_Cipher_ModeCBC,
  58     rtl_Cipher_ModeStream,
  59     rtl_Cipher_ModeInvalid,
  60     rtl_Cipher_Mode_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
  61 };
  62
  63 /** Cipher Mode type.
  64  */
  65 typedef enum __rtl_CipherMode rtlCipherMode;
  66
  67 /** Cipher Direction enumeration.
  68     @see rtl_cipher_init()
  69  */
  70 enum __rtl_CipherDirection
  71 {
  72     rtl_Cipher_DirectionBoth,
  73     rtl_Cipher_DirectionDecode,
  74     rtl_Cipher_DirectionEncode,
  75     rtl_Cipher_DirectionInvalid,
  76     rtl_Cipher_Direction_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
  77 };
  78
  79 /** Cipher Direction type.
  80  */
  81 typedef enum __rtl_CipherDirection rtlCipherDirection;
  82
  83
  84 /** Error Code enumeration.
  85  */
  86 enum __rtl_CipherError
  87 {
  88     rtl_Cipher_E_None,
  89     rtl_Cipher_E_Argument,
  90     rtl_Cipher_E_Algorithm,
  91     rtl_Cipher_E_Direction,
  92     rtl_Cipher_E_Mode,
  93     rtl_Cipher_E_BufferSize,
  94     rtl_Cipher_E_Memory,
  95     rtl_Cipher_E_Unknown,
  96     rtl_Cipher_E_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
  97 };
  98
  99 /** Error Code type.
 100  */
 101 typedef enum __rtl_CipherError rtlCipherError;
 102
 103
 104 /** Create a cipher handle for the given algorithm and mode.
 105     @see rtlCipherAlgorithm
 106     @see rtlCipherMode
 107
 108     @param[in] Algorithm cipher algorithm.
 109     @param[in] Mode      cipher mode.
 110     @return Cipher handle, or 0 upon failure.
 111  */
 112 SAL_DLLPUBLIC rtlCipher SAL_CALL rtl_cipher_create (
 113     rtlCipherAlgorithm Algorithm,
 114     rtlCipherMode      Mode
 115 ) SAL_THROW_EXTERN_C();
 116
 117 /** Inititialize a cipher for the given direction.
 118     @see rtlCipherDirection
 119
 120     @param[in] Cipher    cipher handle.
 121     @param[in] Direction cipher direction.
 122     @param[in] pKeyData  key material buffer.
 123     @param[in] nKeyLen   key material length in bytes.
 124     @param[in] pArgData  initialization vector buffer.
 125     @param[in] nArgLen   initialization vector length in bytes.
 126     @retval rtl_Cipher_E_None upon success.
 127  */
 128 SAL_DLLPUBLIC rtlCipherError SAL_CALL rtl_cipher_init (
 129     rtlCipher           Cipher,
 130     rtlCipherDirection  Direction,
 131     const sal_uInt8    *pKeyData, sal_Size nKeyLen,
 132     const sal_uInt8    *pArgData, sal_Size nArgLen
 133 ) SAL_THROW_EXTERN_C();
 134
 135 /** Encode a buffer under a given cipher algorithm.
 136     @pre Initialized for a compatible cipher direction.
 137     @see     rtl_cipher_init()
 138
 139     @param[in]  Cipher  cipher handle.
 140     @param[in]  pData   plaintext buffer.
 141     @param[in]  nDatLen plaintext length in bytes.
 142     @param[out] pBuffer ciphertext buffer.
 143     @param[in]  nBufLen ciphertext length in bytes.
 144     @retval rtl_Cipher_E_None upon success.
 145  */
 146 SAL_DLLPUBLIC rtlCipherError SAL_CALL rtl_cipher_encode (
 147     rtlCipher   Cipher,
 148     const void *pData,   sal_Size nDatLen,
 149     sal_uInt8  *pBuffer, sal_Size nBufLen
 150 ) SAL_THROW_EXTERN_C();
 151
 152 /** Decode a buffer under a given cipher algorithm.
 153     @pre Initialized for a compatible cipher direction.
 154     @see     rtl_cipher_init()
 155
 156     @param[in]  Cipher  cipher handle.
 157     @param[in]  pData   ciphertext buffer.
 158     @param[in]  nDatLen ciphertext length in bytes.
 159     @param[out] pBuffer plaintext buffer.
 160     @param[in]  nBufLen plaintext length in bytes.
 161     @retval rtl_Cipher_E_None upon success.
 162  */
 163 SAL_DLLPUBLIC rtlCipherError SAL_CALL rtl_cipher_decode (
 164     rtlCipher   Cipher,
 165     const void *pData,   sal_Size nDatLen,
 166     sal_uInt8  *pBuffer, sal_Size nBufLen
 167 ) SAL_THROW_EXTERN_C();
 168
 169 /** Destroy a cipher handle.
 170     @param[in] Cipher cipher handle to be destroyed.
 171     @return None. Cipher handle destroyed and invalid.
 172  */
 173 SAL_DLLPUBLIC void SAL_CALL rtl_cipher_destroy (
 174     rtlCipher Cipher
 175 ) SAL_THROW_EXTERN_C();
 176
 177 /** Create a Blowfish cipher handle for the given mode.
 178
 179     The Blowfish block cipher algorithm is specified in
 180     Bruce Schneier: Applied Cryptography, 2nd edition, ch. 14.3
 181
 182     @see rtl_cipher_create()
 183  */
 184 SAL_DLLPUBLIC rtlCipher SAL_CALL rtl_cipher_createBF (
 185     rtlCipherMode Mode
 186 ) SAL_THROW_EXTERN_C();
 187
 188 /** Inititialize a Blowfish cipher for the given direction.
 189     @see rtl_cipher_init()
 190  */
 191 SAL_DLLPUBLIC rtlCipherError SAL_CALL rtl_cipher_initBF (
 192     rtlCipher          Cipher,
 193     rtlCipherDirection Direction,
 194     const sal_uInt8 *pKeyData, sal_Size nKeyLen,
 195     const sal_uInt8 *pArgData, sal_Size nArgLen
 196 ) SAL_THROW_EXTERN_C();
 197
 198 /** Encode a buffer under the Blowfish cipher algorithm.
 199     @see rtl_cipher_encode()
 200  */
 201 SAL_DLLPUBLIC rtlCipherError SAL_CALL rtl_cipher_encodeBF (
 202     rtlCipher   Cipher,
 203     const void *pData,   sal_Size nDatLen,
 204     sal_uInt8  *pBuffer, sal_Size nBufLen
 205 ) SAL_THROW_EXTERN_C();
 206
 207 /** Decode a buffer under the Blowfish cipher algorithm.
 208     @see rtl_cipher_decode()
 209  */
 210 SAL_DLLPUBLIC rtlCipherError SAL_CALL rtl_cipher_decodeBF (
 211     rtlCipher   Cipher,
 212     const void *pData,   sal_Size nDatLen,
 213     sal_uInt8  *pBuffer, sal_Size nBufLen
 214 ) SAL_THROW_EXTERN_C();
 215
 216 /** Destroy a Blowfish cipher handle.
 217     @see rtl_cipher_destroy()
 218  */
 219 SAL_DLLPUBLIC void SAL_CALL rtl_cipher_destroyBF (
 220     rtlCipher Cipher
 221 ) SAL_THROW_EXTERN_C();
 222
 223 /** Create a RC4 cipher handle for the given mode.
 224
 225     The RC4 symmetric stream cipher algorithm is specified in
 226     Bruce Schneier: Applied Cryptography, 2nd edition, ch. 17.1
 227
 228     @see rtl_cipher_create()
 229
 230     @param[in] Mode cipher mode. Must be <code>rtl_Cipher_ModeStream</code>.
 231     @return Cipher handle, or 0 upon failure.
 232  */
 233 SAL_DLLPUBLIC rtlCipher SAL_CALL rtl_cipher_createARCFOUR (
 234     rtlCipherMode Mode
 235 ) SAL_THROW_EXTERN_C();
 236
 237 /** Inititialize a RC4 cipher for the given direction.
 238     @see rtl_cipher_init()
 239  */
 240 SAL_DLLPUBLIC rtlCipherError SAL_CALL rtl_cipher_initARCFOUR (
 241     rtlCipher          Cipher,
 242     rtlCipherDirection Direction,
 243     const sal_uInt8 *pKeyData, sal_Size nKeyLen,
 244     const sal_uInt8 *pArgData, sal_Size nArgLen
 245 ) SAL_THROW_EXTERN_C();
 246
 247 /** Encode a buffer under the RC4 cipher algorithm.
 248     @see rtl_cipher_encode()
 249  */
 250 SAL_DLLPUBLIC rtlCipherError SAL_CALL rtl_cipher_encodeARCFOUR (
 251     rtlCipher   Cipher,
 252     const void *pData,   sal_Size nDatLen,
 253     sal_uInt8  *pBuffer, sal_Size nBufLen
 254 ) SAL_THROW_EXTERN_C();
 255
 256 /** Decode a buffer under the RC4 cipher algorithm.
 257     @see rtl_cipher_decode()
 258  */
 259 SAL_DLLPUBLIC rtlCipherError SAL_CALL rtl_cipher_decodeARCFOUR (
 260     rtlCipher   Cipher,
 261     const void *pData,   sal_Size nDatLen,
 262     sal_uInt8  *pBuffer, sal_Size nBufLen
 263 ) SAL_THROW_EXTERN_C();
 264
 265 /** Destroy a RC4 cipher handle.
 266     @see rtl_cipher_destroy()
 267  */
 268 SAL_DLLPUBLIC void SAL_CALL rtl_cipher_destroyARCFOUR (
 269     rtlCipher Cipher
 270 ) SAL_THROW_EXTERN_C();
 271
 272 #ifdef __cplusplus
 273 }
 274 #endif
 275
 276 #endif /* ! INCLUDED_RTL_CIPHER_H */
 277
 278 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */