include/tropicssl/rsa.h

   1 /**
   2  * \file rsa.h
   3  *
   4  *  Based on XySSL: Copyright (C) 2006-2008  Christophe Devine
   5  *
   6  *  Copyright (C) 2009  Paul Bakker <polarssl_maintainer at polarssl dot org>
   7  *
   8  *  All rights reserved.
   9  *
  10  *  Redistribution and use in source and binary forms, with or without
  11  *  modification, are permitted provided that the following conditions
  12  *  are met:
  13  *
  14  *    * Redistributions of source code must retain the above copyright
  15  *      notice, this list of conditions and the following disclaimer.
  16  *    * Redistributions in binary form must reproduce the above copyright
  17  *      notice, this list of conditions and the following disclaimer in the
  18  *      documentation and/or other materials provided with the distribution.
  19  *    * Neither the names of PolarSSL or XySSL nor the names of its contributors
  20  *      may be used to endorse or promote products derived from this software
  21  *      without specific prior written permission.
  22  *
  23  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  24  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  25  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  26  *  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  27  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  28  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
  29  *  TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  30  *  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  31  *  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  32  *  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  33  *  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  34  */
  35 #ifndef TROPICSSL_RSA_H
  36 #define TROPICSSL_RSA_H
  37
  38 #include "tropicssl/bignum.h"
  39
  40 #define TROPICSSL_ERR_RSA_BAD_INPUT_DATA                    -0x0400
  41 #define TROPICSSL_ERR_RSA_INVALID_PADDING                   -0x0410
  42 #define TROPICSSL_ERR_RSA_KEY_GEN_FAILED                    -0x0420
  43 #define TROPICSSL_ERR_RSA_KEY_CHECK_FAILED                  -0x0430
  44 #define TROPICSSL_ERR_RSA_PUBLIC_FAILED                     -0x0440
  45 #define TROPICSSL_ERR_RSA_PRIVATE_FAILED                    -0x0450
  46 #define TROPICSSL_ERR_RSA_VERIFY_FAILED                     -0x0460
  47 #define TROPICSSL_ERR_RSA_OUTPUT_TO_LARGE                   -0x0470
  48
  49 /*
  50  * PKCS#1 constants
  51  */
  52 #define RSA_RAW         0
  53 #define RSA_MD2         2
  54 #define RSA_MD4         3
  55 #define RSA_MD5         4
  56 #define RSA_SHA1        5
  57 #define RSA_SHA256      6
  58
  59 #define RSA_PUBLIC      0
  60 #define RSA_PRIVATE     1
  61
  62 #define RSA_PKCS_V15    0
  63 #define RSA_PKCS_V21    1
  64
  65 #define RSA_SIGN        1
  66 #define RSA_CRYPT       2
  67
  68 /*
  69  * DigestInfo ::= SEQUENCE {
  70  *   digestAlgorithm DigestAlgorithmIdentifier,
  71  *   digest Digest }
  72  *
  73  * DigestAlgorithmIdentifier ::= AlgorithmIdentifier
  74  *
  75  * Digest ::= OCTET STRING
  76  */
  77 #define ASN1_HASH_MDX                       \
  78     "\x30\x20\x30\x0C\x06\x08\x2A\x86\x48"  \
  79     "\x86\xF7\x0D\x02\x00\x05\x00\x04\x10"
  80
  81 #define ASN1_HASH_SHA1                      \
  82     "\x30\x21\x30\x09\x06\x05\x2B\x0E\x03"  \
  83     "\x02\x1A\x05\x00\x04\x14"
  84
  85 /**
  86  * \brief          RSA context structure
  87  */
  88 typedef struct {
  89         int ver;                /*!<  always 0          */
  90         int len;                /*!<  size(N) in chars  */
  91
  92         mpi N;                  /*!<  public modulus    */
  93         mpi E;                  /*!<  public exponent   */
  94
  95         mpi D;                  /*!<  private exponent  */
  96         mpi P;                  /*!<  1st prime factor  */
  97         mpi Q;                  /*!<  2nd prime factor  */
  98         mpi DP;                 /*!<  D % (P - 1)       */
  99         mpi DQ;                 /*!<  D % (Q - 1)       */
 100         mpi QP;                 /*!<  1 / (Q % P)       */
 101
 102         mpi RN;                 /*!<  cached R^2 mod N  */
 103         mpi RP;                 /*!<  cached R^2 mod P  */
 104         mpi RQ;                 /*!<  cached R^2 mod Q  */
 105
 106         int padding;            /*!<  1.5 or OAEP/PSS   */
 107         int hash_id;            /*!<  hash identifier   */
 108         int (*f_rng) (void *);  /*!<  RNG function      */
 109         void *p_rng;            /*!<  RNG parameter     */
 110 } rsa_context;
 111
 112 #ifdef __cplusplus
 113 extern "C" {
 114 #endif
 115
 116         /**
 117          * \brief          Initialize an RSA context
 118          *
 119          * \param ctx      RSA context to be initialized
 120          * \param padding  RSA_PKCS_V15 or RSA_PKCS_V21
 121          * \param hash_id  RSA_PKCS_V21 hash identifier
 122          * \param f_rng    RNG function
 123          * \param p_rng    RNG parameter
 124          *
 125          * \note           The hash_id parameter is actually ignored
 126          *                 when using RSA_PKCS_V15 padding.
 127          *
 128          * \note           Currently (xyssl-0.8), RSA_PKCS_V21 padding
 129          *                 is not supported.
 130          */
 131         void rsa_init(rsa_context * ctx,
 132                       int padding,
 133                       int hash_id, int (*f_rng) (void *), void *p_rng);
 134
 135         /**
 136          * \brief          Generate an RSA keypair
 137          *
 138          * \param ctx      RSA context that will hold the key
 139          * \param nbits    size of the public key in bits
 140          * \param exponent public exponent (e.g., 65537)
 141          *
 142          * \note           rsa_init() must be called beforehand to setup
 143          *                 the RSA context (especially f_rng and p_rng).
 144          *
 145          * \return         0 if successful, or an TROPICSSL_ERR_RSA_XXX error code
 146          */
 147         int rsa_gen_key(rsa_context * ctx, int nbits, int exponent);
 148
 149         /**
 150          * \brief          Check a public RSA key
 151          *
 152          * \param ctx      RSA context to be checked
 153          *
 154          * \return         0 if successful, or an TROPICSSL_ERR_RSA_XXX error code
 155          */
 156         int rsa_check_pubkey(const rsa_context * ctx);
 157
 158         /**
 159          * \brief          Check a private RSA key
 160          *
 161          * \param ctx      RSA context to be checked
 162          *
 163          * \return         0 if successful, or an TROPICSSL_ERR_RSA_XXX error code
 164          */
 165         int rsa_check_privkey(const rsa_context * ctx);
 166
 167         /**
 168          * \brief          Do an RSA public key operation
 169          *
 170          * \param ctx      RSA context
 171          * \param input    input buffer
 172          * \param output   output buffer
 173          *
 174          * \return         0 if successful, or an TROPICSSL_ERR_RSA_XXX error code
 175          *
 176          * \note           This function does NOT take care of message
 177          *                 padding. Also, be sure to set input[0] = 0.
 178          *
 179          * \note           The input and output buffers must be large
 180          *                 enough (eg. 128 bytes if RSA-1024 is used).
 181          */
 182         int rsa_public(rsa_context * ctx,
 183                        const unsigned char *input,
 184                        unsigned char *output);
 185
 186         /**
 187          * \brief          Do an RSA private key operation
 188          *
 189          * \param ctx      RSA context
 190          * \param input    input buffer
 191          * \param output   output buffer
 192          *
 193          * \return         0 if successful, or an TROPICSSL_ERR_RSA_XXX error code
 194          *
 195          * \note           The input and output buffers must be large
 196          *                 enough (eg. 128 bytes if RSA-1024 is used).
 197          */
 198         int rsa_private(rsa_context * ctx,
 199                         const unsigned char *input,
 200                         unsigned char *output);
 201
 202         /**
 203          * \brief          Add the message padding, then do an RSA operation
 204          *
 205          * \param ctx      RSA context
 206          * \param mode     RSA_PUBLIC or RSA_PRIVATE
 207          * \param ilen     contains the the plaintext length
 208          * \param input    buffer holding the data to be encrypted
 209          * \param output   buffer that will hold the ciphertext
 210          *
 211          * \return         0 if successful, or an TROPICSSL_ERR_RSA_XXX error code
 212          *
 213          * \note           The output buffer must be as large as the size
 214          *                 of ctx->N (eg. 128 bytes if RSA-1024 is used).
 215          */
 216         int rsa_pkcs1_encrypt(rsa_context * ctx,
 217                               int mode, int ilen,
 218                               const unsigned char *input,
 219                               unsigned char *output);
 220
 221         /**
 222          * \brief          Do an RSA operation, then remove the message padding
 223          *
 224          * \param ctx      RSA context
 225          * \param mode     RSA_PUBLIC or RSA_PRIVATE
 226          * \param input    buffer holding the encrypted data
 227          * \param output   buffer that will hold the plaintext
 228          * \param olen     will contain the plaintext length
 229          * \param output_max_len        maximum length of the output buffer
 230          *
 231          * \return         0 if successful, or an TROPICSSL_ERR_RSA_XXX error code
 232          *
 233          * \note           The output buffer must be as large as the size
 234          *                 of ctx->N (eg. 128 bytes if RSA-1024 is used) otherwise
 235          *                 an error is thrown.
 236          */
 237         int rsa_pkcs1_decrypt(rsa_context * ctx,
 238                               int mode, int *olen,
 239                               const unsigned char *input,
 240                               unsigned char *output,
 241                               int output_max_len);
 242
 243         /**
 244          * \brief          Do a private RSA to sign a message digest
 245          *
 246          * \param ctx      RSA context
 247          * \param mode     RSA_PUBLIC or RSA_PRIVATE
 248          * \param hash_id  RSA_RAW, RSA_MD{2,4,5} or RSA_SHA{1,256}
 249          * \param hashlen  message digest length (for RSA_RAW only)
 250          * \param hash     buffer holding the message digest
 251          * \param sig      buffer that will hold the ciphertext
 252          *
 253          * \return         0 if the signing operation was successful,
 254          *                 or an TROPICSSL_ERR_RSA_XXX error code
 255          *
 256          * \note           The "sig" buffer must be as large as the size
 257          *                 of ctx->N (eg. 128 bytes if RSA-1024 is used).
 258          */
 259         int rsa_pkcs1_sign(rsa_context * ctx,
 260                            int mode,
 261                            int hash_id,
 262                            int hashlen,
 263                            const unsigned char *hash,
 264                            unsigned char *sig);
 265
 266         /**
 267          * \brief          Do a public RSA and check the message digest
 268          *
 269          * \param ctx      points to an RSA public key
 270          * \param mode     RSA_PUBLIC or RSA_PRIVATE
 271          * \param hash_id  RSA_RAW, RSA_MD{2,4,5} or RSA_SHA{1,256}
 272          * \param hashlen  message digest length (for RSA_RAW only)
 273          * \param hash     buffer holding the message digest
 274          * \param sig      buffer holding the ciphertext
 275          *
 276          * \return         0 if the verify operation was successful,
 277          *                 or an TROPICSSL_ERR_RSA_XXX error code
 278          *
 279          * \note           The "sig" buffer must be as large as the size
 280          *                 of ctx->N (eg. 128 bytes if RSA-1024 is used).
 281          */
 282         int rsa_pkcs1_verify(rsa_context * ctx,
 283                              int mode,
 284                              int hash_id,
 285                              int hashlen,
 286                              const unsigned char *hash,
 287                              const unsigned char *sig);
 288
 289         /**
 290          * \brief          Free the components of an RSA key
 291          */
 292         void rsa_free(rsa_context * ctx);
 293
 294         /**
 295          * \brief          Checkup routine
 296          *
 297          * \return         0 if successful, or 1 if the test failed
 298          */
 299         int rsa_self_test(int verbose);
 300
 301 #ifdef __cplusplus
 302 }
 303 #endif
 304 #endif                          /* rsa.h */