M2MB_RSA

The RSA public-key cryptosystem. More...

Enumerations
enum	M2MB_CRYPTO_RSA_PADDING_TYPE_E {   M2MB_CRYPTO_RSA_PADDING_PKCS1_V15, M2MB_CRYPTO_RSA_PADDING_PKCS1_OAEP, M2MB_CRYPTO_RSA_PADDING_PKCS1_PSS, M2MB_CRYPTO_RSA_PADDING_PKCS1_PSS_AUTORECOVER_SALTLEN,   M2MB_CRYPTO_RSA_PADDING_NONE }
	Padding types for RSA encryption. More...
enum	M2MB_CRYPTO_RSA_MODE_E { M2MB_CRYPTO_RSA_PUBLIC, M2MB_CRYPTO_RSA_PRIVATE }
	The operation mode (encrypt/decrypt).

Functions
M2MB_RESULT_E	m2mb_crypto_rsa_init (M2MB_CRYPTO_RSA_CONTEXT *ctx, M2MB_CRYPTO_RSA_PADDING_TYPE_E padding_type, M2MB_CRYPTO_MD_ALG_E hash_id)
	Allocates an M2MB_CRYPTO_RSA_CONTEXT structure. More...
M2MB_RESULT_E	m2mb_crypto_rsa_deinit (M2MB_CRYPTO_RSA_CONTEXT ctx)
	Free an M2MB_CRYPTO_RSA_CONTEXT structure. More...
M2MB_RESULT_E	m2mb_crypto_rsa_public (M2MB_CRYPTO_RSA_CONTEXT ctx, const UINT8 *in, UINT8 *out)
	RSA public key operation. More...
M2MB_RESULT_E	m2mb_crypto_rsa_private (M2MB_CRYPTO_RSA_CONTEXT ctx, const UINT8 *in, UINT8 *out)
	RSA private key operation. More...
M2MB_RESULT_E	m2mb_crypto_rsa_generate_key (M2MB_CRYPTO_RSA_CONTEXT ctx, UINT32 key_size, UINT32 public_exponent)
	Generates an RSA key pair. More...
M2MB_RESULT_E	m2mb_crypto_rsa_keyblob_export (M2MB_CRYPTO_RSA_CONTEXT ctx, UINT8 *keyblob, UINT32 *keyblob_length)
	Exports an RSA key pair blob from the given context. The blob is encrypted with a device specific key and can only be used on the same HW originating it. More...
M2MB_RESULT_E	m2mb_crypto_rsa_keyblob_import (M2MB_CRYPTO_RSA_CONTEXT ctx, const UINT8 *keyblob, UINT32 keyblob_length)
	Imports an RSA key pair into the context. More...
M2MB_RESULT_E	m2mb_crypto_rsa_public_key_export (M2MB_CRYPTO_RSA_CONTEXT ctx, UINT8 *modulus, UINT32 *modulus_size, UINT8 *public_exponent, UINT32 *public_exponent_size)
	Exports an RSA public key from the given context. More...
M2MB_RESULT_E	m2mb_crypto_rsa_public_key_import (M2MB_CRYPTO_RSA_CONTEXT ctx, const UINT8 *modulus, UINT32 modulus_size, const UINT8 *public_exponent, UINT32 public_exponent_size)
	Imports an RSA public key to the given context. More...
M2MB_RESULT_E	m2mb_crypto_rsa_externalkey_import (M2MB_CRYPTO_RSA_CONTEXT ctx, const UINT8 *modulus, UINT32 modulus_size, const UINT8 *p_factor, UINT32 p_factor_size, const UINT8 *q_factor, UINT32 q_factor_size, const UINT8 *public_exponent, UINT32 public_exponent_size, const UINT8 *private_exponent, UINT32 private_exponent_size, M2MB_CRYPTO_RSA_PADDING_TYPE_E padding_type)
	Imports an externally generated RSA key pair into the context. More...
M2MB_RESULT_E	m2mb_crypto_rsa_encrypt (M2MB_CRYPTO_RSA_CONTEXT ctx, M2MB_CRYPTO_RSA_MODE_E mode, SIZE_T inlen, const UINT8 *in, UINT8 *out)
	Generic RSA PKCS#1 encryption method. This function adds the message padding, then performs an RSA operation (encryption). More...
M2MB_RESULT_E	m2mb_crypto_rsa_decrypt (M2MB_CRYPTO_RSA_CONTEXT ctx, M2MB_CRYPTO_RSA_MODE_E mode, SIZE_T *outlen, UINT8 *out, SIZE_T out_max_len, const UINT8 *in)
	Generic RSA PKCS#1 decryption method. This function performs an RSA operation (decryption), then removes the message padding. More...
M2MB_RESULT_E	m2mb_crypto_rsa_sign (M2MB_CRYPTO_RSA_CONTEXT ctx, M2MB_CRYPTO_RSA_MODE_E mode, M2MB_CRYPTO_MD_ALG_E md_alg, UINT32 hashlen, const UINT8 *hash, UINT8 *sig)
	Generic RSA PKCS#1 signature creation method. The signature is created using the context key (created via the m2mb_crypto_rsa_generate_key()). More...
M2MB_RESULT_E	m2mb_crypto_rsa_verify (M2MB_CRYPTO_RSA_CONTEXT ctx, UINT8 *pubkey, UINT32 pubkey_length, M2MB_CRYPTO_MD_ALG_E md_alg, UINT32 hashlen, const UINT8 *hash, const UINT8 *sig)
	Generic RSA PKCS#1 signature verification method. More...

Detailed Description

The RSA public-key cryptosystem.

Enumeration Type Documentation

