PolarSSL v1.1.4
Data Structures | Defines | Functions
rsa.h File Reference

The RSA public-key cryptosystem. More...

#include "bignum.h"
Include dependency graph for rsa.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  rsa_context
 RSA context structure. More...

Defines

#define POLARSSL_ERR_RSA_BAD_INPUT_DATA   -0x4080
 Bad input parameters to function.
#define POLARSSL_ERR_RSA_INVALID_PADDING   -0x4100
 Input data contains invalid padding and is rejected.
#define POLARSSL_ERR_RSA_KEY_GEN_FAILED   -0x4180
 Something failed during generation of a key.
#define POLARSSL_ERR_RSA_KEY_CHECK_FAILED   -0x4200
 Key failed to pass the libraries validity check.
#define POLARSSL_ERR_RSA_PUBLIC_FAILED   -0x4280
 The public key operation failed.
#define POLARSSL_ERR_RSA_PRIVATE_FAILED   -0x4300
 The private key operation failed.
#define POLARSSL_ERR_RSA_VERIFY_FAILED   -0x4380
 The PKCS#1 verification failed.
#define POLARSSL_ERR_RSA_OUTPUT_TOO_LARGE   -0x4400
 The output buffer for decryption is not large enough.
#define POLARSSL_ERR_RSA_RNG_FAILED   -0x4480
 The random generator failed to generate non-zeros.
#define SIG_RSA_RAW   0
#define SIG_RSA_MD2   2
#define SIG_RSA_MD4   3
#define SIG_RSA_MD5   4
#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
#define RSA_PUBLIC   0
#define RSA_PRIVATE   1
#define RSA_PKCS_V15   0
#define RSA_PKCS_V21   1
#define RSA_SIGN   1
#define RSA_CRYPT   2
#define ASN1_STR_CONSTRUCTED_SEQUENCE   "\x30"
#define ASN1_STR_NULL   "\x05"
#define ASN1_STR_OID   "\x06"
#define ASN1_STR_OCTET_STRING   "\x04"
#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_MEMBER_BODIES   "\x2a"
#define OID_ISO_IDENTIFIED_ORG   "\x2b"
#define OID_COUNTRY_US   "\x86\x48"
#define OID_RSA_DATA_SECURITY   "\x86\xf7\x0d"
#define OID_OIW_SECSIG_SHA1   "\x0e\x03\x02\x1a"
#define ASN1_HASH_MDX
#define ASN1_HASH_SHA1
#define ASN1_HASH_SHA2X

Functions

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

Detailed Description

The RSA public-key cryptosystem.

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.

Definition in file rsa.h.


Define Documentation

#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"              \
)

Definition at line 99 of file rsa.h.

#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"

Definition at line 109 of file rsa.h.

#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"

Definition at line 117 of file rsa.h.

#define ASN1_STR_CONSTRUCTED_SEQUENCE   "\x30"

Definition at line 67 of file rsa.h.

#define ASN1_STR_NULL   "\x05"

Definition at line 68 of file rsa.h.

#define ASN1_STR_OCTET_STRING   "\x04"

Definition at line 70 of file rsa.h.

#define ASN1_STR_OID   "\x06"

Definition at line 69 of file rsa.h.

#define OID_COUNTRY_US   "\x86\x48"

Definition at line 82 of file rsa.h.

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

Definition at line 72 of file rsa.h.

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

Definition at line 73 of file rsa.h.

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

Definition at line 74 of file rsa.h.

#define OID_ISO_IDENTIFIED_ORG   "\x2b"

Definition at line 77 of file rsa.h.

#define OID_ISO_MEMBER_BODIES   "\x2a"

Definition at line 76 of file rsa.h.

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

Definition at line 88 of file rsa.h.

#define OID_RSA_DATA_SECURITY   "\x86\xf7\x0d"

Definition at line 83 of file rsa.h.

#define POLARSSL_ERR_RSA_BAD_INPUT_DATA   -0x4080

Bad input parameters to function.

Definition at line 35 of file rsa.h.

#define POLARSSL_ERR_RSA_INVALID_PADDING   -0x4100

Input data contains invalid padding and is rejected.

Definition at line 36 of file rsa.h.

#define POLARSSL_ERR_RSA_KEY_CHECK_FAILED   -0x4200

Key failed to pass the libraries validity check.

Definition at line 38 of file rsa.h.

#define POLARSSL_ERR_RSA_KEY_GEN_FAILED   -0x4180

Something failed during generation of a key.

Definition at line 37 of file rsa.h.

#define POLARSSL_ERR_RSA_OUTPUT_TOO_LARGE   -0x4400

The output buffer for decryption is not large enough.

Definition at line 42 of file rsa.h.

#define POLARSSL_ERR_RSA_PRIVATE_FAILED   -0x4300

The private key operation failed.

Definition at line 40 of file rsa.h.

#define POLARSSL_ERR_RSA_PUBLIC_FAILED   -0x4280

The public key operation failed.

Definition at line 39 of file rsa.h.

#define POLARSSL_ERR_RSA_RNG_FAILED   -0x4480

The random generator failed to generate non-zeros.

Definition at line 43 of file rsa.h.

#define POLARSSL_ERR_RSA_VERIFY_FAILED   -0x4380

The PKCS#1 verification failed.

