# rsa.h File Reference

## Detailed Description

Copyright (C) 2006-2009, Paul Bakker <polarssl_maintainer at polarssl.org> All rights reserved.

Joined copyright on original XySSL code with: Christophe Devine

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.

`#include "polarssl/bignum.h"`

Go to the source code of this file.

## Data Structures
struct | rsa_context
| RSA context structure. More...
## Defines
#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_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 (rsa_context *ctx)
| Check a private RSA key.
int | rsa_check_pubkey (rsa_context *ctx)
| Check a public RSA key.
void | rsa_free (rsa_context *ctx)
| Free the components of an RSA key.
int | rsa_gen_key (rsa_context *ctx, int nbits, int exponent)
| Generate an RSA keypair.
void | rsa_init (rsa_context *ctx, int padding, int hash_id, int(*f_rng)(void *), void *p_rng)
| Initialize an RSA context.
int | rsa_pkcs1_decrypt (rsa_context *ctx, int mode, int *olen, unsigned char *input, unsigned char *output, int output_max_len)
| Do an RSA operation, then remove the message padding.
int | rsa_pkcs1_encrypt (rsa_context *ctx, int mode, int ilen, unsigned char *input, unsigned char *output)
| Add the message padding, then do an RSA operation.
int | rsa_pkcs1_sign (rsa_context *ctx, int mode, int hash_id, int hashlen, 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, int hashlen, unsigned char *hash, unsigned char *sig)
| Do a public RSA and check the message digest.
int | rsa_private (rsa_context *ctx, unsigned char *input, unsigned char *output)
| Do an RSA private key operation.
int | rsa_public (rsa_context *ctx, unsigned char *input, unsigned char *output)
| Do an RSA public key operation.
int | rsa_self_test (int verbose)
| Checkup routine.

## 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 94 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 104 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 112 of file rsa.h.

#define ASN1_STR_CONSTRUCTED_SEQUENCE "\x30"

Definition at line 62 of file rsa.h.

#define ASN1_STR_NULL "\x05"

Definition at line 63 of file rsa.h.

#define ASN1_STR_OCTET_STRING "\x04"

Definition at line 65 of file rsa.h.

#define ASN1_STR_OID "\x06"

Definition at line 64 of file rsa.h.

#define OID_COUNTRY_US "\x86\x48"

Definition at line 77 of file rsa.h.

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

Definition at line 67 of file rsa.h.

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

Definition at line 68 of file rsa.h.

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

Definition at line 69 of file rsa.h.

#define OID_ISO_IDENTIFIED_ORG "\x2b"

Definition at line 72 of file rsa.h.

#define OID_ISO_MEMBER_BODIES "\x2a"

Definition at line 71 of file rsa.h.

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

Definition at line 83 of file rsa.h.

#define OID_RSA_DATA_SECURITY "\x86\xf7\x0d"

Definition at line 78 of file rsa.h.

#define POLARSSL_ERR_RSA_BAD_INPUT_DATA -0x0400

Definition at line 31 of file rsa.h.

#define POLARSSL_ERR_RSA_INVALID_PADDING -0x0410

Definition at line 32 of file rsa.h.

#define POLARSSL_ERR_RSA_KEY_CHECK_FAILED -0x0430

Definition at line 34 of file rsa.h.

#define POLARSSL_ERR_RSA_KEY_GEN_FAILED -0x0420

Definition at line 33 of file rsa.h.

#define POLARSSL_ERR_RSA_OUTPUT_TOO_LARGE -0x0470

Definition at line 38 of file rsa.h.

#define POLARSSL_ERR_RSA_PRIVATE_FAILED -0x0450

Definition at line 36 of file rsa.h.

#define POLARSSL_ERR_RSA_PUBLIC_FAILED -0x0440

Definition at line 35 of file rsa.h.

#define POLARSSL_ERR_RSA_VERIFY_FAILED -0x0460

Definition at line 37 of file rsa.h.

#define RSA_CRYPT 2

Definition at line 60 of file rsa.h.

#define RSA_PKCS_V15 0

Definition at line 56 of file rsa.h.

#define RSA_PKCS_V21 1

Definition at line 57 of file rsa.h.

#define RSA_PRIVATE 1

Definition at line 54 of file rsa.h.

Referenced by RSA_private_decrypt(), and RSA_private_encrypt().

#define RSA_PUBLIC 0

Definition at line 53 of file rsa.h.

Referenced by RSA_public_decrypt(), and RSA_public_encrypt().

#define RSA_SIGN 1

Definition at line 59 of file rsa.h.

#define SIG_RSA_MD2 2

Definition at line 44 of file rsa.h.

#define SIG_RSA_MD4 3

Definition at line 45 of file rsa.h.

#define SIG_RSA_MD5 4

Definition at line 46 of file rsa.h.

#define SIG_RSA_RAW 0

Definition at line 43 of file rsa.h.

#define SIG_RSA_SHA1 5

Definition at line 47 of file rsa.h.

#define SIG_RSA_SHA224 14

Definition at line 48 of file rsa.h.

#define SIG_RSA_SHA256 11

Definition at line 49 of file rsa.h.

#define SIG_RSA_SHA384 12

Definition at line 50 of file rsa.h.

#define SIG_RSA_SHA512 13

Definition at line 51 of file rsa.h.

## Function Documentation

int rsa_check_privkey | ( | 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 | ( | 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 | nbits,
|  | int | exponent |
| ) |  |  |

Generate an RSA keypair.

Parameters:

  | ctx | RSA context that will hold the key
  | 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 (especially f_rng and p_rng).

Returns:
  0 if successful, or an POLARSSL_ERR_RSA_XXX error code

void rsa_init | ( | rsa_context * | ctx,
|  | int | padding,
|  | int | hash_id,
|  | int(*)(void *) | f_rng,
|  | void * | p_rng |
| ) |  |  |

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
  | f_rng | RNG function
  | p_rng | RNG parameter

Note:
  The hash_id parameter is actually ignored when using RSA_PKCS_V15 padding.

  Currently (xyssl-0.8), RSA_PKCS_V21 padding is not supported.

int rsa_pkcs1_decrypt | ( | rsa_context * | ctx,
|  | int | mode,
|  | int * | olen,
|  | 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 | mode,
|  | int | ilen,
|  | unsigned char * | input,
|  | unsigned char * | output |
| ) |  |  |

Add the message padding, then do an RSA operation.

Parameters:

  | ctx | RSA context
  | 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,
|  | 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,
|  | 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, RSA_MD{2,4,5} or RSA_SHA{1,256}
  | 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,
|  | 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,
|  | 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