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