rsa.h File Reference

Copyright (C) 2006-2010, Brainspark B.V.

This file is part of PolarSSL (http://www.polarssl.org) Lead Maintainer: Paul Bakker <polarssl_maintainer at polarssl.org>

All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

#include "polarssl/bignum.h"

Data Structures
struct	rsa_context
	RSA context structure. More...

Macros
#define	ASN1_HASH_MDX
#define	ASN1_HASH_SHA1
#define	ASN1_HASH_SHA2X
#define	ASN1_STR_CONSTRUCTED_SEQUENCE   "\x30"
#define	ASN1_STR_NULL   "\x05"
#define	ASN1_STR_OCTET_STRING   "\x04"
#define	ASN1_STR_OID   "\x06"
#define	OID_COUNTRY_US   "\x86\x48"
#define	OID_DIGEST_ALG_MDX   "\x2A\x86\x48\x86\xF7\x0D\x02\x00"
#define	OID_HASH_ALG_SHA1   "\x2b\x0e\x03\x02\x1a"
#define	OID_HASH_ALG_SHA2X   "\x60\x86\x48\x01\x65\x03\x04\x02\x00"
#define	OID_ISO_IDENTIFIED_ORG   "\x2b"
#define	OID_ISO_MEMBER_BODIES   "\x2a"
#define	OID_OIW_SECSIG_SHA1   "\x0e\x03\x02\x1a"
#define	OID_RSA_DATA_SECURITY   "\x86\xf7\x0d"
#define	POLARSSL_ERR_RSA_BAD_INPUT_DATA   -0x0400
#define	POLARSSL_ERR_RSA_INVALID_PADDING   -0x0410
#define	POLARSSL_ERR_RSA_KEY_CHECK_FAILED   -0x0430
#define	POLARSSL_ERR_RSA_KEY_GEN_FAILED   -0x0420
#define	POLARSSL_ERR_RSA_OUTPUT_TOO_LARGE   -0x0470
#define	POLARSSL_ERR_RSA_PRIVATE_FAILED   -0x0450
#define	POLARSSL_ERR_RSA_PUBLIC_FAILED   -0x0440
#define	POLARSSL_ERR_RSA_RNG_FAILED   -0x0480
#define	POLARSSL_ERR_RSA_VERIFY_FAILED   -0x0460
#define	RSA_CRYPT   2
#define	RSA_PKCS_V15   0
#define	RSA_PKCS_V21   1
#define	RSA_PRIVATE   1
#define	RSA_PUBLIC   0
#define	RSA_SIGN   1
#define	SIG_RSA_MD2   2
#define	SIG_RSA_MD4   3
#define	SIG_RSA_MD5   4
#define	SIG_RSA_RAW   0
#define	SIG_RSA_SHA1   5
#define	SIG_RSA_SHA224   14
#define	SIG_RSA_SHA256   11
#define	SIG_RSA_SHA384   12
#define	SIG_RSA_SHA512   13

Functions
int	rsa_check_privkey (const rsa_context *ctx)
	Check a private RSA key. More...
int	rsa_check_pubkey (const rsa_context *ctx)
	Check a public RSA key. More...
void	rsa_free (rsa_context *ctx)
	Free the components of an RSA key. More...
int	rsa_gen_key (rsa_context *ctx, int(*f_rng)(void *), void *p_rng, int nbits, int exponent)
	Generate an RSA keypair. More...
void	rsa_init (rsa_context *ctx, int padding, int hash_id)
	Initialize an RSA context. More...
int	rsa_pkcs1_decrypt (rsa_context *ctx, int mode, int *olen, const unsigned char *input, unsigned char *output, int output_max_len)
	Do an RSA operation, then remove the message padding. More...
int	rsa_pkcs1_encrypt (rsa_context *ctx, int(*f_rng)(void *), void *p_rng, int mode, int ilen, const unsigned char *input, unsigned char *output)
	Add the message padding, then do an RSA operation. More...
int	rsa_pkcs1_sign (rsa_context *ctx, int mode, int hash_id, int hashlen, const unsigned char *hash, unsigned char *sig)
	Do a private RSA to sign a message digest. More...
int	rsa_pkcs1_verify (rsa_context *ctx, int mode, int hash_id, int hashlen, const unsigned char *hash, unsigned char *sig)
	Do a public RSA and check the message digest. More...
int	rsa_private (rsa_context *ctx, const unsigned char *input, unsigned char *output)
	Do an RSA private key operation. More...
int	rsa_public (rsa_context *ctx, const unsigned char *input, unsigned char *output)
	Do an RSA public key operation. More...
int	rsa_self_test (int verbose)
	Checkup routine. More...

#define ASN1_HASH_MDX

Value:

(                                               \
    ASN1_STR_CONSTRUCTED_SEQUENCE "\x20"        \
      ASN1_STR_CONSTRUCTED_SEQUENCE "\x0C"      \
        ASN1_STR_OID "\x08"                     \
	  OID_DIGEST_ALG_MDX				        \
	ASN1_STR_NULL "\x00"                       \
      ASN1_STR_OCTET_STRING "\x10"              \
)

#define ASN1_HASH_SHA1

Value:

ASN1_STR_CONSTRUCTED_SEQUENCE "\x21"        \
      ASN1_STR_CONSTRUCTED_SEQUENCE "\x09"      \
        ASN1_STR_OID "\x05"                     \
	  OID_HASH_ALG_SHA1				            \
        ASN1_STR_NULL "\x00"                    \
      ASN1_STR_OCTET_STRING "\x14"

#define ASN1_HASH_SHA2X

Value:

ASN1_STR_CONSTRUCTED_SEQUENCE "\x11"        \
      ASN1_STR_CONSTRUCTED_SEQUENCE "\x0d"      \
        ASN1_STR_OID "\x09"                     \
	  OID_HASH_ALG_SHA2X				        \
        ASN1_STR_NULL "\x00"                    \
      ASN1_STR_OCTET_STRING "\x00"

#define ASN1_STR_CONSTRUCTED_SEQUENCE   "\x30"

#define ASN1_STR_NULL   "\x05"

#define ASN1_STR_OCTET_STRING   "\x04"

#define ASN1_STR_OID   "\x06"

#define OID_COUNTRY_US   "\x86\x48"

#define OID_DIGEST_ALG_MDX   "\x2A\x86\x48\x86\xF7\x0D\x02\x00"

#define OID_HASH_ALG_SHA1   "\x2b\x0e\x03\x02\x1a"

#define OID_HASH_ALG_SHA2X   "\x60\x86\x48\x01\x65\x03\x04\x02\x00"

#define OID_ISO_IDENTIFIED_ORG   "\x2b"

#define OID_ISO_MEMBER_BODIES   "\x2a"

#define OID_OIW_SECSIG_SHA1   "\x0e\x03\x02\x1a"

#define OID_RSA_DATA_SECURITY   "\x86\xf7\x0d"

#define POLARSSL_ERR_RSA_BAD_INPUT_DATA   -0x0400

#define POLARSSL_ERR_RSA_INVALID_PADDING   -0x0410

#define POLARSSL_ERR_RSA_KEY_CHECK_FAILED   -0x0430

#define POLARSSL_ERR_RSA_KEY_GEN_FAILED   -0x0420

#define POLARSSL_ERR_RSA_OUTPUT_TOO_LARGE   -0x0470

#define POLARSSL_ERR_RSA_PRIVATE_FAILED   -0x0450

#define POLARSSL_ERR_RSA_PUBLIC_FAILED   -0x0440

#define POLARSSL_ERR_RSA_RNG_FAILED   -0x0480

#define POLARSSL_ERR_RSA_VERIFY_FAILED   -0x0460

#define RSA_CRYPT   2

#define RSA_PKCS_V15   0

#define RSA_PKCS_V21   1

#define RSA_PRIVATE   1

Referenced by RSA_private_decrypt(), and RSA_private_encrypt().

#define RSA_PUBLIC   0

Referenced by RSA_public_decrypt(), and RSA_public_encrypt().

#define RSA_SIGN   1

#define SIG_RSA_MD2   2

#define SIG_RSA_MD4   3

#define SIG_RSA_MD5   4

#define SIG_RSA_RAW   0

#define SIG_RSA_SHA1   5

#define SIG_RSA_SHA224   14

#define SIG_RSA_SHA256   11

#define SIG_RSA_SHA384   12

#define SIG_RSA_SHA512   13

int rsa_check_privkey

(

const rsa_context *

ctx

)

Check a private RSA key.

Parameters

ctx	RSA context to be checked

Returns

0 if successful, or an POLARSSL_ERR_RSA_XXX error code

int rsa_check_pubkey

(

const rsa_context *

ctx

)

Check a public RSA key.

Parameters

ctx	RSA context to be checked

Returns

0 if successful, or an POLARSSL_ERR_RSA_XXX error code

void rsa_free

(

rsa_context *

ctx

)

Free the components of an RSA key.

Parameters

ctx	RSA Context to free

int rsa_gen_key	(	rsa_context *	ctx,
		int(*)(void *)	f_rng,
		void *	p_rng,
		int	nbits,
		int	exponent
	)

Generate an RSA keypair.

Parameters

ctx	RSA context that will hold the key
f_rng	RNG function
p_rng	RNG parameter
nbits	size of the public key in bits
exponent	public exponent (e.g., 65537)

Note

rsa_init() must be called beforehand to setup the RSA context.

Returns

0 if successful, or an POLARSSL_ERR_RSA_XXX error code

void rsa_init	(	rsa_context *	ctx,
		int	padding,
		int	hash_id
	)

Initialize an RSA context.

Parameters

ctx	RSA context to be initialized
padding	RSA_PKCS_V15 or RSA_PKCS_V21
hash_id	RSA_PKCS_V21 hash identifier

Note

The hash_id parameter is actually ignored when using RSA_PKCS_V15 padding.

Currently, RSA_PKCS_V21 padding is not supported.

int rsa_pkcs1_decrypt	(	rsa_context *	ctx,
		int	mode,
		int *	olen,
		const unsigned char *	input,
		unsigned char *	output,
		int	output_max_len
	)

Do an RSA operation, then remove the message padding.

Parameters

ctx	RSA context
mode	RSA_PUBLIC or RSA_PRIVATE
input	buffer holding the encrypted data
output	buffer that will hold the plaintext
olen	will contain the plaintext length
output_max_len	maximum length of the output buffer

Returns

0 if successful, or an POLARSSL_ERR_RSA_XXX error code

Note

The output buffer must be as large as the size of ctx->N (eg. 128 bytes if RSA-1024 is used) otherwise an error is thrown.

Referenced by RSA_private_decrypt(), and RSA_public_decrypt().

int rsa_pkcs1_encrypt	(	rsa_context *	ctx,
		int(*)(void *)	f_rng,
		void *	p_rng,
		int	mode,
		int	ilen,
		const unsigned char *	input,
		unsigned char *	output
	)

Add the message padding, then do an RSA operation.

Parameters

ctx	RSA context
f_rng	RNG function
p_rng	RNG parameter
mode	RSA_PUBLIC or RSA_PRIVATE
ilen	contains the plaintext length
input	buffer holding the data to be encrypted
output	buffer that will hold the ciphertext

Returns

0 if successful, or an POLARSSL_ERR_RSA_XXX error code

Note

The output buffer must be as large as the size of ctx->N (eg. 128 bytes if RSA-1024 is used).

Referenced by RSA_private_encrypt(), and RSA_public_encrypt().

int rsa_pkcs1_sign	(	rsa_context *	ctx,
		int	mode,
		int	hash_id,
		int	hashlen,
		const unsigned char *	hash,
		unsigned char *	sig
	)

Do a private RSA to sign a message digest.

Parameters

ctx	RSA context
mode	RSA_PUBLIC or RSA_PRIVATE
hash_id	SIG_RSA_RAW, SIG_RSA_MD{2,4,5} or SIG_RSA_SHA{1,224,256,384,512}
hashlen	message digest length (for SIG_RSA_RAW only)
hash	buffer holding the message digest
sig	buffer that will hold the ciphertext

Returns

0 if the signing operation was successful, or an POLARSSL_ERR_RSA_XXX error code

Note

The "sig" buffer must be as large as the size of ctx->N (eg. 128 bytes if RSA-1024 is used).

int rsa_pkcs1_verify	(	rsa_context *	ctx,
		int	mode,
		int	hash_id,
		int	hashlen,
		const unsigned char *	hash,
		unsigned char *	sig
	)

Do a public RSA and check the message digest.

Parameters

ctx	points to an RSA public key
mode	RSA_PUBLIC or RSA_PRIVATE
hash_id	SIG_RSA_RAW, SIG_RSA_MD{2,4,5} or SIG_RSA_SHA{1,224,256,384,512}
hashlen	message digest length (for SIG_RSA_RAW only)
hash	buffer holding the message digest
sig	buffer holding the ciphertext

Returns

0 if the verify operation was successful, or an POLARSSL_ERR_RSA_XXX error code

Note

The "sig" buffer must be as large as the size of ctx->N (eg. 128 bytes if RSA-1024 is used).

int rsa_private	(	rsa_context *	ctx,
		const unsigned char *	input,
		unsigned char *	output
	)

Do an RSA private key operation.

Parameters

ctx	RSA context
input	input buffer
output	output buffer

Returns

0 if successful, or an POLARSSL_ERR_RSA_XXX error code

Note

The input and output buffers must be large enough (eg. 128 bytes if RSA-1024 is used).

int rsa_public	(	rsa_context *	ctx,
		const unsigned char *	input,
		unsigned char *	output
	)

Do an RSA public key operation.

Parameters

ctx	RSA context
input	input buffer
output	output buffer

Returns

0 if successful, or an POLARSSL_ERR_RSA_XXX error code

Note

This function does NOT take care of message padding. Also, be sure to set input[0] = 0 or assure that input is smaller than N.

The input and output buffers must be large enough (eg. 128 bytes if RSA-1024 is used).

int rsa_self_test

(

int

verbose

)

Checkup routine.

Returns

0 if successful, or 1 if the test failed