Definition at line 41 of file rsa.h.

#define RSA_CRYPT   2

Definition at line 65 of file rsa.h.

#define RSA_PKCS_V15   0

Definition at line 61 of file rsa.h.

#define RSA_PKCS_V21   1

Definition at line 62 of file rsa.h.

#define RSA_PRIVATE   1

Definition at line 59 of file rsa.h.

Referenced by RSA_private_decrypt(), and RSA_private_encrypt().

#define RSA_PUBLIC   0

Definition at line 58 of file rsa.h.

Referenced by RSA_public_decrypt(), and RSA_public_encrypt().

#define RSA_SIGN   1

Definition at line 64 of file rsa.h.

#define SIG_RSA_MD2   2

Definition at line 49 of file rsa.h.

#define SIG_RSA_MD4   3

Definition at line 50 of file rsa.h.

#define SIG_RSA_MD5   4

Definition at line 51 of file rsa.h.

#define SIG_RSA_RAW   0

Definition at line 48 of file rsa.h.

#define SIG_RSA_SHA1   5

Definition at line 52 of file rsa.h.

#define SIG_RSA_SHA224   14

Definition at line 53 of file rsa.h.

#define SIG_RSA_SHA256   11

Definition at line 54 of file rsa.h.

#define SIG_RSA_SHA384   12

Definition at line 55 of file rsa.h.

#define SIG_RSA_SHA512   13

Definition at line 56 of file rsa.h.


Function Documentation

int rsa_check_privkey ( const rsa_context ctx)

Check a private RSA key.

Parameters:
ctxRSA 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:
ctxRSA 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:
ctxRSA Context to free
int rsa_gen_key ( rsa_context ctx,
int(*)(void *, unsigned char *, size_t)  f_rng,
void *  p_rng,
unsigned int  nbits,
int  exponent 
)

Generate an RSA keypair.

Parameters:
ctxRSA context that will hold the key
f_rngRNG function
p_rngRNG parameter
nbitssize of the public key in bits
exponentpublic 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:
ctxRSA context to be initialized
paddingRSA_PKCS_V15 or RSA_PKCS_V21
hash_idRSA_PKCS_V21 hash identifier
Note:
The hash_id parameter is actually ignored when using RSA_PKCS_V15 padding.
int rsa_pkcs1_decrypt ( rsa_context ctx,
int  mode,
size_t *  olen,
const unsigned char *  input,
unsigned char *  output,
size_t  output_max_len 
)

Do an RSA operation, then remove the message padding.

Parameters:
ctxRSA context
modeRSA_PUBLIC or RSA_PRIVATE
olenwill contain the plaintext length
inputbuffer holding the encrypted data
outputbuffer that will hold the plaintext
output_max_lenmaximum 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 *, unsigned char *, size_t)  f_rng,
void *  p_rng,
int  mode,
size_t  ilen,
const unsigned char *  input,
unsigned char *  output 
)

Add the message padding, then do an RSA operation.

Parameters:
ctxRSA context
f_rngRNG function (Needed for padding and PKCS#1 v2.1 encoding)
p_rngRNG parameter
modeRSA_PUBLIC or RSA_PRIVATE
ilencontains the plaintext length
inputbuffer holding the data to be encrypted
outputbuffer 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(*)(void *, unsigned char *, size_t)  f_rng,
void *  p_rng,
int  mode,
int  hash_id,
unsigned int  hashlen,
const unsigned char *  hash,
unsigned char *  sig 
)

Do a private RSA to sign a message digest.

Parameters:
ctxRSA context
f_rngRNG function (Needed for PKCS#1 v2.1 encoding)
p_rngRNG parameter
modeRSA_PUBLIC or RSA_PRIVATE
hash_idSIG_RSA_RAW, SIG_RSA_MD{2,4,5} or SIG_RSA_SHA{1,224,256,384,512}
hashlenmessage digest length (for SIG_RSA_RAW only)
hashbuffer holding the message digest
sigbuffer 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).
In case of PKCS#1 v2.1 encoding keep in mind that the hash_id in the RSA context is the one used for the encoding. hash_id in the function call is the type of hash that is encoded. According to RFC 3447 it is advised to keep both hashes the same.
int rsa_pkcs1_verify ( rsa_context ctx,
int  mode,
int  hash_id,
unsigned int  hashlen,
const unsigned char *  hash,
unsigned char *  sig 
)

Do a public RSA and check the message digest.

Parameters:
ctxpoints to an RSA public key
modeRSA_PUBLIC or RSA_PRIVATE
hash_idSIG_RSA_RAW, SIG_RSA_MD{2,4,5} or SIG_RSA_SHA{1,224,256,384,512}
hashlenmessage digest length (for SIG_RSA_RAW only)
hashbuffer holding the message digest
sigbuffer 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).
In case of PKCS#1 v2.1 encoding keep in mind that the hash_id in the RSA context is the one used for the verification. hash_id in the function call is the type of hash that is verified. According to RFC 3447 it is advised to keep both hashes the same.
int rsa_private ( rsa_context ctx,
const unsigned char *  input,
unsigned char *  output 
)

Do an RSA private key operation.

Parameters:
ctxRSA context
inputinput buffer
outputoutput 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:
ctxRSA context
inputinput buffer
outputoutput 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