NanoScale R T O S. NanoCrypto User and Reference Guide. For all distributions

Transcription

1 NanoScale R T O S NanoCrypto User and Reference Guide For all distributions Version October 29, 2016

2 Disclaimer Specifications written in this document are believed to be accurate, but are not guaranteed to be entirely free of error. The information in this manual is subject to change for functional or performance improvements without notice. Please make sure your manual is the latest edition. While the information herein is assumed to be accurate, GenId SPRL (the manufacturer) assumes no responsibility for any errors or omissions. The manufacturer makes no representations or warranties, express, implied, statutory or in any communication with you. The manufacturer specifically disclaims any implied warranty of merchantability or fitness for a particular purpose. In no event shall the manufacturer, its employees, its contractors, or the authors of this document be liable for special, direct, indirect, or consequential damage, losses, costs, charges, claims, demands, claim for lost profits, fees, or expenses of any nature or kind. Copyright notice You may not extract portions of this manual or modify the PDF file in any way without the prior written permission of the manufacturer. The software described in this document is furnished under a license and may only be used or copied in accordance with the terms of such a license GenId SPRL Trademarks Names mentioned in this manual may be trademarks of their respective companies. Brand and product names are trademarks or registered trademarks of their respective holders. GenId SPRL Rue Florent Laurent 37C 7080 La Bouverie Belgium Tel. +32 (0) GenId SPRL 2

3 About this document Assumptions This document assumes that you already have a solid knowledge of the following: The software tools used for building your application (assembler, linker, C compiler); The target processor; The C programming language. If you feel that your knowledge of C is not sufficient, we recommend The C Programming Language by Kernighan and Richie (ISBN ), which describes the standard in C-programming and, in newer editions, also covers the ANSI C standard. How to use this manual The aim of this manual is to be a complete reference guide to the NanoCrypto library. This library relies completely on the NanoScale RTOS. As a result this manual is processor agnostic and is valid whatever the distribution GenId SPRL 3

4 Contents Acronyms 5 1 Introduction Installation Directory Structure Restrictions of the Demo version Cryptographic Hash Functions Introduction Algorithms presentation MD SHA SHA SHA Module description Example API Hash_CreateUnit Hash_CloseUnit Hash_GetOid Hash_GetDigestSize Hash_Begin Hash_Update Hash_Finalize Symmetric-Key Algorithms Introduction Algorithms presentation AES DES Triple DES IDEA RC Serpent Encryption modes ECB GenId SPRL 4

5 CONTENTS CBC CFB OFB CTR Module description Example API Crypto_CreateUnit Crypto_CloseUnit Crypto_GetBlockSize Crypto_SetKey Crypto_Encrypt Crypto_Decrypt Crypto_EncryptCBC Crypto_DecryptCBC Crypto_EncryptCFB Crypto_DecryptCFB Crypto_EncryptOFB Crypto_DecryptOFB Crypto_EncryptCTR Crypto_DecryptCTR RSA Public-Key cryptography Introduction Module description Example API RSA_CreateUnit RSA_CloseUnit RSA_WriteKey RSA_Encrypt RSA_Decrypt RSA_Sign RSA_Verify Random Number Generator Introduction Yarrow algorithm Module description Example API RNG_Seed RNG_AddEntropy RNG_Out GenId SPRL 5

6 Acronyms AES : Advanced Encryption Standard API : Application Program Interface CBC : Cipher Block Chaining CBF : Cipher FeedBack CRT : Chinese Remainder Theorem EBC : Electronic Code Block HMAC : keyed-hash Message Authentication Code IV : Initialization Vector MAC : Message Authentication Code NIST : National Institute of Standards and Technology of the United States OFB : Output FeedBack PRNG : Pseudo Random Number Generator RNG : Random Number Generator TRNG : True Random Number Generator SHA : Secure Hash Algorithm 2016 GenId SPRL 6

7 CHAPTER Introduction 1 This library comes in complement to the NanoScale distribution. It is intended to provide state of the art encryption and authentication material. The algorithms currently supported by the library are, for private key encryption: AES, DES, DES-3, IDEA, RC4 and Serpent; for cryptographic hash function: MD5, SHA1, SHA2 and SHA3; for public key encryption and signature: RSA. The library also has a built-in Cryptographically Secure Random Number Generator (CSPRNG) integrated with the NanoScale kernel. The kernel is bound to this generator in order to constantly add entropy and to make it unpredictable. 1.1 Installation The NanoCrypto library is distributed as a self-extracting archive. Simply execute the installation file and follow the stated instruction to deploy it in the directory of your choice (see figure 1.1). Figure 1.1: NanoCrypto self-extracting dialog box Installation process doesn t install any file elsewhere than in the directory of your choice. As a 2016 GenId SPRL 7

8 CHAPTER 1. INTRODUCTION result, the NanoCrypto library can be removed by simply deleting your installation directory Directory Structure Installation deploys several folders in the installation directory. This later is denominated as the <root> directory in picture 1.2. <root> doc library include lib tutorial PIC32 Eth Start Kit Figure 1.2: NanoCrypto directory structure doc directory contains the manuals related to the NanoCrypto library. library - include directory contains NanoCrypto specific header files. Including NanoCrypto.h in your application is enough to get access to the whole NanoCrypto functionalities. library - lib directory contains the NanoCrypto library code. Libraries are classified by processor families. The correct NanoCrypto library must be linked to your application, according to the target processor. This can be done through your IDE. Library naming convention is as follows: libnanocr ypto {Pr ocessor } el f.a, where: Processor gives the target processor family this library is intended for. tutorial - PIC32_Embedded_Connectivity_Starter_Kit_Crypto directory contains a tutorial project for the PIC32MZ EC Starter Kit W/ Crypto Engine development board (DM C). tutorial - PIC32_Ethernet_Starter_Kit directory contains a tutorial project for the PIC32 Ethernet Starter Kit development board (DM320004). tutorial - PIC24E_USB_Starter_Kit directory contains a tutorial project for the PIC24E USB Starter Kit development board (DM240012). tutorial - dspic33e_usb_starter_kit directory contains a tutorial project for the dspic33e USB Starter Kit development board (DM330012) GenId SPRL 8

