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