1128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden/* --------------------------------------------------------------------------- 2128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 3128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * AEAD API 0.12 - 23-MAY-2012 4128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 5128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * This file gives an interface appropriate for many authenticated 6128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * encryption with associated data (AEAD) implementations. It does not try 7128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * to accommodate all possible options or limitations that an implementation 8128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * might have -- you should consult the documentation of your chosen 9128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * implementation to find things like RFC 5116 constants, alignment 10128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * requirements, whether the incremental interface is supported, etc. 11128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 12128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * This file is in the public domain. It is provided "as is", without 13128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * warranty of any kind. Use at your own risk. 14128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 15128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * Comments are welcome: Ted Krovetz <ted@krovetz>. 16128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 17128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * ------------------------------------------------------------------------ */ 18128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden 19128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden#ifndef _AE_H_ 20128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden#define _AE_H_ 21128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden 22128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden#ifdef __cplusplus 23128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willdenextern "C" { 24128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden#endif 25128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden 26128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden/* -------------------------------------------------------------------------- 27128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 28128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * Constants 29128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 30128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * ----------------------------------------------------------------------- */ 31128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden 32128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden/* Return status codes: Negative return values indicate an error occurred. 33128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * For full explanations of error values, consult the implementation's 34128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * documentation. */ 35128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden#define AE_SUCCESS (0) /* Indicates successful completion of call */ 36128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden#define AE_INVALID (-1) /* Indicates bad tag during decryption */ 37128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden#define AE_NOT_SUPPORTED (-2) /* Indicates unsupported option requested */ 38128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden 39128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden/* Flags: When data can be processed "incrementally", these flags are used 40128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * to indicate whether the submitted data is the last or not. */ 41128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden#define AE_FINALIZE (1) /* This is the last of data */ 42128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden#define AE_PENDING (0) /* More data of is coming */ 43128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden 44128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden/* -------------------------------------------------------------------------- 45128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 46128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * AEAD opaque structure definition 47128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 48128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * ----------------------------------------------------------------------- */ 49128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden 50128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willdentypedef struct _ae_ctx ae_ctx; 51128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden 52128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden/* -------------------------------------------------------------------------- 53128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 54128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * Data Structure Routines 55128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 56128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * ----------------------------------------------------------------------- */ 57128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden 58128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willdenae_ctx* ae_allocate(void* misc); /* Allocate ae_ctx, set optional ptr */ 59128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willdenvoid ae_free(ae_ctx* ctx); /* Deallocate ae_ctx struct */ 60128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willdenint ae_clear(ae_ctx* ctx); /* Undo initialization */ 61128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willdenint ae_ctx_sizeof(void); /* Return sizeof(ae_ctx) */ 62128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden/* ae_allocate() allocates an ae_ctx structure, but does not initialize it. 63128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * ae_free() deallocates an ae_ctx structure, but does not zero it. 64128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * ae_clear() zeroes sensitive values associated with an ae_ctx structure 65128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * and deallocates any auxiliary structures allocated during ae_init(). 66128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * ae_ctx_sizeof() returns sizeof(ae_ctx), to aid in any static allocations. 67128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden */ 68128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden 69128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden/* -------------------------------------------------------------------------- 70128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 71128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * AEAD Routines 72128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 73128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * ----------------------------------------------------------------------- */ 74128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden 75128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willdenint ae_init(ae_ctx* ctx, const void* key, int key_len, int nonce_len, int tag_len); 76128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden/* -------------------------------------------------------------------------- 77128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 78128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * Initialize an ae_ctx context structure. 79128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 80128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * Parameters: 81128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * ctx - Pointer to an ae_ctx structure to be initialized 82128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * key - Pointer to user-supplied key 83128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * key_len - Length of key supplied, in bytes 84128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * nonce_len - Length of nonces to be used for this key, in bytes 85128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * tag_len - Length of tags to be produced for this key, in bytes 86128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 87128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * Returns: 88128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * AE_SUCCESS - Success. Ctx ready for use. 89128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * AE_NOT_SUPPORTED - An unsupported length was supplied. Ctx is untouched. 90128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * Otherwise - Error. Check implementation documentation for codes. 91128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 92128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * ----------------------------------------------------------------------- */ 93128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden 94128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willdenint ae_encrypt(ae_ctx* ctx, const void* nonce, const void* pt, int pt_len, const void* ad, 95128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden int ad_len, void* ct, void* tag, int final); 96128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden/* -------------------------------------------------------------------------- 97128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 98128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * Encrypt plaintext; provide for authentication of ciphertext/associated data. 99128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 100128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * Parameters: 101128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * ctx - Pointer to an ae_ctx structure initialized by ae_init. 102128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * nonce - Pointer to a nonce_len (defined in ae_init) byte nonce. 103128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * pt - Pointer to plaintext bytes to be encrypted. 104128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * pt_len - number of bytes pointed to by pt. 105128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * ad - Pointer to associated data. 106128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * ad_len - number of bytes pointed to by ad. 107128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * ct - Pointer to buffer to receive ciphertext encryption. 108128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * tag - Pointer to receive authentication tag; or NULL 109128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * if tag is to be bundled into the ciphertext. 110128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * final - Non-zero if this call completes the plaintext being encrypted. 111128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 112128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * If nonce!=NULL then a message is being initiated. If final!=0 113128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * then a message is being finalized. If final==0 or nonce==NULL 114128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * then the incremental interface is being used. If nonce!=NULL and 115128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * ad_len<0, then use same ad as last message. 116128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 117128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * Returns: 118128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * non-negative - Number of bytes written to ct. 119128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * AE_NOT_SUPPORTED - Usage mode unsupported (eg, incremental and/or sticky). 120128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * Otherwise - Error. Check implementation documentation for codes. 121128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 122128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * ----------------------------------------------------------------------- */ 123128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden 124128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willdenint ae_decrypt(ae_ctx* ctx, const void* nonce, const void* ct, int ct_len, const void* ad, 125128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden int ad_len, void* pt, const void* tag, int final); 126128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden/* -------------------------------------------------------------------------- 127128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 128128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * Decrypt ciphertext; provide authenticity of plaintext and associated data. 129128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 130128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * Parameters: 131128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * ctx - Pointer to an ae_ctx structure initialized by ae_init. 132128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * nonce - Pointer to a nonce_len (defined in ae_init) byte nonce. 133128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * ct - Pointer to ciphertext bytes to be decrypted. 134128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * ct_len - number of bytes pointed to by ct. 135128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * ad - Pointer to associated data. 136128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * ad_len - number of bytes pointed to by ad. 137128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * pt - Pointer to buffer to receive plaintext decryption. 138128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * tag - Pointer to tag_len (defined in ae_init) bytes; or NULL 139128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * if tag is bundled into the ciphertext. Non-NULL tag is only 140128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * read when final is non-zero. 141128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * final - Non-zero if this call completes the ciphertext being decrypted. 142128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 143128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * If nonce!=NULL then "ct" points to the start of a ciphertext. If final!=0 144128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * then "in" points to the final piece of ciphertext. If final==0 or nonce== 145128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * NULL then the incremental interface is being used. If nonce!=NULL and 146128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * ad_len<0, then use same ad as last message. 147128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 148128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * Returns: 149128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * non-negative - Number of bytes written to pt. 150128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * AE_INVALID - Authentication failure. 151128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * AE_NOT_SUPPORTED - Usage mode unsupported (eg, incremental and/or sticky). 152128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * Otherwise - Error. Check implementation documentation for codes. 153128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 154128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * NOTE !!! NOTE !!! -- The ciphertext should be assumed possibly inauthentic 155128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * until it has been completely written and it is 156128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * verified that this routine did not return AE_INVALID. 157128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * 158128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden * ----------------------------------------------------------------------- */ 159128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden 160128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden#ifdef __cplusplus 161128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden} /* closing brace for extern "C" */ 162128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden#endif 163128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden 164128ffe07c723d8ffe2d5ea528ba5f64436c8a55aShawn Willden#endif /* _AE_H_ */ 165