M2MB_CRYPTO_RSA_PADDING_TYPE_E

enum M2MB_CRYPTO_RSA_PADDING_TYPE_E

Padding types for RSA encryption.

Enumerator
M2MB_CRYPTO_RSA_PADDING_PKCS1_V15	For PKCS version 1.5
M2MB_CRYPTO_RSA_PADDING_PKCS1_OAEP	For PKCS version 2.1 i.e. for OAEP ENCRYPT / DECRYPT function
M2MB_CRYPTO_RSA_PADDING_PKCS1_PSS	For PKCS version 2.1 i.e. for PSS-VERIFY function
M2MB_CRYPTO_RSA_PADDING_PKCS1_PSS_AUTORECOVER_SALTLEN	For PKCS version 2.1 PSS with unknown salt length
M2MB_CRYPTO_RSA_PADDING_NONE	No Padding

Function Documentation

m2mb_crypto_rsa_decrypt()

M2MB_RESULT_E m2mb_crypto_rsa_decrypt	(	M2MB_CRYPTO_RSA_CONTEXT	ctx,
		M2MB_CRYPTO_RSA_MODE_E	mode,
		SIZE_T *	outlen,
		UINT8 *	out,
		SIZE_T	out_max_len,
		const UINT8 *	in
	)

Generic RSA PKCS#1 decryption method. This function performs an RSA operation (decryption), then removes the message padding.

This function decrypts <inlen> bytes from <in> buffer using the public/private key from <ctx> (depending on the <mode> provided) and writes, at most, out_max_len bytes of cyphertext data to <out>. The value inlen cannot be bigger than the modulus size.

Parameters

[in]	ctx	Pointer to a context structure previously allocated by m2mb_crypto_rsa_init().
[in]	mode	M2MB_CRYPTO_RSA_PUBLIC or M2MB_CRYPTO_RSA_PRIVATE
[out]	outlen	The length, in bytes, of the plaintext data put into <out>
[out]	out	The buffer that will hold the resulting plaintext. Must be as large as the RSA modulus size .
[in]	out_max_len	The maximum length of the out buffer
[in]	in	The ciphertext buffer to decrypt. Must be as large as the size of the modulus (eg. 128 bytes if RSA-1024 is used)

Returns

M2MB_RESULT_SUCCESS on success

see M2MB_RESULT_E for different values in case of fail

Note

