1 /** 2 * \file rsa.h 3 * 4 * \brief The RSA public-key cryptosystem 5 * 6 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved 7 * SPDX-License-Identifier: Apache-2.0 8 * 9 * Licensed under the Apache License, Version 2.0 (the "License"); you may 10 * not use this file except in compliance with the License. 11 * You may obtain a copy of the License at 12 * 13 * http://www.apache.org/licenses/LICENSE-2.0 14 * 15 * Unless required by applicable law or agreed to in writing, software 16 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 17 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 18 * See the License for the specific language governing permissions and 19 * limitations under the License. 20 * 21 * This file is part of mbed TLS (https://tls.mbed.org) 22 */ 23 #ifndef MBEDTLS_RSA_ALT_H 24 #define MBEDTLS_RSA_ALT_H 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 #include "sec_crypto_rsa.h" 31 32 /** 33 * \brief RSA context structure 34 */ 35 typedef struct { 36 int ver; /*!< always 0 */ 37 size_t len; /*!< size(N) in chars */ 38 39 mbedtls_mpi N; /*!< public modulus */ 40 mbedtls_mpi E; /*!< public exponent */ 41 42 mbedtls_mpi D; /*!< private exponent */ 43 mbedtls_mpi P; /*!< 1st prime factor */ 44 mbedtls_mpi Q; /*!< 2nd prime factor */ 45 mbedtls_mpi DP; /*!< D % (P - 1) */ 46 mbedtls_mpi DQ; /*!< D % (Q - 1) */ 47 mbedtls_mpi QP; /*!< 1 / (Q % P) */ 48 int padding; /*!< MBEDTLS_RSA_PKCS_V15 for 1.5 padding and 49 MBEDTLS_RSA_PKCS_v21 for OAEP/PSS */ 50 int hash_id; /*!< Hash identifier of mbedtls_md_type_t as 51 specified in the mbedtls_md.h header file 52 for the EME-OAEP and EMSA-PSS 53 encoding */ 54 #if defined(CONFIG_TEE_RSA) 55 void *ctx; 56 #endif 57 58 sc_rsa_t sc_rsa; 59 sc_rsa_context_t sc_ctx; 60 } mbedtls_rsa_context; 61 62 /** 63 * \brief Initialize an RSA context 64 * 65 * Note: Set padding to MBEDTLS_RSA_PKCS_V21 for the RSAES-OAEP 66 * encryption scheme and the RSASSA-PSS signature scheme. 67 * 68 * \param ctx RSA context to be initialized 69 * \param padding MBEDTLS_RSA_PKCS_V15 or MBEDTLS_RSA_PKCS_V21 70 * \param hash_id MBEDTLS_RSA_PKCS_V21 hash identifier 71 * 72 * \note The hash_id parameter is actually ignored 73 * when using MBEDTLS_RSA_PKCS_V15 padding. 74 * 75 * \note Choice of padding mode is strictly enforced for private key 76 * operations, since there might be security concerns in 77 * mixing padding modes. For public key operations it's merely 78 * a default value, which can be overriden by calling specific 79 * rsa_rsaes_xxx or rsa_rsassa_xxx functions. 80 * 81 * \note The chosen hash is always used for OEAP encryption. 82 * For PSS signatures, it's always used for making signatures, 83 * but can be overriden (and always is, if set to 84 * MBEDTLS_MD_NONE) for verifying them. 85 */ 86 void mbedtls_rsa_init(mbedtls_rsa_context *ctx, 87 int padding, 88 int hash_id); 89 90 /** 91 * \brief Check a public RSA key 92 * 93 * \param ctx RSA context to be checked 94 * 95 * \return 0 if successful, or an MBEDTLS_ERR_RSA_XXX error code 96 */ 97 int mbedtls_rsa_check_pubkey(const mbedtls_rsa_context *ctx); 98 99 /** 100 * \brief Check a private RSA key 101 * 102 * \param ctx RSA context to be checked 103 * 104 * \return 0 if successful, or an MBEDTLS_ERR_RSA_XXX error code 105 */ 106 int mbedtls_rsa_check_privkey(const mbedtls_rsa_context *ctx); 107 108 /** 109 * \brief Check a public-private RSA key pair. 110 * Check each of the contexts, and make sure they match. 111 * 112 * \param pub RSA context holding the public key 113 * \param prv RSA context holding the private key 114 * 115 * \return 0 if successful, or an MBEDTLS_ERR_RSA_XXX error code 116 */ 117 int mbedtls_rsa_check_pub_priv(const mbedtls_rsa_context *pub, const mbedtls_rsa_context *prv); 118 119 /** 120 * \brief Generic wrapper to perform a PKCS#1 encryption using the 121 * mode from the context. Add the message padding, then do an 122 * RSA operation. 123 * 124 * \param ctx RSA context 125 * \param f_rng RNG function (Needed for padding and PKCS#1 v2.1 encoding 126 * and MBEDTLS_RSA_PRIVATE) 127 * \param p_rng RNG parameter 128 * \param mode MBEDTLS_RSA_PUBLIC or MBEDTLS_RSA_PRIVATE 129 * \param ilen contains the plaintext length 130 * \param input buffer holding the data to be encrypted 131 * \param output buffer that will hold the ciphertext 132 * 133 * \return 0 if successful, or an MBEDTLS_ERR_RSA_XXX error code 134 * 135 * \note The output buffer must be as large as the size 136 * of ctx->N (eg. 128 bytes if RSA-1024 is used). 137 */ 138 int mbedtls_rsa_pkcs1_encrypt(mbedtls_rsa_context *ctx, 139 int (*f_rng)(void *, unsigned char *, size_t), 140 void *p_rng, 141 int mode, size_t ilen, 142 const unsigned char *input, 143 unsigned char *output); 144 145 /** 146 * \brief Generic wrapper to perform a PKCS#1 decryption using the 147 * mode from the context. Do an RSA operation, then remove 148 * the message padding 149 * 150 * \param ctx RSA context 151 * \param f_rng RNG function (Only needed for MBEDTLS_RSA_PRIVATE) 152 * \param p_rng RNG parameter 153 * \param mode MBEDTLS_RSA_PUBLIC or MBEDTLS_RSA_PRIVATE 154 * \param olen will contain the plaintext length 155 * \param input buffer holding the encrypted data 156 * \param output buffer that will hold the plaintext 157 * \param output_max_len maximum length of the output buffer 158 * 159 * \return 0 if successful, or an MBEDTLS_ERR_RSA_XXX error code 160 * 161 * \note The output buffer must be as large as the size 162 * of ctx->N (eg. 128 bytes if RSA-1024 is used) otherwise 163 * an error is thrown. 164 */ 165 int mbedtls_rsa_pkcs1_decrypt(mbedtls_rsa_context *ctx, 166 int (*f_rng)(void *, unsigned char *, size_t), 167 void *p_rng, 168 int mode, size_t *olen, 169 const unsigned char *input, 170 unsigned char *output, 171 size_t output_max_len); 172 173 /** 174 * \brief Generic wrapper to perform a PKCS#1 signature using the 175 * mode from the context. Do a private RSA operation to sign 176 * a message digest 177 * 178 * \param ctx RSA context 179 * \param f_rng RNG function (Needed for PKCS#1 v2.1 encoding and for 180 * MBEDTLS_RSA_PRIVATE) 181 * \param p_rng RNG parameter 182 * \param mode MBEDTLS_RSA_PUBLIC or MBEDTLS_RSA_PRIVATE 183 * \param md_alg a MBEDTLS_MD_XXX (use MBEDTLS_MD_NONE for signing raw data) 184 * \param hashlen message digest length (for MBEDTLS_MD_NONE only) 185 * \param hash buffer holding the message digest 186 * \param sig buffer that will hold the ciphertext 187 * 188 * \return 0 if the signing operation was successful, 189 * or an MBEDTLS_ERR_RSA_XXX error code 190 * 191 * \note The "sig" buffer must be as large as the size 192 * of ctx->N (eg. 128 bytes if RSA-1024 is used). 193 * 194 * \note In case of PKCS#1 v2.1 encoding, see comments on 195 * \note \c mbedtls_rsa_rsassa_pss_sign() for details on md_alg and hash_id. 196 */ 197 int mbedtls_rsa_pkcs1_sign(mbedtls_rsa_context *ctx, 198 int (*f_rng)(void *, unsigned char *, size_t), 199 void *p_rng, 200 int mode, 201 mbedtls_md_type_t md_alg, 202 unsigned int hashlen, 203 const unsigned char *hash, 204 unsigned char *sig); 205 /** 206 * \brief Generic wrapper to perform a PKCS#1 verification using the 207 * mode from the context. Do a public RSA operation and check 208 * the message digest 209 * 210 * \param ctx points to an RSA public key 211 * \param f_rng RNG function (Only needed for MBEDTLS_RSA_PRIVATE) 212 * \param p_rng RNG parameter 213 * \param mode MBEDTLS_RSA_PUBLIC or MBEDTLS_RSA_PRIVATE 214 * \param md_alg a MBEDTLS_MD_XXX (use MBEDTLS_MD_NONE for signing raw data) 215 * \param hashlen message digest length (for MBEDTLS_MD_NONE only) 216 * \param hash buffer holding the message digest 217 * \param sig buffer holding the ciphertext 218 * 219 * \return 0 if the verify operation was successful, 220 * or an MBEDTLS_ERR_RSA_XXX error code 221 * 222 * \note The "sig" buffer must be as large as the size 223 * of ctx->N (eg. 128 bytes if RSA-1024 is used). 224 * 225 * \note In case of PKCS#1 v2.1 encoding, see comments on 226 * \c mbedtls_rsa_rsassa_pss_verify() about md_alg and hash_id. 227 */ 228 int mbedtls_rsa_pkcs1_verify(mbedtls_rsa_context *ctx, 229 int (*f_rng)(void *, unsigned char *, size_t), 230 void *p_rng, 231 int mode, 232 mbedtls_md_type_t md_alg, 233 unsigned int hashlen, 234 const unsigned char *hash, 235 const unsigned char *sig); 236 237 /** 238 * \brief Free the components of an RSA key 239 * 240 * \param ctx RSA Context to free 241 */ 242 void mbedtls_rsa_free(mbedtls_rsa_context *ctx); 243 244 /** 245 * \brief This function retrieves the length of RSA modulus in Bytes. 246 * 247 * \param ctx The initialized RSA context. 248 * 249 * \return The length of the RSA modulus in Bytes. 250 * 251 */ 252 size_t mbedtls_rsa_get_len( const mbedtls_rsa_context *ctx ); 253 254 255 /** 256 * \brief This function imports core RSA parameters, in raw big-endian 257 * binary format, into an RSA context. 258 * 259 * \note This function can be called multiple times for successive 260 * imports, if the parameters are not simultaneously present. 261 * 262 * Any sequence of calls to this function should be followed 263 * by a call to mbedtls_rsa_complete(), which checks and 264 * completes the provided information to a ready-for-use 265 * public or private RSA key. 266 * 267 * \note See mbedtls_rsa_complete() for more information on which 268 * parameters are necessary to set up a private or public 269 * RSA key. 270 * 271 * \note The imported parameters are copied and need not be preserved 272 * for the lifetime of the RSA context being set up. 273 * 274 * \param ctx The initialized RSA context to store the parameters in. 275 * \param N The RSA modulus. This may be \c NULL. 276 * \param N_len The Byte length of \p N; it is ignored if \p N == NULL. 277 * \param P The first prime factor of \p N. This may be \c NULL. 278 * \param P_len The Byte length of \p P; it ns ignored if \p P == NULL. 279 * \param Q The second prime factor of \p N. This may be \c NULL. 280 * \param Q_len The Byte length of \p Q; it is ignored if \p Q == NULL. 281 * \param D The private exponent. This may be \c NULL. 282 * \param D_len The Byte length of \p D; it is ignored if \p D == NULL. 283 * \param E The public exponent. This may be \c NULL. 284 * \param E_len The Byte length of \p E; it is ignored if \p E == NULL. 285 * 286 * \return \c 0 on success. 287 * \return A non-zero error code on failure. 288 */ 289 int mbedtls_rsa_import_raw( mbedtls_rsa_context *ctx, 290 unsigned char const *N, size_t N_len, 291 unsigned char const *P, size_t P_len, 292 unsigned char const *Q, size_t Q_len, 293 unsigned char const *D, size_t D_len, 294 unsigned char const *E, size_t E_len ); 295 296 297 /** 298 * \brief This function completes an RSA context from 299 * a set of imported core parameters. 300 * 301 * To setup an RSA public key, precisely \p N and \p E 302 * must have been imported. 303 * 304 * To setup an RSA private key, sufficient information must 305 * be present for the other parameters to be derivable. 306 * 307 * The default implementation supports the following: 308 * <ul><li>Derive \p P, \p Q from \p N, \p D, \p E.</li> 309 * <li>Derive \p N, \p D from \p P, \p Q, \p E.</li></ul> 310 * Alternative implementations need not support these. 311 * 312 * If this function runs successfully, it guarantees that 313 * the RSA context can be used for RSA operations without 314 * the risk of failure or crash. 315 * 316 * \warning This function need not perform consistency checks 317 * for the imported parameters. In particular, parameters that 318 * are not needed by the implementation might be silently 319 * discarded and left unchecked. To check the consistency 320 * of the key material, see mbedtls_rsa_check_privkey(). 321 * 322 * \param ctx The initialized RSA context holding imported parameters. 323 * 324 * \return \c 0 on success. 325 * \return #MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the attempted derivations 326 * failed. 327 * 328 */ 329 int mbedtls_rsa_complete( mbedtls_rsa_context *ctx ); 330 331 #ifdef __cplusplus 332 } 333 #endif 334 335 #endif /* rsa.h */ 336