9 CHAPTER 1. INTRODUCTION 1.2 Restrictions of the Demo version Key sizes are restricted with the Demo version of this library. Wassenaar Arrangement. These restrictions follow the Private-key cryptography is limited to 56-bit key. As a result, this library truncates greater keys to this limit and pads them with zero instead. Public-key cryptography is limited to 512-bit key. Greater keys are rejected by the library GenId SPRL 9

10 CHAPTER Cryptographic Hash Functions 2 This chapter details the usage of the Cryptographic Hash Functions algorithms and their related API. 2.1 Introduction A Hash function is an algorithm that associates a vector of data of arbitrary length to a fixed size number. The outputs of such algorithm are called message digests, hash values, hash codes or checksums. Typical usage of a hash function is to shorten a long vector of data to a more handy value. Such value is then used for example in a hash table. Hash functions are deterministic, they always produce the same output when faced to the same input. They are also not invertible, which is a consequence of the mapping of arbitrary long numbers to fixed size numbers. A Cryptographic Hash Function has additional properties. They are designed in such a way that the probability of collisions is negligible. A collision occurs when two different inputs map to the same output value. They are also designed to resist to malicious collision attacks. Such attacks consist in purposely finding different inputs that generate collisions. In cryptography, Cryptographic Hash Functions are mainly used to ensure the integrity of a message, with the guarantee that it has not been maliciously modified. Therefore, they must not be mistaken with checksum functions. Indeed, such functions try to maximize the probability to detect a bit corrupted in a message, while lowering the size of the checksum. However, they are not designed to resist to malicious corruptions Algorithms presentation MD5 The MD5 message-digest algorithm has been designed by Ron Rivest in 1991 to replace the earlier MD4 hash function. It produces 128-bit message digest size. It has been widely used in various cryptographic applications, but should no longer be used today. Indeed, various weaknesses have been found since Today, a modern computer can generate collisions within seconds. SHA-1 SHA-1 is the second Secure Hash Algorithm designed by the United States National Security Agency (NSA), coming after SHA-0. It produces 160-bit hash values. It has been widely used by a broad 2016 GenId SPRL 10

11 CHAPTER 2. CRYPTOGRAPHIC HASH FUNCTIONS range of applications and protocols since its publication in SHA-1 is not recommended anymore since an attack has been found in 2005, suggesting that the algorithm might not be secure enough for ongoing use. SHA-2 SHA-2 has also been designed by the United States National Security Agency (NSA). This algorithm is declined in a set of different flavours: SHA-256: Algorithm iterates on 32-bit words and produces 256-bit message digests; SHA-512: Algorithm iterates on 64-bit words and produces 512-bit message digests; SHA-224: Truncated version of SHA-256 that produces 224-bit message digests; SHA-384: Truncated version of SHA-512 that produces 384-bit message digests; SHA-2 shares a similar geometrical structure than SHA-1. Therefore, the security flaw found for SHA-1 would suggest that some mathematical weakness would also exist for SHA-2. However, no any successful attacks have been found up to now for SHA-2. SHA-3 Because of the potential issue that exists with SHA-2, the US National Institute of Standards and Technology (NIST) organized in 2007 a hash function competition, similar to the Advanced Encryption Standard (AES) competition. The competition ended in 2012 when the NIST announced that Keccak would be the new SHA-3 hash algorithm. Keccak is based on a sponge construction and has therefore a completely different structure than the previous known hash functions. Similar to SHA-2, it is declined in different versions in order to produce 224, 256, 384 or 512-bit message digests. This implementation is compliant with the Federal Information Processing Standard (FIPS) 202, released in Augustus Module description The different hash algorithms must be initialized before they can be used. This is done by invoking one or more of the following functions at initialization: MD5_Init: Registers the MD5 hash function algorithm on the system; SHA1_Init: Registers the SHA-1 hash function algorithm on the system; SHA2_256_Init: Registers the SHA2-224 and SHA2-256 hash function algorithms on the system; SHA2_512_Init: Registers the SHA2-384 and SHA2-512 hash function algorithms on the system; SHA3_Init: Registers the SHA3-224, SHA3-256, SHA3-384 and SHA3-512 hash function algorithm on the system; Except for initialization, all the hash algorithms implemented in this library are accessed through a generic common API. To use a hash function, a hashing unit must first be created on the system. This is done tanks to function Hash_CreateUnit. Then, hashing a message to produce a message digest is done in 3 steps: 2016 GenId SPRL 11

