/* Copyright (c) 2008 Nordic Semiconductor. All Rights Reserved.
 *
 * The information contained herein is confidential property of Nordic 
 * Semiconductor. The use, copying, transfer or disclosure of such information 
 * is prohibited except by express written agreement with Nordic Semiconductor.
 */

/** @file lib_crypt.h
 * @defgroup nordic_lib_crypt AES encryption
 * @{
 * @ingroup nordic_lib
 *
 * @brief Example implemenation for encryption/decryption data. 
 * 
 * The encryption is based on AES counter mode (CTR) where a 128 bit hybrid counter 
 * is used for encryption/decryption. The counter is split in two, 11 bytes as MS11B 
 * and 5 bytes as LS5B. The LS5B part is not secret and tells the receiver how 
 * to decrypt an encrypted message. 
 * 
 * The library is customized for low report rate data communication, such as 
 * a keyboard or remote control. When using this library, the 5 byte part (LS5B) of the
 * counter should be transmitted in plain text along with the encrypted data. 
 * On the receive side the encrypted data should simply be decrypted using the received 
 * plain text LS5B counter (in addition to the secret chipher key). This concept will 
 * eliminate any issue related to the counters on the receiver and transmitter becoming 
 * unsynchronized, and still maintain the data pattern supression properties of
 * the CTR AES mode. As long as a relatively low packet rate is maintained, the added 
 * data overhead due to the 5 byte counter will in any case be ignorable.
 *
 * Note that the security of the link will not be reduced as a consequence of sending 
 * the counter value in plain text as long as the following criteria are met:
 *
 * - Cipher key used for encryption/decryption must be kept secret.
 * - The plain text counter (LS5B) must be modified for each transfer.
 *
 * @image html Encryption_Figs.png
 *
 * The library can be used on both nRF24LU1 and nRF24LE1 devices. 
 * 
 * @author Ivar Conradi Oesthus
 */
#ifndef LIB_CRYPT_H__
#define LIB_CRYPT_H__

#include <stdint.h>

/**
* Initialise the encryption/decryption library. This function will set up the 
* underlying AES encryption module with correct mode and set the encryption key.
*
* @param key sets the encryption/decryption key	(16 Bytes)
* @param init_counter sets the encryption counter     (16 Bytes)
*/
void lib_crypt_init(uint8_t * key, uint8_t * init_counter);

/**
* This function is used to set a new counter value.
* 
* @remark The counter should be changed before lib_crypt(..) function has been 
* called: 2^40 = 1'099'511'627'776 times.
* 
* @param counter The 16 byte counter to use.
*/
void lib_crypt_set_counter(uint8_t * counter);

/**
* This function is used to encrypt or decrypt data. It is possible to encrypt 
* or decrypt data-blocks up to 16 bytes. If more data needs to be encrypted or 
* decrypted this function needs to be used multiple times.
*
* @remark This function can only encrypt up to 16 bytes.
* 
* [Encryption]
* Each encryption needs to be encrypted with an unique LS5B value. A new value 
* can be generated by using the lib_crypt_generate_ls5b() function. 
* 
* @sa lib_crypt_generate_ls5b();
*
* [Decryption]
* To decrypt it is required to specify the LS5B value which where used to encrypt 
* the data. This value should be provided together with the encrypted data. 
*
* [Param]
* @param src_buf    Where to find data to encrypt/decrypt
* @param dest_buf   Where to put the encrypted/decrypted result
* @param length     The length of the data to be encrypted (max 16 Bytes)
* @param ls5b_value The the least significant 5 bytes of the counter used
*                   for encryption or decryption.
*/
void lib_crypt(uint8_t * dest_buf, uint8_t * src_buf, uint8_t length, uint8_t * ls5b_value);

/**
* This function is used to generate a new LS5B value (5 bytes) used to encrypt
* data. This function should be called before using lib_crypt() to encrypt data. 
*
* @sa lib_crypt(); 
* 
* @param dest_buf where to put the new ls5b-value (5 bytes). 
*/
void lib_crypt_generate_ls5b(uint8_t * dest_buf);	 

#endif  // LIB_CRYPT_H__