1 #ifndef DCRYPT_H 2 #define DCRYPT_H 1 3 #include "array.h" 4 5 struct dcrypt_context_symmetric; 6 struct dcrypt_context_hmac; 7 struct dcrypt_public_key; 8 struct dcrypt_private_key; 9 10 struct dcrypt_keypair { 11 struct dcrypt_public_key *pub; 12 struct dcrypt_private_key *priv; 13 }; 14 15 enum dcrypt_sym_mode { 16 DCRYPT_MODE_ENCRYPT, 17 DCRYPT_MODE_DECRYPT 18 }; 19 20 enum dcrypt_key_type { 21 DCRYPT_KEY_RSA = 0x1, 22 DCRYPT_KEY_EC = 0x2 23 }; 24 25 /** 26 * dovecot key format: 27 * version version-specific data 28 * v1: version tab nid tab raw ec private key (in hex) 29 * v2: version colon algorithm oid colon private-or-public-key-only (in hex) 30 */ 31 enum dcrypt_key_format { 32 DCRYPT_FORMAT_PEM, 33 DCRYPT_FORMAT_DOVECOT, 34 DCRYPT_FORMAT_JWK, /* JSON Web Key (JWK) [RFC7517] */ 35 }; 36 37 enum dcrypt_key_encryption_type { 38 DCRYPT_KEY_ENCRYPTION_TYPE_NONE, 39 DCRYPT_KEY_ENCRYPTION_TYPE_KEY, 40 DCRYPT_KEY_ENCRYPTION_TYPE_PASSWORD 41 }; 42 43 enum dcrypt_key_version { 44 DCRYPT_KEY_VERSION_1, 45 DCRYPT_KEY_VERSION_2, 46 DCRYPT_KEY_VERSION_NA /* not applicable, PEM key */ 47 }; 48 49 enum dcrypt_key_kind { 50 DCRYPT_KEY_KIND_PUBLIC, 51 DCRYPT_KEY_KIND_PRIVATE 52 }; 53 54 enum dcrypt_key_usage { 55 DCRYPT_KEY_USAGE_NONE, 56 DCRYPT_KEY_USAGE_ENCRYPT, 57 DCRYPT_KEY_USAGE_SIGN, 58 }; 59 60 enum dcrypt_signature_format { 61 DCRYPT_SIGNATURE_FORMAT_DSS, 62 DCRYPT_SIGNATURE_FORMAT_X962, 63 }; 64 65 /* this parameter makes sense with RSA only 66 default for RSA means either PSS (sign/verify) 67 or OAEP (encrypt/decrypt). 68 for ECDSA default can be used. 69 */ 70 enum dcrypt_padding { 71 DCRYPT_PADDING_DEFAULT, 72 DCRYPT_PADDING_RSA_PKCS1_PSS, 73 DCRYPT_PADDING_RSA_PKCS1_OAEP, 74 DCRYPT_PADDING_RSA_PKCS1, /* for compatibility use only */ 75 DCRYPT_PADDING_RSA_NO, 76 }; 77 78 struct dcrypt_settings { 79 /* OpenSSL engine to use */ 80 const char *crypto_device; 81 /* Look for backends in this directory */ 82 const char *module_dir; 83 }; 84 85 struct dcrypt_raw_key { 86 const void *parameter; 87 size_t len; 88 }; 89 90 ARRAY_DEFINE_TYPE(dcrypt_raw_key, struct dcrypt_raw_key); 91 92 /** 93 * load and initialize dcrypt backend, use either openssl or gnutls 94 */ 95 bool dcrypt_initialize(const char *backend, const struct dcrypt_settings *set, 96 const char **error_r); 97 98 /** 99 * Returns TRUE if dcrypt has been initialized. 100 */ 101 bool dcrypt_is_initialized(void); 102 103 /** 104 * deinitialize dcrypt. 105 * 106 * NOTE: Do not call this function if you are going to use dcrypt later on. 107 * Deinitializing the library using this will not allow it to be reinitialized 108 * when using OpenSSL. 109 */ 110 void dcrypt_deinitialize(void); 111 112 /** 113 * create symmetric context 114 */ 115 bool dcrypt_ctx_sym_create(const char *algorithm, enum dcrypt_sym_mode mode, 116 struct dcrypt_context_symmetric **ctx_r, 117 const char **error_r); 118 119 /** 120 * destroy symmetric context and free memory 121 */ 122 void dcrypt_ctx_sym_destroy(struct dcrypt_context_symmetric **ctx); 123 124 /** 125 * key and IV manipulation functions 126 */ 127 void dcrypt_ctx_sym_set_key(struct dcrypt_context_symmetric *ctx, 128 const unsigned char *key, size_t key_len); 129 void dcrypt_ctx_sym_set_iv(struct dcrypt_context_symmetric *ctx, 130 const unsigned char *iv, size_t iv_len); 131 void dcrypt_ctx_sym_set_key_iv_random(struct dcrypt_context_symmetric *ctx); 132 bool dcrypt_ctx_sym_get_key(struct dcrypt_context_symmetric *ctx, buffer_t *key); 133 bool dcrypt_ctx_sym_get_iv(struct dcrypt_context_symmetric *ctx, buffer_t *iv); 134 135 /** 136 * turn padding on/off (default: on) 137 */ 138 void dcrypt_ctx_sym_set_padding(struct dcrypt_context_symmetric *ctx, 139 bool padding); 140 141 /** 142 * authentication data manipulation (use with GCM only) 143 */ 144 void dcrypt_ctx_sym_set_aad(struct dcrypt_context_symmetric *ctx, 145 const unsigned char *aad, size_t aad_len); 146 bool dcrypt_ctx_sym_get_aad(struct dcrypt_context_symmetric *ctx, 147 buffer_t *aad); 148 /** 149 * result tag from aead (use with GCM only) 150 */ 151 void dcrypt_ctx_sym_set_tag(struct dcrypt_context_symmetric *ctx, 152 const unsigned char *tag, size_t tag_len); 153 bool dcrypt_ctx_sym_get_tag(struct dcrypt_context_symmetric *ctx, 154 buffer_t *tag); 155 156 /* get various lengths */ 157 unsigned int dcrypt_ctx_sym_get_key_length(struct dcrypt_context_symmetric *ctx); 158 unsigned int dcrypt_ctx_sym_get_iv_length(struct dcrypt_context_symmetric *ctx); 159 unsigned int dcrypt_ctx_sym_get_block_size(struct dcrypt_context_symmetric *ctx); 160 161 /** 162 * initialize crypto 163 */ 164 bool dcrypt_ctx_sym_init(struct dcrypt_context_symmetric *ctx, 165 const char **error_r); 166 167 /** 168 * update with data 169 */ 170 bool dcrypt_ctx_sym_update(struct dcrypt_context_symmetric *ctx, 171 const unsigned char *data, size_t data_len, 172 buffer_t *result, const char **error_r); 173 174 /** 175 * perform final step (may or may not emit data) 176 */ 177 bool dcrypt_ctx_sym_final(struct dcrypt_context_symmetric *ctx, 178 buffer_t *result, const char **error_r); 179 180 /** 181 * create HMAC context, algorithm is digest algorithm 182 */ 183 bool dcrypt_ctx_hmac_create(const char *algorithm, 184 struct dcrypt_context_hmac **ctx_r, 185 const char **error_r); 186 /** 187 * destroy HMAC context and free memory 188 */ 189 void dcrypt_ctx_hmac_destroy(struct dcrypt_context_hmac **ctx); 190 191 /** 192 * hmac key manipulation 193 */ 194 void dcrypt_ctx_hmac_set_key(struct dcrypt_context_hmac *ctx, 195 const unsigned char *key, size_t key_len); 196 bool dcrypt_ctx_hmac_get_key(struct dcrypt_context_hmac *ctx, buffer_t *key); 197 void dcrypt_ctx_hmac_set_key_random(struct dcrypt_context_hmac *ctx); 198 199 /** 200 * get digest length for HMAC 201 */ 202 unsigned int dcrypt_ctx_hmac_get_digest_length(struct dcrypt_context_hmac *ctx); 203 204 /** 205 * initialize hmac 206 */ 207 bool dcrypt_ctx_hmac_init(struct dcrypt_context_hmac *ctx, 208 const char **error_r); 209 210 /** 211 * update hmac context with data 212 */ 213 bool dcrypt_ctx_hmac_update(struct dcrypt_context_hmac *ctx, 214 const unsigned char *data, size_t data_len, 215 const char **error_r); 216 217 /** 218 * perform final rounds and retrieve result 219 */ 220 bool dcrypt_ctx_hmac_final(struct dcrypt_context_hmac *ctx, buffer_t *result, 221 const char **error_r); 222 223 /** 224 * Elliptic Curve based Diffie-Heffman shared secret derivation */ 225 bool dcrypt_ecdh_derive_secret(struct dcrypt_private_key *priv_key, 226 struct dcrypt_public_key *pub_key, 227 buffer_t *shared_secret, 228 const char **error_r); 229 /** 230 * Helpers for DCRYPT file format */ 231 bool dcrypt_ecdh_derive_secret_local(struct dcrypt_private_key *local_key, 232 buffer_t *R, buffer_t *S, 233 const char **error_r); 234 bool dcrypt_ecdh_derive_secret_peer(struct dcrypt_public_key *peer_key, 235 buffer_t *R, buffer_t *S, 236 const char **error_r); 237 238 /** Signature functions 239 algorithm is name of digest algorithm to use, such as SHA256. 240 241 both RSA and EC keys are supported. 242 */ 243 244 /* returns false on error, true on success */ 245 bool dcrypt_sign(struct dcrypt_private_key *key, const char *algorithm, 246 enum dcrypt_signature_format format, 247 const void *data, size_t data_len, buffer_t *signature_r, 248 enum dcrypt_padding padding, const char **error_r); 249 250 /* check valid_r for signature validity 251 false return means it wasn't able to verify it for other reasons */ 252 bool dcrypt_verify(struct dcrypt_public_key *key, const char *algorithm, 253 enum dcrypt_signature_format format, 254 const void *data, size_t data_len, 255 const unsigned char *signature, size_t signature_len, 256 bool *valid_r, enum dcrypt_padding padding, 257 const char **error_r); 258 259 /** 260 * generate cryptographic data from password and salt. Use 1000-10000 for rounds. 261 */ 262 bool dcrypt_pbkdf2(const unsigned char *password, size_t password_len, 263 const unsigned char *salt, size_t salt_len, 264 const char *hash, unsigned int rounds, 265 buffer_t *result, unsigned int result_len, 266 const char **error_r); 267 268 bool dcrypt_keypair_generate(struct dcrypt_keypair *pair_r, 269 enum dcrypt_key_type kind, unsigned int bits, 270 const char *curve, const char **error_r); 271 272 /** 273 * load loads key structure from external format. 274 * store stores key structure into external format. 275 * 276 * you can provide either PASSWORD or ENC_KEY, not both. 277 */ 278 bool dcrypt_key_load_private(struct dcrypt_private_key **key_r, 279 const char *data, const char *password, 280 struct dcrypt_private_key *dec_key, 281 const char **error_r); 282 283 bool dcrypt_key_load_public(struct dcrypt_public_key **key_r, 284 const char *data, const char **error_r); 285 286 /** 287 * When encrypting with public key, the cipher parameter here must begin with 288 * ecdh-, for example ecdh-aes-256-ctr. An example of a valid cipher for 289 * encrypting with password would be aes-256-ctr. 290 */ 291 bool dcrypt_key_store_private(struct dcrypt_private_key *key, 292 enum dcrypt_key_format format, const char *cipher, 293 buffer_t *destination, const char *password, 294 struct dcrypt_public_key *enc_key, 295 const char **error_r); 296 297 bool dcrypt_key_store_public(struct dcrypt_public_key *key, 298 enum dcrypt_key_format format, 299 buffer_t *destination, const char **error_r); 300 301 void dcrypt_key_convert_private_to_public(struct dcrypt_private_key *priv_key, 302 struct dcrypt_public_key **pub_key_r); 303 304 void dcrypt_keypair_unref(struct dcrypt_keypair *keypair); 305 void dcrypt_key_ref_public(struct dcrypt_public_key *key); 306 void dcrypt_key_ref_private(struct dcrypt_private_key *key); 307 void dcrypt_key_unref_public(struct dcrypt_public_key **key); 308 void dcrypt_key_unref_private(struct dcrypt_private_key **key); 309 310 enum dcrypt_key_type dcrypt_key_type_private(struct dcrypt_private_key *key); 311 enum dcrypt_key_type dcrypt_key_type_public(struct dcrypt_public_key *key); 312 /* return digest of key */ 313 bool dcrypt_key_id_public(struct dcrypt_public_key *key, const char *algorithm, 314 buffer_t *result, const char **error_r); 315 /* return SHA1 sum of key */ 316 bool dcrypt_key_id_public_old(struct dcrypt_public_key *key, buffer_t *result, 317 const char **error_r); 318 /* return digest of key */ 319 bool dcrypt_key_id_private(struct dcrypt_private_key *key, 320 const char *algorithm, buffer_t *result, 321 const char **error_r); 322 /* return SHA1 sum of key */ 323 bool dcrypt_key_id_private_old(struct dcrypt_private_key *key, 324 buffer_t *result, const char **error_r); 325 326 /* return raw private key: 327 Only ECC supported currently 328 329 returns OID bytes and private key in bigendian bytes 330 */ 331 bool dcrypt_key_store_private_raw(struct dcrypt_private_key *key, 332 pool_t pool, 333 enum dcrypt_key_type *key_type_r, 334 ARRAY_TYPE(dcrypt_raw_key) *keys_r, 335 const char **error_r); 336 337 /* return raw public key 338 Only ECC supported currently 339 340 returns OID bytes and public key in compressed form (z||x) 341 */ 342 bool dcrypt_key_store_public_raw(struct dcrypt_public_key *key, 343 pool_t pool, 344 enum dcrypt_key_type *key_type_r, 345 ARRAY_TYPE(dcrypt_raw_key) *keys_r, 346 const char **error_r); 347 348 /* load raw private key: 349 Only ECC supported currently 350 351 expects OID bytes and private key in bigendian bytes 352 */ 353 bool dcrypt_key_load_private_raw(struct dcrypt_private_key **key_r, 354 enum dcrypt_key_type key_type, 355 const ARRAY_TYPE(dcrypt_raw_key) *keys, 356 const char **error_r); 357 358 /* load raw public key 359 Only ECC supported currently 360 361 expects OID bytes and public key bytes. 362 */ 363 bool dcrypt_key_load_public_raw(struct dcrypt_public_key **key_r, 364 enum dcrypt_key_type key_type, 365 const ARRAY_TYPE(dcrypt_raw_key) *keys, 366 const char **error_r); 367 368 /* for ECC only - return textual name or OID of used curve */ 369 bool dcrypt_key_get_curve_public(struct dcrypt_public_key *key, 370 const char **curve_r, const char **error_r); 371 372 bool dcrypt_key_string_get_info(const char *key_data, 373 enum dcrypt_key_format *format_r, 374 enum dcrypt_key_version *version_r, 375 enum dcrypt_key_kind *kind_r, 376 enum dcrypt_key_encryption_type *encryption_type_r, 377 const char **encryption_key_hash_r, 378 const char **key_hash_r, const char **error_r); 379 380 /* Get/Set key identifier, this is optional opaque string identifying the key. */ 381 const char *dcrypt_key_get_id_public(struct dcrypt_public_key *key); 382 const char *dcrypt_key_get_id_private(struct dcrypt_private_key *key); 383 void dcrypt_key_set_id_public(struct dcrypt_public_key *key, const char *id); 384 void dcrypt_key_set_id_private(struct dcrypt_private_key *key, const char *id); 385 386 /* Get/Set key usage, optional. Defaults to NONE */ 387 enum dcrypt_key_usage dcrypt_key_get_usage_public(struct dcrypt_public_key *key); 388 enum dcrypt_key_usage dcrypt_key_get_usage_private(struct dcrypt_private_key *key); 389 void dcrypt_key_set_usage_public(struct dcrypt_public_key *key, 390 enum dcrypt_key_usage usage); 391 void dcrypt_key_set_usage_private(struct dcrypt_private_key *key, 392 enum dcrypt_key_usage usage); 393 394 /* RSA stuff */ 395 bool dcrypt_rsa_encrypt(struct dcrypt_public_key *key, 396 const unsigned char *data, size_t data_len, 397 buffer_t *result, enum dcrypt_padding padding, 398 const char **error_r); 399 bool dcrypt_rsa_decrypt(struct dcrypt_private_key *key, 400 const unsigned char *data, size_t data_len, 401 buffer_t *result, enum dcrypt_padding padding, 402 const char **error_r); 403 404 /* OID stuff */ 405 const char *dcrypt_oid2name(const unsigned char *oid, size_t oid_len, 406 const char **error_r); 407 bool dcrypt_name2oid(const char *name, buffer_t *oid, const char **error_r); 408 409 #endif 410