m2mb_crypto_rsa_init() & m2mb_crypto_rsa_generate_key() must be called before using this function (or keys were imported into the context). There are two RSA encryption schemes: RSAES-PKCS-v1_5 and RSAES-OAEP (PKCS#1 v2.1). Padding M2MB_CRYPTO_RSA_PADDING_PKCS1_V15 and M2MB_CRYPTO_RSA_PADDING_NONE uses RSAES-PKCS-v1_5, all the others paddings use RSAES-OAEP

Example

//see m2mb_crypto_rsa_encrypt example

m2mb_crypto_rsa_deinit()

M2MB_RESULT_E m2mb_crypto_rsa_deinit

(

M2MB_CRYPTO_RSA_CONTEXT

ctx

)

Free an M2MB_CRYPTO_RSA_CONTEXT structure.

This function free a previously allocated RSA context.

Parameters

[in]

ctx

Pointer to a context structure to be free by this function.

Returns

M2MB_RESULT_SUCCESS on success

see M2MB_RESULT_E for different values in case of fail

Note

m2mb_crypto_rsa_encrypt()

M2MB_RESULT_E m2mb_crypto_rsa_encrypt	(	M2MB_CRYPTO_RSA_CONTEXT	ctx,
		M2MB_CRYPTO_RSA_MODE_E	mode,
		SIZE_T	inlen,
		const UINT8 *	in,
		UINT8 *	out
	)

Generic RSA PKCS#1 encryption method. This function adds the message padding, then performs an RSA operation (encryption).

This function encrypts <inlen> bytes from <in> buffer using the public/private key from <ctx> (depending on the <mode> provided>) and writes, at most, <modulus> bytes of cyphertext data to <out>. It is the generic wrapper for performing a PKCS#1 encryption (PKCS#1 v1.5 and PKCS#1 v2.1 padding)

Parameters

[in]	ctx	Pointer to a context structure previously allocated by m2mb_crypto_rsa_init().
[in]	mode	M2MB_CRYPTO_RSA_PUBLIC or M2MB_CRYPTO_RSA_PRIVATE
[in]	inlen	The length, in bytes, of the <in> plaintext buffer
[in]	in	The plaintext buffer to encrypt. This must not be NULL In case of M2MB_CRYPTO_RSA_PADDING_NONE or M2MB_CRYPTO_RSA_PADDING_PKCS1_V15, the plaintext max length must be M-11 octets, where M is the length in bytes of the modulus n. References:https://tools.ietf.org/html/rfc2437#section-7.2.1 In the others cases (PKCS version 2.1), the plaintext max length must be M-2-2hLen octets, where M is the length in bytes of the modulus n and hLen is the length the hash function. References: https://tools.ietf.org/html/rfc2437#section-7.1.1
[out]	out	The buffer that will hold the ciphertext. Must be in the size of RSA modulus size (eg. 128 bytes if RSA-1024 is used).

Returns

M2MB_RESULT_SUCCESS on success

see M2MB_RESULT_E for different values in case of fail

Note

m2mb_crypto_rsa_init() & m2mb_crypto_rsa_generate_key() must be called before using this function (or keys were imported into the context). There are two RSA encryption schemes: RSAES-PKCS-v1_5 and RSAES-OAEP (PKCS#1 v2.1). Padding M2MB_CRYPTO_RSA_PADDING_PKCS1_V15 and M2MB_CRYPTO_RSA_PADDING_NONE uses RSAES-PKCS-v1_5, all the others paddings use RSAES-OAEP

Example

#define RSA_1024_BLOCK_SIZE (SIZE_T)128
#define PUBLIC_EXPONENT     (UINT32)65537
 
void rsa_main( void )
{
  INT32 res;
  M2MB_CRYPTO_RSA_CONTEXT ctx;
  SIZE_T outlen;
 
  CHAR mytext[] = "Hello world, hello sun";
  UINT8 secret[RSA_1024_BLOCK_SIZE] ={0x00};
  CHAR outplain[RSA_1024_BLOCK_SIZE]={0x00};
 
  res = m2mb_crypto_rsa_init( &ctx, M2MB_CRYPTO_RSA_PADDING_NONE, M2MB_CRYPTO_MD_ALG_MD5 );
  if( M2MB_RESULT_SUCCESS != res )
  {
    return;
  }
 
  res = m2mb_crypto_rsa_generate_key(ctx, RSA_1024_MODE, PUBLIC_EXPONENT);
  if( M2MB_RESULT_SUCCESS != res )
  {
    m2mb_crypto_rsa_deinit(ctx);
    return ;
  }
 
  res = m2mb_crypto_rsa_encrypt(ctx, M2MB_CRYPTO_RSA_PUBLIC,  strlen(mytext),(UINT8*) mytext, secret);
  if( M2MB_RESULT_SUCCESS != res )
  {
    m2mb_crypto_rsa_deinit(ctx);
    return ;
  }
 
  res = m2mb_crypto_rsa_decrypt( ctx, M2MB_CRYPTO_RSA_PRIVATE, &outlen, (UINT8*)outplain,
                                 RSA_1024_BLOCK_SIZE, secret);
  if( M2MB_RESULT_SUCCESS != res )
  {
    m2mb_crypto_rsa_deinit(ctx);
    return ;
  }
 
  ...
 
}

m2mb_crypto_rsa_externalkey_import()

M2MB_RESULT_E m2mb_crypto_rsa_externalkey_import	(	M2MB_CRYPTO_RSA_CONTEXT	ctx,
		const UINT8 *	modulus,
		UINT32	modulus_size,
		const UINT8 *	p_factor,
		UINT32	p_factor_size,
		const UINT8 *	q_factor,
		UINT32	q_factor_size,
		const UINT8 *	public_exponent,
		UINT32	public_exponent_size,
		const UINT8 *	private_exponent,
		UINT32	private_exponent_size,
		M2MB_CRYPTO_RSA_PADDING_TYPE_E	padding_type
	)

Imports an externally generated RSA key pair into the context.

m2mb_crypto_rsa_externalkey_import

This function imports a given RSA key pair (which was created by an external implementation) to the provided context. This basically allows using of a keys not created by the m2mb_crypto component.

Parameters

[in]	ctx	Pointer to a context structure previously allocated by m2mb_crypto_rsa_init().
[in]	modulus	RSA modulus
[in]	modulus_size	RSA modulus size in bytes
[in]	p_factor	RSA p factor
[in]	p_factor_size	RSA p factor size in bytes
[in]	q_factor	RSA q factor
[in]	q_factor_size	RSA q factor size in bytes
[in]	public_exponent	RSA public exponent.
[in]	public_exponent_size	RSA public exponent size in bytes
[in]	private_exponent	RSA private exponent.
[in]	private_exponent_size	RSA private exponent size in bytes
[in]	padding_type	Padding type to use.

Returns

M2MB_RESULT_SUCCESS on success

see M2MB_RESULT_E for different values in case of fail

Note

m2mb_crypto_rsa_init() must be called before using this function. A check is made after the import for the consistency of RSA public and RSA private key, but is the responsibility of the user to ensure the trustworthiness of the source of his RSA parameters, which goes beyond what is effectively checkable.

Example

...
 
M2MB_CRYPTO_RSA_CONTEXT ctx;
const uint8_t exponent[] = { 0x01, 0x00, 0x01 };
const uint8_t modulus[] = {
   0xB5, 0x3F, 0xB8, 0x51 ,0x36, 0x8D, 0x7F, 0x4D, 0x3B, 0x71, 0x71, 0x15, 0x60, 0x62, 0x66, 0x61,
    0x4F, 0x1D, 0x7F, 0x2F, 0x78 ,0x23 ,0x99, 0x04,
    0xCE, 0x17, 0x23, 0xAB ,0x39,0x86, 0xBD, 0xA6, 0x4A, 0xC6 ,0x0E, 0xFF ,0x7A,
    0x1F, 0xA5, 0x53, 0xA7, 0x80, 0x86, 0xB6, 0x0B, 0x12, 0x21, 0x18, 0xDE, 0x01, 0xF1, 0xCD ,0xC6, 0x5F,
    0x7D, 0xB4, 0x70, 0xEA, 0x53, 0x0A, 0x79, 0xFA, 0xF5,
    0x23, 0xAB, 0x18, 0x5E, 0x04, 0xCB, 0x9A, 0xEE, 0x93, 0x61,
    0xCC, 0xA1, 0xD1, 0xD2, 0x9E, 0xFD, 0xCB, 0x23, 0x5E, 0x5D, 0x2B, 0x3E, 0x13, 0x14 ,0x1B, 0xA8, 0x0F,
    0x2A, 0xD7, 0xF9, 0x80, 0x12, 0xC6, 0x18, 0x66, 0xE3,
    0xD0, 0x91, 0x93, 0xE5, 0x67, 0xCA, 0xA0, 0x97, 0x84, 0x64 ,0xD7, 0xEA,
    0x0E, 0x54, 0x5F, 0x92, 0xB5, 0x44, 0x3C, 0xA6, 0x94, 0xCE, 0x2A, 0x02, 0x80, 0x64, 0xB7, 0xF7, 0xDD
};
 
const uint8_t p[] = {
    0xED, 0x9B, 0xA7, 0xC2, 0xD7, 0x09, 0x4B, 0x10, 0xFE, 0x63, 0x49, 0x8E, 0x6A,
    0xD0, 0xB6, 0xA6, 0x70, 0x2F, 0xC4, 0x9B,
    0x98, 0x29, 0xCE, 0xC2, 0x2A, 0xB5, 0x04, 0x01, 0x43, 0xC9,
    0x5A, 0x6C ,0xEC, 0x17, 0x2F, 0xF8, 0x18, 0xF3, 0x16, 0x50, 0xFA ,0x9B, 0x02, 0x33,
    0xA4 ,0xCD, 0x64 ,0xA3, 0xA2, 0x19 ,0xB8,
    0x5E, 0x47, 0xCA, 0x99,  0x18, 0xE3, 0x04, 0x7B, 0x81, 0x4E, 0x2B, 0x58, 0xB3
};
 
const uint8_t q[] = {
    0xC3, 0x47, 0x46, 0x6B, 0x6D, 0xAA ,0x58 ,0xE6, 0xC2, 0x07, 0x5A ,0xE5, 0x09, 0x53,
    0xAB ,0x9A, 0x4F, 0x16, 0x73, 0x74, 0x9C, 0x4A, 0xE3, 0x00, 0xC0,
    0xA4, 0xC5, 0x45, 0xC4, 0x62, 0x15, 0x32, 0x06, 0xA0, 0xB5, 0x99, 0x03, 0x4F, 0xF1,
    0x8F ,0x8F, 0x1C, 0x2C, 0x75, 0xCF, 0xC0, 0xB8, 0x20, 0x79, 0x10, 0x2D,
    0xA0, 0x5D, 0x09, 0x45, 0xDE, 0xE5, 0x4D, 0xE2, 0x35, 0x77, 0x94, 0x15 ,0x2F
 
};
 
const uint8_t d[] = {
    0x12, 0x8F, 0x56, 0xD9, 0x82, 0x23, 0x95, 0x30, 0x9C, 0x70, 0xAE,
    0x6A, 0xC8, 0xF6, 0xEA, 0x92, 0xF6, 0x5E, 0x07, 0xE3, 0x1D, 0x83, 0x4F,
    0xAD, 0x0D, 0x49, 0x93, 0x4E, 0x7A, 0x52, 0x90, 0xE3, 0x11, 0x6F, 0x1C, 0xA4, 0x0E, 0xA6,
    0x64, 0xF0, 0x9F, 0x0B, 0x6B, 0x40, 0x02, 0xFC, 0x35, 0x45, 0x6D, 0x9E, 0x77, 0x5B, 0x61,
    0xFF, 0xEF, 0x48, 0x65, 0xF3, 0xA8, 0xD3, 0x3E, 0xD0, 0x72, 0xFF,
    0xAA, 0xB6, 0x84, 0x20, 0x4C, 0xAA, 0x2C, 0x9A, 0xA9, 0x38, 0xF6,
    0x90, 0x0E, 0x4E, 0xB1, 0xD4, 0xC7, 0x11, 0x2D, 0xE3, 0x89, 0xE5, 0x9D, 0x1E, 0x87, 0x1C,
    0x6F, 0xC4, 0x3E, 0xE2, 0x32, 0xDE, 0xD4, 0x5E, 0x0A ,0x0D, 0x07,
    0x7F, 0x63, 0x5F, 0xF1, 0x46, 0xB5, 0x85, 0x0D, 0xEC, 0x10, 0xC8, 0x93,
    0xF9, 0x2A, 0x19, 0x7D, 0x53, 0x66, 0x75, 0x6E, 0xDE, 0xB9, 0x32, 0x28, 0x44, 0x3D, 0x25
 
};
 
 
res = m2mb_crypto_rsa_init( &ctx, M2MB_CRYPTO_RSA_PADDING_NONE, M2MB_CRYPTO_MD_ALG_MD5);
if( M2MB_RESULT_SUCCESS != res )
{
    return;
}
 
res = m2mb_crypto_rsa_externalkey_import( ctx, modulus, sizeof(modulus), p, sizeof(p),
                                          q, sizeof(q), exponent,  sizeof(exponent),
                                          d, sizeof(d), M2MB_CRYPTO_RSA_PADDING_NONE );
if( M2MB_RESULT_SUCCESS != res )
{
  return;
}
 
...

m2mb_crypto_rsa_generate_key()

M2MB_RESULT_E m2mb_crypto_rsa_generate_key	(	M2MB_CRYPTO_RSA_CONTEXT	ctx,
		UINT32	key_size,
		UINT32	public_exponent
	)

Generates an RSA key pair.

This function generates an RSA key pair. The RSA key pair is stored in the context and can be exported via a call to m2mb_crypto_rsa_key_export().

Parameters

[in]	ctx	Pointer to a context structure previously allocated by m2mb_crypto_rsa_init().
[in]	key_size	RSA key length (in bytes).
[in]	public_exponent	The public key exponent This must be odd and greater than 1.

Returns

M2MB_RESULT_SUCCESS on success

see M2MB_RESULT_E for different values in case of fail

Note

m2mb_crypto_rsa_init() must be called before using this function.

m2mb_crypto_rsa_init()

M2MB_RESULT_E m2mb_crypto_rsa_init	(	M2MB_CRYPTO_RSA_CONTEXT *	ctx,
		M2MB_CRYPTO_RSA_PADDING_TYPE_E	padding_type,
		M2MB_CRYPTO_MD_ALG_E	hash_id
	)

Allocates an M2MB_CRYPTO_RSA_CONTEXT structure.

This function allocates an RSA context to be later used by any RSA function.

Parameters

[in]	ctx	Pointer to a context structure to be allocated by this function. Any consecutive call to RSA function must use this context.
[in]	padding_type	Padding type to use.
[in]	hash_id	The index of hash algorithm used for generating signature. There are also two RSA encryption schemes with padding: RSA PKCS-v1.5 and RSA OAEP, the hash_id is needed only for RSA OAEP.

Returns

M2MB_RESULT_SUCCESS on success

see M2MB_RESULT_E for different values in case of fail

Note

For PKCS version 2.1: M2MB_CRYPTO_RSA_PADDING_PKCS1_OAEP is for encryption scheme. M2MB_CRYPTO_RSA_PADDING_PKCS1_PSS and M2MB_CRYPTO_RSA_PADDING_PKCS1_PSS_AUTORECOVER_SALTLEN are used for signature (PSS probabilistic signature scheme) Setting any of the 3 padding type will set the PKCS version 2.1

Setting M2MB_CRYPTO_RSA_PADDING_NONE falls in PKCS#1 v1.5 padding mode when using m2mb_crypto_rsa_encrypt and m2mb_crypto_rsa_decrypt.

To encrypt / decript a buffer without padding, use m2mb_crypto_rsa_public and m2mb_crypto_rsa_private

Example

M2MB_CRYPTO_RSA_CONTEXT ctx;
M2MB_RESULT_E           res;
 
res = m2mb_crypto_rsa_init( &ctx, M2MB_CRYPTO_RSA_PADDING_PKCS1_V15, M2MB_CRYPTO_MD_ALG_MD5);
 
if( M2MB_RESULT_SUCCESS != res )
{
  ....
}

m2mb_crypto_rsa_keyblob_export()

M2MB_RESULT_E m2mb_crypto_rsa_keyblob_export	(	M2MB_CRYPTO_RSA_CONTEXT	ctx,
		UINT8 *	keyblob,
		UINT32 *	keyblob_length
	)

Exports an RSA key pair blob from the given context. The blob is encrypted with a device specific key and can only be used on the same HW originating it.

This function exports an RSA key pair for the given context. Assumption made is that the context already have keys, i.e. keys were created using the m2mb_crypto_rsa_generate_key()

Parameters

[in]	ctx	Pointer to a context structure previously allocated by m2mb_crypto_rsa_init().
[out]	keyblob	The buffer that will hold the result keyblob representing the exported RSA key pair. If keyblob ptr is NULL, this function will return the number of bytes required for the keyblob via the keyblob_length pointer.
[out]	keyblob_length	The length of the RSA key blob

Returns

M2MB_RESULT_SUCCESS on success

see M2MB_RESULT_E for different values in case of fail

Note

The exported keyblob contains the public and the private keys m2mb_crypto_rsa_init() & m2mb_crypto_rsa_generate_key() must be called before using this function.

Example

#define RSA_1024_BLOCK_SIZE (SIZE_T)128
#define PUBLIC_EXPONENT     (UINT32)65537
 
void rsa_main( void )
{
  M2MB_CRYPTO_RSA_CONTEXT ctx1,ctx2;
  INT32 res;
  UINT32 keylen;
  UINT8 *pKey;
 
  res = m2mb_crypto_rsa_init( &ctx1, M2MB_CRYPTO_RSA_PADDING_PKCS1_V15, M2MB_CRYPTO_MD_ALG_MD5 );
 
  if( M2MB_RESULT_SUCCESS != res )
  {
    return;
  }
 
  res = m2mb_crypto_rsa_init( &ctx2, M2MB_CRYPTO_RSA_PADDING_PKCS1_V15, M2MB_CRYPTO_MD_ALG_MD5 );
  if( M2MB_RESULT_SUCCESS != res )
  {
    m2mb_crypto_rsa_deinit(ctx1);
    return;
  }
 
  res = m2mb_crypto_rsa_generate_key(ctx1, RSA_1024_MODE, PUBLIC_EXPONENT);
  if( M2MB_RESULT_SUCCESS != res)
  {
    m2mb_crypto_rsa_deinit(ctx1);
    m2mb_crypto_rsa_deinit(ctx2);
    return;
  }
 
  // get keyblob length
  pKey = NULL;
  keylen=0;
  res = m2mb_crypto_rsa_keyblob_export(ctx1, pKey, &keylen);
  if( M2MB_RESULT_SUCCESS != res)
  {
    m2mb_crypto_rsa_deinit(ctx1);
    m2mb_crypto_rsa_deinit(ctx2);
    return;
  }
 
  // allocate space for keyblob
  pKey = ( UINT8* ) m2mb_os_calloc( keylen * sizeof( UINT8 ) );
 
  if( pKey == NULL )
  {
    m2mb_crypto_rsa_deinit(ctx1);
    m2mb_crypto_rsa_deinit(ctx2);
    return;
  }
 
  // fill the keyblob
  res = m2mb_crypto_rsa_keyblob_export(ctx1, pKey, &keylen);
  if( M2MB_RESULT_SUCCESS != res)
  {
    m2mb_crypto_rsa_deinit(ctx1);
    m2mb_crypto_rsa_deinit(ctx2);
    m2mb_os_free(pKey);
    return;
  }
 
  // import keyblob into ctx2 context
  res = m2mb_crypto_rsa_keyblob_import(ctx2, pKey,keylen);
  if( M2MB_RESULT_SUCCESS != res)
  {
    m2mb_crypto_rsa_deinit(ctx1);
    m2mb_crypto_rsa_deinit(ctx2);
    m2mb_os_free(pKey);
    return;
  }
 
  ...
}

m2mb_crypto_rsa_keyblob_import()

M2MB_RESULT_E m2mb_crypto_rsa_keyblob_import	(	M2MB_CRYPTO_RSA_CONTEXT	ctx,
		const UINT8 *	keyblob,
		UINT32	keyblob_length
	)

Imports an RSA key pair into the context.

This function imports a given keyblob (which was previously created by m2mb_crypto_rsa_generate_key and was exported by m2mb_crypto_rsa_key_export) to the provided context. This basically allows using of an old keys with an existing context. The blob is encrypted with a device specific key and can only be used on the same HW originating it.

Parameters

[in]	ctx	Pointer to a context structure previously allocated by m2mb_crypto_rsa_init().
[in]	keyblob	The keyblob previously exported using m2mb_crypto_rsa_key_export() that will be imported into the given context. These keys can then be used for RSA operations like encrypt, decrypt, sign & verify.
[in]	keyblob_length	The length of the RSA key blob

Returns

M2MB_RESULT_SUCCESS on success

see M2MB_RESULT_E for different values in case of fail

Note

m2mb_crypto_rsa_init() must be called before using this function.

m2mb_crypto_rsa_private()

M2MB_RESULT_E m2mb_crypto_rsa_private	(	M2MB_CRYPTO_RSA_CONTEXT	ctx,
		const UINT8 *	in,
		UINT8 *	out
	)

RSA private key operation.

This function is doing an RSA private key operation. This function does not handle message padding. Generally used to get the original message from the secret produced with m2mb_crypto_rsa_public(...). If instead it used to generate the secret, to get back the original message, RSA public key operation need to be performed. See m2mb_crypto_rsa_public(...)

Parameters

[in]	ctx	Pointer to a context structure previously allocated by m2mb_crypto_rsa_init().
[in]	in	The input buffer. Must be large enough for the RSA operation key that is used (e.g. 128 bytes if RSA-1024 is used)
[out]	out	The output buffer. Must be large enough for the RSA operation key that is used (e.g. 128 bytes if RSA-1024 is used)

Returns

M2MB_RESULT_SUCCESS on success

see M2MB_RESULT_E for different values in case of fail

Note

m2mb_crypto_rsa_init() must be called before using this function.

Example

//see m2mb_crypto_rsa_public example

m2mb_crypto_rsa_public()

M2MB_RESULT_E m2mb_crypto_rsa_public	(	M2MB_CRYPTO_RSA_CONTEXT	ctx,
		const UINT8 *	in,
		UINT8 *	out
	)

RSA public key operation.

This function is doing an RSA public key operation. This function does not handle message padding. Generally used to produce secret from original message. If instead it used to get original message from secret, the secret must have been produced with an RSA private key operation. See m2mb_crypto_rsa_private(...)

Parameters

[in]	ctx	Pointer to a context structure previously allocated by m2mb_crypto_rsa_init().
[in]	in	The input buffer that must be large enough for the RSA operation key that is used (e.g. 128 bytes if RSA-1024 is used).
[out]	out	The output buffer that must be large enough for the RSA operation key that is used (e.g. 128 bytes if RSA-1024 is used).

Returns

M2MB_RESULT_SUCCESS on success

see M2MB_RESULT_E for different values in case of fail

Note

Make sure to set in[0] = 0 or ensure that input is smaller than the public modulus . m2mb_crypto_rsa_init() must be called before using this function. Input and Output buffers must be large enough for the RSA operation key that is used (e.g. 128 bytes if RSA-1024 is used).

Example

#define RSA_1024_BLOCK_SIZE (SIZE_T)128
#define PUBLIC_EXPONENT     (UINT32)65537
void someFunction( )
{
  INT32 res;
  M2MB_CRYPTO_RSA_CONTEXT ctx;
  uint8_t outplain[RSA_1024_BLOCK_SIZE]={0x00};
  uint8_t secret[RSA_1024_BLOCK_SIZE] ={0x00};
  uint8_t plain[RSA_1024_BLOCK_SIZE] = {0x00};
 
  plain[3]=0x6d;
  plain[2]=0x92;
  plain[1]=0x03;
  plain[0]=0;
 
  res = m2mb_crypto_rsa_init( &ctx, M2MB_CRYPTO_RSA_PADDING_PKCS1_V15, M2MB_CRYPTO_MD_ALG_MD5);
  if( M2MB_RESULT_SUCCESS != res )
  {
    return;
  }
 
  res = m2mb_crypto_rsa_generate_key(ctx, RSA_1024_MODE, PUBLIC_EXPONENT);
  if( M2MB_RESULT_SUCCESS != res )
  {
    m2mb_crypto_rsa_deinit(ctx);
    return;
  }
 
   res = m2mb_crypto_rsa_public(ctx, plain, secret);
  if( M2MB_RESULT_SUCCESS != res)
  {
    m2mb_crypto_rsa_deinit(ctx);
    return;
  }
 
  res = m2mb_crypto_rsa_private(ctx, secret, outplain);
  if( M2MB_RESULT_SUCCESS != res)
  {
    m2mb_crypto_rsa_deinit(ctx);
    return;
  }
 
  res = memcmp(plain,outplain,sizeof(plain));
 
  res = m2mb_crypto_rsa_deinit(ctx);
  ...
}

m2mb_crypto_rsa_public_key_export()

M2MB_RESULT_E m2mb_crypto_rsa_public_key_export	(	M2MB_CRYPTO_RSA_CONTEXT	ctx,
		UINT8 *	modulus,
		UINT32 *	modulus_size,
		UINT8 *	public_exponent,
		UINT32 *	public_exponent_size
	)

Exports an RSA public key from the given context.

This function exports an RSA public key exponent and modulus for the given context. The RSA public key information will be exported from the given context (assuming context has keys associated).

Parameters

[in]	ctx	Pointer to a context structure previously allocated by m2mb_crypto_rsa_init().
[out]	modulus	RSA modulus. If modulus ptr is NULL, this function will return the number of bytes required for the modulus via the modulus_size pointer.
[out]	modulus_size	RSA modulus size
[out]	public_exponent	RSA public exponent. If public_exponent ptr is NULL, this function will return the number of bytes required for the public_exponent via the public_exponent_size pointer.
[out]	public_exponent_size	RSA public exponent size.

Returns

M2MB_RESULT_SUCCESS on success

see M2MB_RESULT_E for different values in case of fail

Note

m2mb_crypto_rsa_init() & m2mb_crypto_rsa_generate_key() must be called before using this function.

Example

#define RSA_1024_BLOCK_SIZE (SIZE_T)128
#define PUBLIC_EXPONENT     (UINT32)65537
 
void rsa_main( void )
{
  M2MB_CRYPTO_RSA_CONTEXT ctx1,ctx2;
  INT32 res;
  UINT8* pModulus;
  UINT8* pExponent;
  UINT32 modulusSize;
  UINT32 exponentSize;
 
  res = m2mb_crypto_rsa_init(&ctx1, M2MB_CRYPTO_RSA_PADDING_PKCS1_V15, M2MB_CRYPTO_MD_ALG_MD5);
  if( M2MB_RESULT_SUCCESS != res)
  {
    return;
  }
 
  res = m2mb_crypto_rsa_init(&ctx2, M2MB_CRYPTO_RSA_PADDING_PKCS1_V15, M2MB_CRYPTO_MD_ALG_MD5);
  if( M2MB_RESULT_SUCCESS != res)
  {
    m2mb_crypto_rsa_deinit(ctx1);
    return;
  }
 
  res = m2mb_crypto_rsa_generate_key(ctx1, RSA_1024_MODE, PUBLIC_EXPONENT);
  if( M2MB_RESULT_SUCCESS != res)
  {
    goto EXPORT_FREE;
  }
 
  // with modulus and exponent NULL, m2mb_crypto_rsa_public_key_export
  // will return modulus and exponent size
  pModulus = NULL;
  pExponent = NULL;
  res = m2mb_crypto_rsa_public_key_export(ctx1, pModulus, &modulusSize, pExponent, &exponentSize);
  if( M2MB_RESULT_SUCCESS != res)
  {
    goto EXPORT_FREE;
  }
 
  pModulus = (UINT8*) m2mb_os_malloc( modulusSize * sizeof(UINT8));
  pExponent = (UINT8*) m2mb_os_malloc( exponentSize * sizeof(UINT8));
 
  if( ( pModulus == NULL ) || (pExponent == NULL) )
  {
    goto EXPORT_FREE;
  }
 
  res = m2mb_crypto_rsa_public_key_export(ctx1, pModulus, &modulusSize, pExponent, &exponentSize);
  if( M2MB_RESULT_SUCCESS != res)
  {
    goto EXPORT_FREE;
  }
 
  // import in the second context
  res = m2mb_crypto_rsa_public_key_import(ctx2, pModulus, modulusSize, pExponent, exponentSize);
  if( M2MB_RESULT_SUCCESS != res)
  {
    goto EXPORT_FREE;
  }
 
  EXPORT_FREE:
  if( pModulus != NULL)
  {
    m2mb_os_free(pModulus);
  }
  if( pExponent != NULL)
  {
    m2mb_os_free(pExponent);
  }
  m2mb_crypto_rsa_deinit(ctx1);
  m2mb_crypto_rsa_deinit(ctx2);
 
  ...
}

m2mb_crypto_rsa_public_key_import()

M2MB_RESULT_E m2mb_crypto_rsa_public_key_import	(	M2MB_CRYPTO_RSA_CONTEXT	ctx,
		const UINT8 *	modulus,
		UINT32	modulus_size,
		const UINT8 *	public_exponent,
		UINT32	public_exponent_size
	)

Imports an RSA public key to the given context.

This function imports an RSA public key exponent and modulus into the given context. The RSA public key information, i.e. exponent and mudulus will be stored into the provided context.

Parameters

[in]	ctx	Pointer to a context structure previously allocated by m2mb_crypto_rsa_init().
[in]	modulus	RSA modulus. Must not be NULL.
[in]	modulus_size	RSA modulus size, in bytes.
[in]	public_exponent	RSA public exponent. Must not be NULL.
[in]	public_exponent_size	RSA public exponent size, in bytes.

Returns

M2MB_RESULT_SUCCESS on success

see M2MB_RESULT_E for different values in case of fail

Note

m2mb_crypto_rsa_init() must be called before using this function.

Example present in the above m2mb_crypto_rsa_public_key_export

m2mb_crypto_rsa_sign()

M2MB_RESULT_E m2mb_crypto_rsa_sign	(	M2MB_CRYPTO_RSA_CONTEXT	ctx,
		M2MB_CRYPTO_RSA_MODE_E	mode,
		M2MB_CRYPTO_MD_ALG_E	md_alg,
		UINT32	hashlen,
		const UINT8 *	hash,
		UINT8 *	sig
	)

Generic RSA PKCS#1 signature creation method. The signature is created using the context key (created via the m2mb_crypto_rsa_generate_key()).

This function will use the padding setup (done by m2mb_crypto_rsa_init()) and performs a private RSA operation to sign the message digest.

Parameters

[in]	ctx	Pointer to a context structure previously allocated by m2mb_crypto_rsa_init().
[in]	mode	M2MB_CRYPTO_RSA_PUBLIC or M2MB_CRYPTO_RSA_PRIVATE It is deprecated and discouraged to call this function using M2MB_CRYPTO_RSA_PUBLIC mode
[out]	md_alg	The message digest algorithm or M2MB_CRYPTO_MD_NONE for raw data signing.
[out]	hashlen	The length of the provided <hash>, i.e. the message digest length. It is only required when using <md_alg>=M2MB_CRYPTO_MD_NONE and retrieved automatically from the hash algorithm if md_alg is specified.
[in]	hash	The message digest to sign.
[out]	sig	The result ciphertext. The sig buffer must be as large as the size of the modulus. For example len of sig = 128 bytes if RSA-1024 is used.

Returns

M2MB_RESULT_SUCCESS on success

see M2MB_RESULT_E for different values in case of fail

Note

m2mb_crypto_rsa_init() must be called before using this function. Keys were previously created via the m2mb_crypto_rsa_generate_key() (or imported). It is discouraged to call this function using M2MB_CRYPTO_RSA_PUBLIC mode. There are two RSA signature schemes specified in [PKCS1]: RSA-PKCS1-v1_5 (for PKCS#1 v1.5 padding) and RSASSA-PSS ( for and PKCS#1 v2.1 padding)

Example

//see m2mb_crypto_rsa_verify example

m2mb_crypto_rsa_verify()

M2MB_RESULT_E m2mb_crypto_rsa_verify	(	M2MB_CRYPTO_RSA_CONTEXT	ctx,
		UINT8 *	pubkey,
		UINT32	pubkey_length,
		M2MB_CRYPTO_MD_ALG_E	md_alg,
		UINT32	hashlen,
		const UINT8 *	hash,
		const UINT8 *	sig
	)

Generic RSA PKCS#1 signature verification method.

This function will use the padding setup (done by m2mb_crypto_rsa_init()) and will do a public RSA operation to verify the signature and performs a public RSA operation.

Parameters

[in]	ctx	Pointer to a context structure previously initialized by m2mb_crypto_rsa_init().
[in]	pubkey	The public key to use for the verification (plaintext). Today not SUPPORTED: pubkey must be set to NULL and the public key from the current context is used. With pubkey different from NULL an error is provided.
[in]	pubkey_length	The length of the provided public key. Still NOT SUPPORTED: 0 need to be provided.
[out]	md_alg	The message digest algorithm or M2MB_CRYPTO_MD_NONE for raw data verification.
[out]	hashlen	The length of the provided <hash>, i.e. the message digest length. It is only required when using <md_alg>=M2MB_CRYPTO_MD_NONE and retrieved automatically from the hash algorithm if md_alg is specified.
[in]	hash	The message digest to verify it's signature.
[in]	sig	The signature ciphertext to verify against the hash.

Returns

M2MB_RESULT_SUCCESS on success

see M2MB_RESULT_E for different values in case of fail

Note

If an external public key is needed m2mb_crypto_rsa_public_key_import should be used before the m2mb_crypto_rsa_verify. m2mb_crypto_rsa_init() must be called before using this function. Keys were previously created via the m2mb_crypto_rsa_generate_key() (or imported).

Example

#define MD5_IN_LEN             16
#define RSA_1024_MODE  (UINT32)128
 
 void rsa_main( void )
{
  INT32 res;
  M2MB_CRYPTO_RSA_CONTEXT ctx;
  UINT8 md_data[MD5_IN_LEN] ={0xFF,0xAA,0x12,0x34};
  UINT8 out_md[MD5_IN_LEN] ={0x00};
  UINT8 signature[RSA_1024_MODE] ={0x00};
 
  res = m2mb_crypto_rsa_init( &ctx, M2MB_CRYPTO_RSA_PADDING_PKCS1_V15, M2MB_CRYPTO_MD_ALG_MD5);
  if( M2MB_RESULT_SUCCESS != res )
  {
    return;
  }
 
  res = m2mb_crypto_rsa_generate_key(ctx, RSA_1024_MODE, PUBLIC_EXPONENT);
  if( M2MB_RESULT_SUCCESS != res )
  {
    m2mb_crypto_rsa_deinit(ctx);
    return;
  }
 
  if( m2mb_crypto_md(M2MB_CRYPTO_MD_ALG_MD5, md_data, MD5_IN_LEN, out_md) == NULL )
  {
    m2mb_crypto_rsa_deinit(ctx);
    return;
  }
 
  res = m2mb_crypto_rsa_sign( ctx, M2MB_CRYPTO_RSA_PRIVATE, M2MB_CRYPTO_MD_ALG_MD5,
                             MD5_IN_LEN, out_md, signature);
  if( M2MB_RESULT_SUCCESS != res )
  {
    m2mb_crypto_rsa_deinit(ctx);
    return;
  }
 
  res = m2mb_crypto_rsa_verify( ctx, NULL, 0, M2MB_CRYPTO_MD_ALG_MD5, MD5_IN_LEN, out_md, signature);
 
  if( M2MB_RESULT_SUCCESS != res )
  {
    m2mb_crypto_rsa_deinit(ctx);
    return;
  }
 
  ...
 
}