api/yaca/yaca_types.h

   1 /*
   2  *  Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  *  Contact: Krzysztof Jackiewicz <k.jackiewicz@samsung.com>
   5  *
   6  *  Licensed under the Apache License, Version 2.0 (the "License");
   7  *  you may not use this file except in compliance with the License.
   8  *  You may obtain a copy of the License at
   9  *
  10  *      http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  *  Unless required by applicable law or agreed to in writing, software
  13  *  distributed under the License is distributed on an "AS IS" BASIS,
  14  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  *  See the License for the specific language governing permissions and
  16  *  limitations under the License
  17  */
  18
  19 /**
  20  * @file yaca_types.h
  21  * @brief
  22  */
  23
  24 #ifndef YACA_TYPES_H
  25 #define YACA_TYPES_H
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif
  30
  31 /**
  32  * @defgroup Crypto-Types Yet Another Crypto API - types.
  33  *
  34  *
  35  * @{
  36  */
  37
  38 /**
  39  * @brief Context.
  40  *
  41  * @since_tizen 3.0
  42  */
  43 typedef struct yaca_context_s *yaca_context_h;
  44
  45 /**
  46  * @brief Key.
  47  *
  48  * @since_tizen 3.0
  49  */
  50 typedef struct yaca_key_s *yaca_key_h;
  51
  52 /**
  53  * @brief Enumeration of YACA key formats.
  54  *
  55  * @since_tizen 3.0
  56  */
  57 typedef enum {
  58         /** Key is either PKCS#1 for RSA or SSLeay for DSA, also use this option for symmetric */
  59         YACA_KEY_FORMAT_DEFAULT,
  60         /** Key is in PKCS#8, can only be used for asymmetric private keys */
  61         YACA_KEY_FORMAT_PKCS8
  62 } yaca_key_format_e;
  63
  64 /**
  65  * @brief Enumeration of YACA key file formats.
  66  *
  67  * @since_tizen 3.0
  68  */
  69 typedef enum {
  70         /** Key file is in raw binary format, used for symmetric keys */
  71         YACA_KEY_FILE_FORMAT_RAW,
  72         /** Key file is encoded in ASCII-base64, used for symmetric keys */
  73         YACA_KEY_FILE_FORMAT_BASE64,
  74         /** Key file is in PEM file format, used for asymmetric keys */
  75         YACA_KEY_FILE_FORMAT_PEM,
  76         /** Key file is in DER file format, used for asymmetric keys */
  77         YACA_KEY_FILE_FORMAT_DER
  78 } yaca_key_file_format_e;
  79
  80 /**
  81  * @brief Enumeration of YACA key types, IV is considered as key.
  82  *
  83  * @since_tizen 3.0
  84  */
  85 typedef enum {
  86         /** Generic symmetric cipher KEY */
  87         YACA_KEY_TYPE_SYMMETRIC,
  88         /** DES* key - must be handled differently because of parity bits */
  89         YACA_KEY_TYPE_DES,
  90         /** Initialization Vector for symmetric algorithms */
  91         YACA_KEY_TYPE_IV,
  92
  93         /** RSA public key */
  94         YACA_KEY_TYPE_RSA_PUB,
  95         /** RSA private key */
  96         YACA_KEY_TYPE_RSA_PRIV,
  97
  98         /** Digital Signature Algorithm public key */
  99         YACA_KEY_TYPE_DSA_PUB,
 100         /** Digital Signature Algorithm private key */
 101         YACA_KEY_TYPE_DSA_PRIV,
 102 } yaca_key_type_e;
 103
 104 /**
 105  * @brief Enumeration of YACA key lengths.
 106  *        It is possible to use arbitrary integer instead,
 107  *        this enum values are placed here to avoid magic numbers.
 108  *
 109  * @since_tizen 3.0
 110  */
 111 typedef enum {
 112         YACA_KEY_LENGTH_IV_UNSAFE_24BIT = 24,
 113         YACA_KEY_LENGTH_IV_64BIT = 64,
 114         YACA_KEY_LENGTH_IV_128BIT = 128,
 115         YACA_KEY_LENGTH_IV_256BIT = 256,
 116         YACA_KEY_LENGTH_UNSAFE_8BIT = 8,
 117         YACA_KEY_LENGTH_UNSAFE_40BIT = 40,
 118         YACA_KEY_LENGTH_UNSAFE_64BIT = 64,
 119         YACA_KEY_LENGTH_UNSAFE_80BIT = 80,
 120         YACA_KEY_LENGTH_UNSAFE_128BIT = 128,
 121         YACA_KEY_LENGTH_192BIT = 192,
 122         YACA_KEY_LENGTH_256BIT = 256,
 123         YACA_KEY_LENGTH_512BIT = 512,
 124         YACA_KEY_LENGTH_1024BIT = 1024,
 125         YACA_KEY_LENGTH_2048BIT = 2048,
 126         YACA_KEY_LENGTH_3072BIT = 3072,
 127         YACA_KEY_LENGTH_4096BIT = 4096
 128 } yaca_key_bit_length_e;
 129
 130 /**
 131  * @brief Enumeration of YACA message digest algorithms.
 132  *
 133  * @since_tizen 3.0
 134  */
 135 typedef enum {
 136         /** Message digest algorithm MD5 */
 137         YACA_DIGEST_MD5,
 138         /** Message digest algorithm SHA1 */
 139         YACA_DIGEST_SHA1,
 140         /** Message digest algorithm SHA2, 224bit */
 141         YACA_DIGEST_SHA224,
 142         /** Message digest algorithm SHA2, 256bit */
 143         YACA_DIGEST_SHA256,
 144         /** Message digest algorithm SHA2, 384bit */
 145         YACA_DIGEST_SHA384,
 146         /** Message digest algorithm SHA2, 512bit */
 147         YACA_DIGEST_SHA512,
 148 } yaca_digest_algorithm_e;
 149
 150 /**
 151  * @brief Enumeration of YACA symmetric encryption algorithms.
 152  *
 153  * @since_tizen 3.0
 154  */
 155 typedef enum {
 156         /**
 157          * AES encryption.
 158          * - Supported key lengths: @c 128, @c 192 and @c 256.
 159          * - Supported block cipher modes:
 160          * #YACA_BCM_CBC,
 161          * #YACA_BCM_OFB,
 162          * #YACA_BCM_CFB,
 163          * #YACA_BCM_CFB1,
 164          * #YACA_BCM_CFB8,
 165          * #YACA_BCM_ECB,
 166          * #YACA_BCM_GCM,
 167          * #YACA_BCM_CCM,
 168          * #YACA_BCM_CTR
 169          * - see #yaca_block_cipher_mode_e for details on additional properties (mandatory).
 170          */
 171         YACA_ENCRYPT_AES = 0,
 172
 173         /**
 174          * DES encryption.
 175          * - Supported key lengths: @c 64.
 176          * - Supported block cipher modes:
 177          * #YACA_BCM_CBC,
 178          * #YACA_BCM_OFB,
 179          * #YACA_BCM_CFB,
 180          * #YACA_BCM_CFB1,
 181          * #YACA_BCM_CFB8,
 182          * #YACA_BCM_ECB
 183          * - see #yaca_block_cipher_mode_e for details on additional properties (mandatory).
 184          */
 185         YACA_ENCRYPT_UNSAFE_DES,
 186
 187         /**
 188          * 3DES 2-key encryption.
 189          * - Supported key lengths: @c 128.
 190          * - Supported block cipher modes:
 191          * #YACA_BCM_CBC,
 192          * #YACA_BCM_OFB,
 193          * #YACA_BCM_CFB,
 194          * #YACA_BCM_ECB
 195          * - see #yaca_block_cipher_mode_e for details on additional properties (mandatory).
 196          * - Use double DES keys to perform corresponding 2-key 3DES encryption.
 197
 198          */
 199         YACA_ENCRYPT_UNSAFE_3DES_2TDEA,
 200
 201         /**
 202          * 3DES 3-key encryption.
 203          * - Supported key lengths: @c 192.
 204          * - Supported block cipher modes:
 205          * #YACA_BCM_CBC,
 206          * #YACA_BCM_OFB,
 207          * #YACA_BCM_CFB,
 208          * #YACA_BCM_CFB1,
 209          * #YACA_BCM_CFB8,
 210          * #YACA_BCM_ECB
 211          * - see #yaca_block_cipher_mode_e for details on additional properties (mandatory).
 212          * - Use triple DES keys to perform corresponding 3-key 3DES encryption.
 213          */
 214         YACA_ENCRYPT_3DES_3TDEA,
 215
 216         /**
 217          * RC2 encryption.
 218          * This is a variable key length cipher.
 219          * - Supported key lengths: 8-1024 bits in steps of 8 bits.
 220          * - Effective key bits property by default equals to 128.
 221          * - Supported block cipher modes:
 222          * #YACA_BCM_CBC,
 223          * #YACA_BCM_OFB,
 224          * #YACA_BCM_CFB,
 225          * #YACA_BCM_ECB
 226          */
 227         YACA_ENCRYPT_UNSAFE_RC2,
 228
 229         /**
 230          * RC4 encryption.
 231          * This is a variable key length cipher.
 232          * - Supported key lengths: 40–2048 bits in steps of 8 bits.
 233          * This cipher doesn't support block cipher modes, use #YACA_BCM_NONE instead.
 234          */
 235         YACA_ENCRYPT_UNSAFE_RC4,
 236
 237         /**
 238          * CAST5 encryption.
 239          * This is a variable key length cipher.
 240          * Supported key lengths: 40-128 bits in steps of 8 bits.
 241          * - Supported block cipher modes:
 242          * #YACA_BCM_CBC,
 243          * #YACA_BCM_OFB,
 244          * #YACA_BCM_CFB,
 245          * #YACA_BCM_ECB
 246          * - see #yaca_block_cipher_mode_e for details on additional properties (mandatory).
 247          */
 248         YACA_ENCRYPT_CAST5,
 249 } yaca_encrypt_algorithm_e;
 250
 251 /**
 252  * @brief Enumeration of YACA chaining modes for block ciphers.
 253  *
 254  * @since_tizen 3.0
 255  */
 256 typedef enum {
 257         /**
 258          * Used when algorithm doesn't support block ciphers modes.
 259          */
 260         YACA_BCM_NONE,
 261
 262         /**
 263          * ECB block cipher mode.
 264          * Encrypts 64 bit at a time. No IV is used.
 265          */
 266         YACA_BCM_ECB,
 267
 268         /**
 269          * CTR block cipher mode.
 270          * 16-byte initialization vector is mandatory.
 271          */
 272         YACA_BCM_CTR,
 273
 274         /**
 275          * CBC block cipher mode.
 276          * 16-byte initialization vector is mandatory.
 277          */
 278         YACA_BCM_CBC,
 279
 280         /**
 281          * GCM block cipher mode.
 282          * This is a variable IV length mode (recommended 96 bits IV).
 283          *
 284          * Supported properties:
 285          * - #YACA_PROPERTY_GCM_TAG_LEN = GCM tag length\n
 286          *   Supported tag lengths: @c 32, @c 64, @c 96, @c 104, @c 112, @c 120, @c 128,
 287          *   (recommended 128 bits tag).\n
 288          *   Set after yaca_encrypt_finalize() / yaca_seal_finalize() and before
 289          *   yaca_context_get_property(#YACA_PROPERTY_GCM_TAG)
 290          *   in encryption / seal operation.\n\n
 291          *
 292          * - #YACA_PROPERTY_GCM_TAG = GCM tag\n
 293          *   Get after yaca_encrypt_finalize() / yaca_seal_finalize() in encryption / seal operation.\n
 294          *   Set before yaca_decrypt_finalize() / yaca_open_finalize() in decryption / open operation.\n\n
 295          *
 296          * - #YACA_PROPERTY_GCM_AAD = additional authentication data (optional)\n
 297          *   Set after yaca_encrypt_initialize() / yaca_seal_initialize() and before
 298          *   yaca_encrypt_update() / yaca_seal_update() in encryption / seal operation.\n
 299          *   Set after yaca_decrypt_initialize() / yaca_open_initialize() and before
 300          *   yaca_decrypt_update() / yaca_open_update() in decryption / open operation.\n\n
 301          *
 302          *   @see examples/encrypt_aes_gcm_ccm.c
 303          *   @see examples/seal.c
 304          */
 305         YACA_BCM_GCM,
 306
 307         /**
 308          * Default CFB block cipher mode.
 309          * 16-byte initialization vector is mandatory.
 310          */
 311         YACA_BCM_CFB,
 312
 313         /**
 314          * 1 bit CFB block cipher mode.
 315          * 16-byte initialization vector is mandatory.
 316          */
 317         YACA_BCM_CFB1,
 318
 319         /**
 320          * 8 bits CFB block cipher mode.
 321          * 16-byte initialization vector is mandatory.
 322          */
 323         YACA_BCM_CFB8,
 324
 325         /**
 326          * OFB block cipher mode.
 327          * 16-byte initialization vector is mandatory.
 328          */
 329         YACA_BCM_OFB,
 330
 331         /**
 332          * CBC-MAC Mode (AES).
 333          * This is a variable IV length mode.\n
 334          * Supported IV lengths: 56-104 bits in steps of 8 bits (recommended 56 bits IV).\n\n
 335          *
 336          * Supported properties:
 337          * - #YACA_PROPERTY_CCM_TAG_LEN = CCM tag length\n
 338          *   Supported tag lengths: 32-128 bits in step of 16 bits (recommended 96 bits tag).\n
 339          *   Set after yaca_encrypt_initialize() / yaca_seal_initialize() and before
 340          *   yaca_encrypt_update() / yaca_seal_update() in encryption / seal operation.\n\n
 341          *
 342          * - #YACA_PROPERTY_CCM_TAG = CCM tag\n
 343          *   Get after yaca_encrypt_finalize() / yaca_seal_finalize() in encryption / seal operation.\n
 344          *   Set after yaca_decrypt_initialize() / yaca_open_initialize() and before
 345          *   yaca_decrypt_update() / yaca_open_update() in decryption / open operation.\n\n
 346          *
 347          * - #YACA_PROPERTY_CCM_AAD = additional authentication data (optional)\n
 348          *   The total plaintext length must be passed to yaca_encrypt_update() / yaca_seal_update()
 349          *   if AAD is used.\n
 350          *   Set after yaca_encrypt_initialize() / yaca_seal_initialize() and before
 351          *   yaca_encrypt_update() / yaca_seal_update() in encryption / seal operation.\n
 352          *   You can only call yaca_encrypt_update() / yaca_seal_update() once for AAD
 353          *   and once for the plaintext.\n\n
 354          *
 355          *   The total encrypted text length must be passed to yaca_decrypt_update() /
 356          *   yaca_open_update() if AAD is used.\n
 357          *   Set after yaca_decrypt_initialize() / yaca_open_initialize() and before
 358          *   yaca_decrypt_update() / yaca_open_update() in decryption / open operation.\n\n
 359          *
 360          *   @see examples/encrypt_aes_gcm_ccm.c
 361          *   @see examples/seal.c
 362          */
 363         YACA_BCM_CCM
 364
 365 } yaca_block_cipher_mode_e;
 366
 367
 368 /**
 369  * @brief Enumeration of YACA non-standard properties for algorithms.
 370  *
 371  * @since_tizen 3.0
 372  */
 373 typedef enum {
 374         /** Padding */
 375         YACA_PROPERTY_PADDING,
 376
 377         /** GCM Additional Authentication Data */
 378         YACA_PROPERTY_GCM_AAD,
 379         /** GCM Tag bits */
 380         YACA_PROPERTY_GCM_TAG,
 381         /** GCM Tag length */
 382         YACA_PROPERTY_GCM_TAG_LEN,
 383
 384         /** CCM Additional Authentication Data */
 385         YACA_PROPERTY_CCM_AAD,
 386         /** CCM Tag bits */
 387         YACA_PROPERTY_CCM_TAG,
 388         /** CCM Tag length */
 389         YACA_PROPERTY_CCM_TAG_LEN
 390 } yaca_property_e;
 391
 392 /**
 393  * @brief Enumeration of YACA paddings.
 394  *
 395  * @since_tizen 3.0
 396  */
 397 typedef enum {
 398         /** The total number of data bytes MUST be a multiple of block size */
 399         YACA_PADDING_NONE = 0,
 400         /** RSA X9.31 padding */
 401         YACA_PADDING_X931,
 402         /** RSA signature/verify operations */
 403         YACA_PADDING_PKCS1,
 404         /** RSA signature/verify operations */
 405         YACA_PADDING_PKCS1_PSS,
 406 } yaca_padding_e;
 407
 408 /**@}*/
 409
 410 #ifdef __cplusplus
 411 } /* extern */
 412 #endif
 413
 414 #endif /* YACA_TYPES_H */