12 CHAPTER 2. CRYPTOGRAPHIC HASH FUNCTIONS 1. Call Hash_Begin in order to reset the unit in its initial state; 2. Call Hash_Update iteratively in order to digest the message in one or more iterations; 3. Call Hash_Finalize in order to deliver the final digest; A hashing unit is not reentrant. Therefore, it must be appropriately protected with a mutex in a multi-thread environment Example HANDLE hashunit ; int main () { InitKernel ();... // Register the MD5 hash algorithm on the system MD5_Init (); // Static allocation of a hashing unit based on MD5 hashunit = Hash_CreateUnit ( ALGO_MD5 ); } // Start the kernel StartKernel (); void HashTask ( void * param ) { char str1 [] = " Hello "; char str2 [] = " World "; Byte hash [16]; // Start a new hash computation Hash_Begin ( hashunit ); // Digest the message in 2 steps Hash_Update ( hashunit, ( Byte *) str1, sizeof ( str1 )); Hash_Update ( hashunit, ( Byte *) str2, sizeof ( str2 )); } // Output the final digest Hash_Finalize ( hashunit, hash ); 2016 GenId SPRL 12

13 CHAPTER 2. CRYPTOGRAPHIC HASH FUNCTIONS 2.2 API Table below lists the different functions related to the Cryptographic Hash Functions management. Flags indicating calling usage are given for each of them. API Init Task Fiber ISR Hash_CreateUnit Creates a hashing unit. Hash_CloseUnit Closes a hashing unit. Hash_GetOid Returns hash algorithm OID. Hash_GetDigestSize Returns hash algorithm message digest size. Hash_Begin Begins a new message digest computation. Hash_Update Digests additional data. Hash_Finalize Finalizes and delivers message digest. Table 2.1: Cryptographic Hash Functions API 2016 GenId SPRL 13

14 CHAPTER 2. CRYPTOGRAPHIC HASH FUNCTIONS Hash_CreateUnit Creates a hashing unit. Prototype NS_ API HANDLE Hash_ CreateUnit ( NS_ Algo algo ); Parameters algo Return value Underlying hash algorithm. HANDLE of a Hash Function unit. INVALID_HANDLE in case of failure. Details This function creates a hashing unit based on the algorithm requested by algo. It returns a valid Handle if the unit could be created. It is necessary to initialize the target algorithm to work with before calling this function, see section Parameter algo can take the following values: ALGO_MD5: MD5 with 16 Bytes digest size; ALGO_SHA1: SHA1 with 20 Bytes digest size; ALGO_SHA2_224: SHA2 with 28 Bytes digest size; ALGO_SHA2_256: SHA2 with 32 Bytes digest size; ALGO_SHA2_384: SHA2 with 48 Bytes digest size; ALGO_SHA2_512: SHA2 with 64 Bytes digest size; ALGO_SHA3_224: SHA3 with 28 Bytes digest size; ALGO_SHA3_256: SHA3 with 32 Bytes digest size; ALGO_SHA3_384: SHA3 with 48 Bytes digest size; ALGO_SHA3_512: SHA3 with 64 Bytes digest size; Error cases Errors ERR_CRYPTO_NOMEM No enough memory to create the unit GenId SPRL 14

15 CHAPTER 2. CRYPTOGRAPHIC HASH FUNCTIONS Hash_CloseUnit Closes a hashing unit. Prototype NS_ API void Hash_ CloseUnit ( HANDLE unit ); Parameters unit Unit to close. Details This function closes the unit and invalidates its Handle so it cannot be used anymore. If the unit was created after the function StartKernel is called, associated resources are also returned to the heap. It is the user s responsibility to check nobody is still using a unit before closing it. Error cases Errors ERR_CRYPTO_DELETED ERR_HANDLE_INVALID Referenced unit has been deleted. This is not a valid hashing unit handle GenId SPRL 15

16 CHAPTER 2. CRYPTOGRAPHIC HASH FUNCTIONS Hash_GetOid Returns hash algorithm OID. Prototype NS_ API const Byte * Hash_ GetOid ( HANDLE unit ); Parameters unit Return value Target unit. Pointer to the null terminated OID vector. Details This function returns a pointer to a null terminated Object Identifier identifying the underlying hashing algorithm. An OID is an identifier used to uniquely name an object, in this case the hashing algorithm. OID is made of successive numbers, each of them identifying a node in a tree. This naming convention follows the ASN.1 standard X.690. For example, MD5 OID is and is encoded with the following vector in ASN.1 notation: [0x2A, 0x86, 0x48, 0x86, 0xF7, 0x0D, 0x02, 0x05]. Error cases Errors ERR_CRYPTO_DELETED ERR_HANDLE_INVALID Referenced unit has been deleted. This is not a valid hashing unit handle GenId SPRL 16

17 CHAPTER 2. CRYPTOGRAPHIC HASH FUNCTIONS Hash_GetDigestSize Returns hash algorithm message digest size. Prototype NS_API int Hash_GetDigestSize ( HANDLE unit ); Parameters unit Return value Target unit. Hash algorithm digest size [B]. Details This function returns the digest size of the underlying hashing algorithm, in Bytes. Error cases Errors ERR_CRYPTO_DELETED ERR_HANDLE_INVALID Referenced unit has been deleted. This is not a valid hashing unit handle GenId SPRL 17

18 CHAPTER 2. CRYPTOGRAPHIC HASH FUNCTIONS Hash_Begin Begins a new message digest computation. Prototype NS_ API void Hash_ Begin ( HANDLE unit ); Parameters unit Target unit. Details This function begins the computation of a new digest from message data. The internal state of the algorithm is reset by calling this function, so that the digest can be iteratively computed by successive calls to function Hash_Update. Once all the data have been digested, function Hash_Finalize can be called in order to finalize the computation and to output the result. Error cases Errors ERR_CRYPTO_DELETED ERR_HANDLE_INVALID Referenced unit has been deleted. This is not a valid hashing unit handle GenId SPRL 18

19 CHAPTER 2. CRYPTOGRAPHIC HASH FUNCTIONS Hash_Update Digests additional data. Prototype NS_ API void Hash_ Update ( HANDLE unit, const Byte * pdata, int len ); Parameters unit pdata len Target unit. Pointer to the data to digest. Data length [B]. Details This function can be called multiple time in order to digest message data iteratively. Once all the data are digested, final digest can be computed thanks to the function Hash_Finalize. Error cases Errors ERR_CRYPTO_DELETED ERR_HANDLE_INVALID Referenced unit has been deleted. This is not a valid hashing unit handle GenId SPRL 19

20 CHAPTER 2. CRYPTOGRAPHIC HASH FUNCTIONS Hash_Finalize Finalizes and delivers message digest. Prototype NS_ API void Hash_ Finalize ( HANDLE unit, Byte * pdigest ); Parameters unit pdigest Target unit. Pointer to the output digest buffer. Must be than the underlying algorithm digest size. Details This function outputs the final digest computation that has been performed on message data thanks to the function Hash_Update. The length of the message digest depends on the underlying algorithm: MD5: 16 Bytes; SHA1: 20 Bytes; SHA2: 28, 32, 48 or 64 Bytes; SHA3: 28, 32, 48 or 64 Bytes; Error cases Errors ERR_CRYPTO_DELETED ERR_HANDLE_INVALID Referenced unit has been deleted. This is not a valid hashing unit handle GenId SPRL 20

21 CHAPTER Symmetric-Key Algorithms 3 This chapter details the usage of the Symmetric-Key Encryption algorithms and their related API. 3.1 Introduction Symmetric-key encryption algorithms are cryptographic primitives that rely on a shared secret between two parties in order to perform encryption and decryption of a message. Indeed, the keys needed to perform both operations are identical and need to be shared between communicating entities. The advantage of symmetric (or private) key algorithms is that they are considerably faster than their asymmetric (or public) counterparts. Depending on the algorithm, encryption can be done on a stream of Bytes (stream cipher), or on a fixed-size block of data (block cipher) Algorithms presentation AES The Advanced Encryption Standard (AES) is the winner of a five-year international standardization process competition organized by the National Institute of Standards and Technology of the United States (NIST). Competition ran from 1997 to 2001 and was intended to propose a successor for the aging Data Encryption Standard (DES). 15 competing designs were presented and evaluated, among which the Rijndael cipher was selected as the most suitable. The name Rijndael comes from the names of the two Belgian cryptographer inventors: Joan Daemen and Vincent Rijmen. It is a 128 bits block size algorithm, with key sizes of 128, 192 or 256 bits. DES The Data Encryption Standard (DES) was the widely spread symmetric-key algorithm before it was superseded by its successor, the AES. It has been developed in the early 1970s and published as an official Federal Information Processing Standard (FIPS) in Because of its small 56 bits key size, DES is now considered insecure for many usages. However, it is still believed to be secure in the form of Triple DES. This algorithms operates on 64 bits blocks, with 56 bits key sizes GenId SPRL 21

22 CHAPTER 3. SYMMETRIC-KEY ALGORITHMS Triple DES Triple DES has been used as a simple method to go beyond the weaknesses of the DES algorithm without having to design a new block cipher. It consists in applying the DES algorithm three times on the data, with different keys. As a result, Triple DES operates on 64 bits blocks, with key sizes of 56, 112 or 168 bits. IDEA The International Data Encryption Algorithm (IDEA) is a block cipher designed by James Massey and Xuejia Lai in It was intended has a replacement for the DES algorithm. It has been patented in many countries, but the last patents expired in 2012 and it is now free to use. IDEA operates on 64 bits blocks and with 128 bits key sizes. RC4 RC4 is a stream cipher designed by Ron Rivest in The main reasons of its success are its speed and the simplicity to implement it. RC4 generates a pseudo random stream of bits that are simply combined with data by using an exclusive-or operation. Key sizes goes from 40 to 2048 bits. RC4 is widely used in different protocols and standards like WEP, WPA and SSL/TLS, but presents anyway some weaknesses that argue against its use in new systems. Serpent Serpent is a block cipher designed by Ross Anderson, Eli Biham and Lars Knudsen. It was finalist in the AES contest and came second to Rijndael. Although considered more secured, it was discarded because its execution speed is quite slower than Rijndael. Serpent is believed to be one of the safer algorithm available today. As AES, it operates on 128 bits block size with 128, 192 or 256 bits key Encryption modes Different encryption modes are available to perform encryption on data larger than the chosen algorithm block size. An encryption mode specifies how different blocks of data are daisy chained together to securely perform encryption. Chaining avoids that identical blocks of data produce the same ciphered blocks. Chaining modes have also different properties in term of error propagation, parallelization capabilities, etc. ECB Electronic Code Block is the simplest encryption mode. Each block of data is encrypted separately, with the drawback that identical data blocks produce the same outputs. As a result, it doesn t hide data patterns very well, and is not recommended at all. CBC Cipher-Block Chaining consists in XORing the data with the previous block encryption result, before actually encrypt it. The first block is scrambled with an Initialization Vector (IV) containing random data. As a result, each encrypted block depends on all the previous blocks GenId SPRL 22

23 CHAPTER 3. SYMMETRIC-KEY ALGORITHMS CFB Cipher FeedBack mode consists in XORing the data with a pseudo one-time pad stream. Each new block of the stream is generated by encrypting the previous block of encrypted data. Unlike CBC, the message doesn t need to be padded to a multiple of the cipher block size. In addition, the block cipher is only used in the encryption direction mode (both for encryption and decryption). OFB Output FeedBack mode is similar to CFB. It consists in XORing the data with a pseudo one-time pad stream. However, the stream is generated by continuously encrypting the previous block of the stream, starting with the Initialization Vector (IV). CTR Like OFB, Counter mode consist in XORing the data with a pseudo one-time pad stream. However, each block of the stream is generated by encrypting an incrementing counter Module description The different symmetric-key algorithms must be initialized before they can be used. This is done by invoking one or more of the following functions at initialization: RC4_Init: Registers the RC4 stream cipher algorithm on the system; DES_Init: Registers the DES block cipher algorithm on the system; DES3_Init: Registers the Triple DES block cipher algorithm on the system; AES_Init: Registers the AES block cipher algorithm on the system; AES_Fast_Init: Registers the AES block cipher algorithm on the system; IDEA_Init: Registers the IDEA block cipher algorithm on the system; SERPENT_Init: Registers the Serpent block cipher algorithm on the system; Functions AES_Init and AES_Fast_Init are mutually exclusive and actually register the same AES cipher on the system, but give access to two different implementations of this algorithm. The regular one has a lower footprint but is also slower. The fast version takes 4 times more space in ROM but is also 4 times faster. Except for initialization, all the symmetric-key algorithms implemented in this library are accessed through a generic common API. To benefit from encryption, a symmetric-key unit must first be created on the system. This is done tanks to function Crypto_CreateUnit. Function Crypto_SetKey is used to configure the symmetric-key unit with the encryption/decryption key. Appropriate key size depends on the underlying algorithm. Finally, a pair of encryption / decryption functions are provided for each encryption mode described above. A Symmetric-key unit is not reentrant. Therefore, it must be appropriately protected with a mutex in a multi-thread environment. Because of a bug in the XC16 v1.26 compiler, AES Fast algorithm is not available on the PIC24 architecture GenId SPRL 23

24 CHAPTER 3. SYMMETRIC-KEY ALGORITHMS Example int main () { InitKernel ();... // Register the AES algorithm on the system AES_Init (); } // Start the kernel StartKernel (); void CryptoTask ( void * param ) { HANDLE unit ; char str [16] = " Hello World "; Byte key [16] = {0 x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0 x0f }; Byte bloc [16]; // Dynamic allocation of a AES crypto unit on the system unit = Cr ypto_c reateu nit ( ALGO_AES ); // Set the key Crypto_SetKey ( unit, key, sizeof ( key )); // Encrypt a single block ( 128 bits ) of data Crypto_Encrypt ( unit, ( Byte *) str, bloc, sizeof ( bloc )); // Decrypt it in place Crypto_Decrypt ( unit, bloc, bloc, sizeof ( bloc )); } // Release the crypto unit Crypto_CloseUnit ( unit ); 2016 GenId SPRL 24

25 CHAPTER 3. SYMMETRIC-KEY ALGORITHMS 3.2 API Table below lists the different functions related to the symmetric-key algorithms management. Flags indicating calling usage are given for each of them. API Init Task Fiber ISR Crypto_CreateUnit Creates a symmetric-key encryption unit. Crypto_CloseUnit Closes a symmetric-key encryption unit. Crypto_GetBlockSize Returns the block size of the underlying algorithm. Crypto_SetKey Specifies the key for encryption and decryption. Crypto_Encrypt Encrypts stream cipher data, or block cipher data in ECB mode. Crypto_EncryptCBC Encrypts block cipher data in CBC mode. Crypto_EncryptCFB Encrypts block cipher data in CFB mode. Crypto_EncryptOFB Encrypts block cipher data in OFB mode. Crypto_EncryptCTR Encrypts block cipher data in CTR mode. Crypto_Decrypt Decrypts stream cipher data, or block cipher data in ECB mode. Crypto_DecryptCBC Decrypts block cipher data in CBC mode. Crypto_DecryptCFB Decrypts block cipher data in CFB mode. Crypto_DecryptOFB Decrypts block cipher data in OFB mode. Crypto_DecryptCTR Decrypts block cipher data in CTR mode. Table 3.1: Symmetric-key algorithms API 2016 GenId SPRL 25

26 CHAPTER 3. SYMMETRIC-KEY ALGORITHMS Crypto_CreateUnit Creates a symmetric-key encryption unit. Prototype NS_ API HANDLE Cry pto_ Cr eateun it ( NS_ Algo algo ); Parameters algo Return value Underlying encryption algorithm. HANDLE of a symmetric-key encryption unit. INVALID_HANDLE in case of failure. Details This function creates a symmetric-key encryption unit based on the algorithm requested by algo. It returns a valid Handle if the unit could be created. It is necessary to initialize the target algorithm to work with before calling this function, see section Parameter algo can take the following values: ALGO_AES: AES block cipher; ALGO_DES: DES block cipher; ALGO_DES3: Triple DES block cipher; ALGO_IDEA: IDEA block cipher; ALGO_SERPENT: Serpent block cipher; ALGO_RC4: RC4 stream cipher; Error cases Errors ERR_CRYPTO_NOMEM No enough memory to create the unit GenId SPRL 26

27 CHAPTER 3. SYMMETRIC-KEY ALGORITHMS Crypto_CloseUnit Closes a symmetric-key encryption unit. Prototype NS_ API void Crypto_ CloseUnit ( HANDLE unit ); Parameters unit Unit to close. Details This function closes the unit and invalidates its Handle so it cannot be used anymore. If the unit was created after the function StartKernel is called, associated resources are also returned to the heap. It is the user s responsibility to check nobody is still using a unit before closing it. Error cases Errors ERR_CRYPTO_DELETED ERR_HANDLE_INVALID Referenced unit has been deleted. This is not a valid unit handle GenId SPRL 27

28 CHAPTER 3. SYMMETRIC-KEY ALGORITHMS Crypto_GetBlockSize Returns the block size of the underlying algorithm. Prototype NS_API int Crypto_GetBlockSize ( HANDLE unit ); Parameters unit Return value Target unit. Block cipher: Algorithm block size [B]. Stream cipher: 0. Details This function returns the block size of the underlying symmetric-key algorithm, in Bytes. This value is greater than 0 in the case of a block cipher algorithm. For a stream cipher algorithm, this function returns 0. Error cases Errors ERR_CRYPTO_DELETED ERR_HANDLE_INVALID Referenced unit has been deleted. This is not a valid unit handle GenId SPRL 28

29 CHAPTER 3. SYMMETRIC-KEY ALGORITHMS Crypto_SetKey Specifies the key for encryption and decryption. Prototype NS_ API void Crypto_ SetKey ( HANDLE unit, const Byte * pkey, int keylen ); Parameters unit pkey keylen Target unit. Pointer to the key data. Key length [B]. Details This function sets the key to use for encryption and decryption. Valid key size, in Bytes, depends on the underlying algorithm: AES: 16, 24 or 32 Bytes; DES: 8 Bytes (including parity bits); Triple DES: 8, 16 or 24 Bytes (including parity bits); IDEA: 16 Bytes; RC4: [1; 256] Bytes; Serpent: 16, 24 or 32 Bytes; Error cases Errors ERR_CRYPTO_BADKEY ERR_CRYPTO_DELETED ERR_HANDLE_INVALID Invalid key size. Referenced unit has been deleted. This is not a valid unit handle GenId SPRL 29

30 CHAPTER 3. SYMMETRIC-KEY ALGORITHMS Crypto_Encrypt Encrypts stream cipher data, or block cipher data in ECB mode. Prototype NS_ API void Crypto_ Encrypt ( HANDLE unit, const Byte * ptext, Byte * pciphered, int len ); Parameters unit ptext pciphered len HANDLE of a symmetric-key unit Data to encrypt. Buffer to store the encrypted data. Data length in Bytes. Must be a multiple of the underlying algorithm block size. Details This function encrypts data, either with a block cipher algorithm in Electronic Code Block mode, or with a stream cipher. Data to encrypt must be a multiple of the underlying algorithm block size (in the case of a block cipher). When the function returns, pciphered is filled with the ciphering process result. The function accepts that pciphered and ptext point to the same buffer. In this case, encryption is performed in place. Error cases Errors ERR_CRYPTO_BADSIZE ERR_SOCKET_DELETED ERR_HANDLE_INVALID Data length is not a multiple of the underlying algorithm block size. Referenced unit has been deleted. This is not a valid unit handle GenId SPRL 30

31 CHAPTER 3. SYMMETRIC-KEY ALGORITHMS Crypto_Decrypt Decrypts stream cipher data, or block cipher data in ECB mode. Prototype NS_ API void Crypto_ Decrypt ( HANDLE unit, const Byte * pciphered, Byte * ptext, int len ); Parameters unit pciphered ptext len HANDLE of a symmetric-key unit Data to decrypt. Buffer to store the decrypted data. Data length in Bytes. Must be a multiple of the underlying algorithm block size. Details This function decrypts data that have been encrypted, either with a block cipher algorithm in Electronic Code Block mode, or with a stream cipher. Data to decrypt must be a multiple of the underlying algorithm block size. When the function returns, ptext is filled with the deciphering process result. The function accepts that pciphered and ptext point to the same buffer. In this case, decryption is performed in place. Error cases Errors ERR_CRYPTO_BADSIZE ERR_SOCKET_DELETED ERR_HANDLE_INVALID Data length is not a multiple of the underlying algorithm block size. Referenced unit has been deleted. This is not a valid unit handle GenId SPRL 31

32 CHAPTER 3. SYMMETRIC-KEY ALGORITHMS Crypto_EncryptCBC Encrypts block cipher data in CBC mode. Prototype NS_ API void Cry pto_ En cryptc BC ( HANDLE unit, Byte * piv, const Byte * ptext, Byte * pciphered, int len ); Parameters unit piv ptext pciphered len HANDLE of a symmetric-key unit IV value. Must have same size than the underlying algorithm block size. Data to encrypt. Buffer to store the encrypted data. Data length in Bytes. Must be a multiple of the underlying algorithm block size. Details This function encrypts with a block cipher algorithm in Cipher Block Chaining mode. Data to encrypt must be a multiple of the underlying algorithm block size. When the function returns, pciphered is filled with the ciphering process result and piv contains the new Initialization Vector (IV) value suitable for encryption of the next blocks of data. The function accepts that pciphered and ptext point to the same buffer. In this case, encryption is performed in place. Error cases Errors ERR_CRYPTO_BADSIZE ERR_SOCKET_DELETED ERR_HANDLE_INVALID Data length is not a multiple of the underlying algorithm block size. Referenced unit has been deleted. This is not a valid unit handle GenId SPRL 32

33 CHAPTER 3. SYMMETRIC-KEY ALGORITHMS Crypto_DecryptCBC Decrypts block cipher data in CBC mode. Prototype NS_ API void Cry pto_ De cryptc BC ( HANDLE unit, Byte * piv, const Byte * pciphered, Byte * ptext, int len ); Parameters unit piv pciphered ptext len HANDLE of a symmetric-key unit IV value. Must have same size than the underlying algorithm block size. Data to decrypt. Buffer to store the decrypted data. Data length in Bytes. Must be a multiple of the underlying algorithm block size. Details This function decrypts data that have been encrypted with a block cipher algorithm in Cipher Block Chaining mode. Data to decrypt must be a multiple of the underlying algorithm block size. When the function returns, ptext is filled with the deciphering process result and piv contains the new Initialization Vector (IV) value suitable for decryption of the next blocks of data. The function accepts that pciphered and ptext point to the same buffer. In this case, decryption is performed in place. Error cases Errors ERR_CRYPTO_BADSIZE ERR_SOCKET_DELETED ERR_HANDLE_INVALID Data length is not a multiple of the underlying algorithm block size. Referenced unit has been deleted. This is not a valid unit handle GenId SPRL 33

34 CHAPTER 3. SYMMETRIC-KEY ALGORITHMS Crypto_EncryptCFB Encrypts block cipher data in CFB mode. Prototype NS_ API void Cry pto_ En cryptc FB ( HANDLE unit, Byte * piv, const Byte * ptext, Byte * pciphered, int len ); Parameters unit piv ptext pciphered len HANDLE of a symmetric-key unit IV value. Must have same size than the underlying algorithm block size. Data to encrypt. Buffer to store the encrypted data. Data length in Bytes. Must be a multiple of the underlying algorithm block size. Details This function encrypts data with a block cipher algorithm in Cipher Feedback mode. Data to encrypt must be a multiple of the underlying algorithm block size. When the function returns, pciphered is filled with the ciphering process result and piv contains the new Initialization Vector (IV) value suitable for encryption of the next blocks of data. The function accepts that pciphered and ptext point to the same buffer. In this case, encryption is performed in place. Error cases Errors ERR_CRYPTO_BADSIZE ERR_SOCKET_DELETED ERR_HANDLE_INVALID Data length is not a multiple of the underlying algorithm block size. Referenced unit has been deleted. This is not a valid unit handle GenId SPRL 34

35 CHAPTER 3. SYMMETRIC-KEY ALGORITHMS Crypto_DecryptCFB Decrypts block cipher data in CFB mode. Prototype NS_ API void Cry pto_ De cryptc FB ( HANDLE unit, Byte * piv, const Byte * pciphered, Byte * ptext, int len ); Parameters unit piv pciphered ptext len HANDLE of a symmetric-key unit IV value. Must have same size than the underlying algorithm block size. Data to decrypt. Buffer to store the decrypted data. Data length in Bytes. Must be a multiple of the underlying algorithm block size. Details This function decrypts data that have been encrypted with a block cipher algorithm in Cipher Feedback mode. Data to decrypt must be a multiple of the underlying algorithm block size. When the function returns, ptext is filled with the deciphering process result and piv contains the new Initialization Vector (IV) value suitable for decryption of the next blocks of data. The function accepts that pciphered and ptext point to the same buffer. In this case, decryption is performed in place. Error cases Errors ERR_CRYPTO_BADSIZE ERR_SOCKET_DELETED ERR_HANDLE_INVALID Data length is not a multiple of the underlying algorithm block size. Referenced unit has been deleted. This is not a valid unit handle GenId SPRL 35

36 CHAPTER 3. SYMMETRIC-KEY ALGORITHMS Crypto_EncryptOFB Encrypts block cipher data in OFB mode. Prototype NS_ API void Cry pto_ En crypto FB ( HANDLE unit, Byte * piv, const Byte * ptext, Byte * pciphered, int len ); Parameters unit piv ptext pciphered len HANDLE of a symmetric-key unit IV value. Must have same size than the underlying algorithm block size. Data to encrypt. Buffer to store the encrypted data. Data length in Bytes. Must be a multiple of the underlying algorithm block size. Details This function encrypts data with a block cipher algorithm in Output Feedback mode. Data to encrypt must be a multiple of the underlying algorithm block size. When the function returns, pciphered is filled with the ciphering process result and piv contains the new Initialization Vector (IV) value suitable for encryption of the next blocks of data. The function accepts that pciphered and ptext point to the same buffer. In this case, encryption is performed in place. Error cases Errors ERR_CRYPTO_BADSIZE ERR_SOCKET_DELETED ERR_HANDLE_INVALID Data length is not a multiple of the underlying algorithm block size. Referenced unit has been deleted. This is not a valid unit handle GenId SPRL 36

37 CHAPTER 3. SYMMETRIC-KEY ALGORITHMS Crypto_DecryptOFB Decrypts block cipher data in OFB mode. Prototype NS_ API void Cry pto_ De crypto FB ( HANDLE unit, Byte * piv, const Byte * pciphered, Byte * ptext, int len ); Parameters unit piv pciphered ptext len HANDLE of a symmetric-key unit IV value. Must have same size than the underlying algorithm block size. Data to decrypt. Buffer to store the decrypted data. Data length in Bytes. Must be a multiple of the underlying algorithm block size. Details This function decrypts data that have been encrypted with a block cipher algorithm in Output Feedback mode. Data to decrypt must be a multiple of the underlying algorithm block size. When the function returns, ptext is filled with the deciphering process result and piv contains the new Initialization Vector (IV) value suitable for decryption of the next blocks of data. The function accepts that pciphered and ptext point to the same buffer. In this case, decryption is performed in place. Error cases Errors ERR_CRYPTO_BADSIZE ERR_SOCKET_DELETED ERR_HANDLE_INVALID Data length is not a multiple of the underlying algorithm block size. Referenced unit has been deleted. This is not a valid unit handle GenId SPRL 37

38 CHAPTER 3. SYMMETRIC-KEY ALGORITHMS Crypto_EncryptCTR Encrypts block cipher data in CTR mode. Prototype NS_ API void Cry pto_ En cryptc TR ( HANDLE unit, Byte * pcounter, const Byte * ptext, Byte * pciphered, int len ); Parameters unit pcounter ptext pciphered len HANDLE of a symmetric-key unit Initial counter value. Must have same size than the underlying algorithm block size. Data to encrypt. Buffer to store the encrypted data. Data length in Bytes. Must be a multiple of the underlying algorithm block size. Details This function encrypts data with a block cipher algorithm in Counter (CTR) mode. Data to encrypt must be a multiple of the underlying algorithm block size. When the function returns, pciphered is filled with the ciphering process result and pcounter contains the new counter value suitable for encryption of the next blocks of data. The function accepts that pciphered and ptext point to the same buffer. In this case, encryption is performed in place. Error cases Errors ERR_CRYPTO_BADSIZE ERR_SOCKET_DELETED ERR_HANDLE_INVALID Data length is not a multiple of the underlying algorithm block size. Referenced unit has been deleted. This is not a valid unit handle GenId SPRL 38

39 CHAPTER 3. SYMMETRIC-KEY ALGORITHMS Crypto_DecryptCTR Decrypts block cipher data in CTR mode. Prototype NS_ API void Cry pto_ De cryptc TR ( HANDLE unit, Byte * pcounter, const Byte * pciphered, Byte * ptext, int len ); Parameters unit pcounter pciphered ptext len HANDLE of a symmetric-key unit Initial counter value. Must have same size than the underlying algorithm block size. Data to decrypt. Buffer to store the decrypted data. Data length in Bytes. Must be a multiple of the underlying algorithm block size. Details This function decrypts data that have been encrypted with a block cipher algorithm in Counter (CTR) mode. Data to decrypt must be a multiple of the underlying algorithm block size. When the function returns, ptext is filled with the deciphering process result and pcounter contains the new counter value suitable for decryption of the next blocks of data. The function accepts that pciphered and ptext point to the same buffer. In this case, decryption is performed in place. Error cases Errors ERR_CRYPTO_BADSIZE ERR_SOCKET_DELETED ERR_HANDLE_INVALID Data length is not a multiple of the underlying algorithm block size. Referenced unit has been deleted. This is not a valid unit handle GenId SPRL 39

40 CHAPTER RSA Public-Key cryptography 4 This chapter details the usage of the RSA Public-Key cryptography and its related API. 4.1 Introduction RSA stands for Ron Rivest, Adi Shamir and Leonard Adleman, the inventors of this public-key cryptosystem that has been described in RSA is the first practicable and most known publickey algorithm, widely used today to secure data transmission. In contrast to private-key (or symmetric-key) cryptography, public-key (or asymmetric-key) cryptography doesn t need that two parties first agree on a shared secret before to communicate with each other. Each party needs a public-key / private-key pair. However, the public-key doesn t need to be kept secret, and may in fact be widely available. Public-key cryptography is based on one way functions with trapdoor. A one way function is a function that is not easily invertible, i.e. it is easy to compute on every input, but hard to invert given the image of this input. A trapdoor function is a one way function that can still be easily inverted if you know special information, called the trapdoor. In the context of cryptography, the trapdoor is the private key. Therefore, two parties can freely exchange their public-key before to communicate with each other. If entity A wants to send a message to entity B, it can encrypt it with A public-key, so that only A is able to decrypt it with its private-key. Public-key encryption also enables the concept of authentication. Authentication consist in providing a digital signature with a private-key, so that anyone can verify its authenticity by using the signing entity public-key. Success confirm the message is unmodified and that the signer, and no one else, generated the signature. RSA algorithm is based on a hard mathematical problem, related to the intractability of factoring large integers. As a result, the public-key is based on the factor of two large prime numbers, while the private key is based on the prime factors Module description RSA processing can be done by first creating a RSA unit thanks to the functionrsa_createunit. This function requires an Handle on a Hash unit (see chapter 2) that is needed for nearly all the RSA 2016 GenId SPRL 40

41 CHAPTER 4. RSA PUBLIC-KEY CRYPTOGRAPHY operations (except for PKCK 1 v1.5 encryption). In addition, a configuration parameter enables to select between two encryption or signature schemes: PKCS 1 v1.5, encryption: older encryption/decryption scheme as first standardized in version 1.5 of PKCS #1. PKCS 1 v1.5, signature: old signature scheme with appendix as first standardized in version 1.5 of PKCS #1. OAEP, encryption: improved encryption/decryption scheme; based on the Optimal Asymmetric Encryption Padding scheme proposed by Mihir Bellare and Phillip Rogaway. PSS, signature: improved probabilistic signature scheme with appendix; based on the Probabilistic Signature Scheme originally invented by Bellare and Rogaway. Then, all the keys required for the encryption/decryption operations must be loaded. This can be achieved, one key at a time, with function RSA_WriteKey. Once all the cryptographic material has been loaded, encryption and decryption can be achieved with functions RSA_Encrypt and RSA_Decrypt. Signature generation is done with function RSA_Sign, while function RSA_Verify enables to perform a signature verification. All the RSA operations require to generate random seeds or random salts. These random data are generated through the Random Number Generator of this library (see chapter 5). As a result, the RNG needs to be seeded before using RSA operations, otherwise the error ERR_CRYPTO_SEED is raised Example /// RSA public and private keys ( 512 bits ) static const Byte kd [ 64] = { 0xAC, 0xE5, 0xCC, 0x5E, 0x11, 0x44, 0x52, 0x65, 0xC3, 0x73, 0xA2, 0xE3, 0xBB, 0xE2, 0xD7, 0x6F, 0x77, 0xBD, 0xCA, 0x1E, 0xED, 0x4D, 0x66, 0xC7, 0xBE, 0x36, 0x0D, 0xCA, 0x8D, 0x7B, 0xEB, 0x3F, 0x3C, 0x30, 0x3B, 0x03, 0x54, 0x07, 0x6B, 0x61, 0xD0, 0x03, 0x1A, 0x99, 0x07, 0x8C, 0x58, 0x57, 0x2D, 0x45, 0x2D, 0xE4, 0xC4, 0x48, 0xE3, 0x1A, 0xB2, 0xB0, 0xD6, 0xEE, 0x43, 0xF1, 0x60, 0 x81 }; static const Byte kn [ 64] = { 0xB4, 0xD6, 0xCB, 0x2D, 0x38, 0xDA, 0x51, 0x2C, 0x55, 0x11, 0x6B, 0x17, 0xEA, 0x8D, 0x8C, 0x11, 0x6F, 0x1A, 0xE3, 0x06, 0x12, 0xAC, 0x2D, 0x0B, 0x5D, 0xBA, 0x20, 0xC2, 0xC8, 0x4B, 0x70, 0x8C, 0xA0, 0x94, 0xC1, 0x55, 0x9D, 0x75, 0xB4, 0xB4, 0x46, 0x3A, 0x66, 0x09, 0x9E, 0x6B, 0x14, 0xDD, 0x7B, 0x02, 0x19, 0x85, 0xB0, 0xB5, 0xF8, 0x94, 0xC3, 0xEE, 0xB9, 0x5D, 0x32, 0xA5, 0xFD, 0 xc9 }; static const Byte ke [4] = {0 x00, 0 x01, 0 x00, 0 x01 }; int main () { Byte random [32]; InitKernel (); 2016 GenId SPRL 41