~bibledit/bibledit/client

#define MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION -0x4500 /**< The implementation does not offer the requested operation, for example, because of security violations or lack of functionality. */

/* MBEDTLS_ERR_RSA_HW_ACCEL_FAILED is deprecated and should not be used. */

#define MBEDTLS_ERR_RSA_HW_ACCEL_FAILED -0x4580 /**< RSA hardware accelerator failed. */

* RSA constants

#define MBEDTLS_RSA_PUBLIC 0 /**< Request private key operation. */

#define MBEDTLS_RSA_PRIVATE 1 /**< Request public key operation. */

#define MBEDTLS_RSA_PKCS_V15 0 /**< Use PKCS#1 v1.5 encoding. */

#define MBEDTLS_RSA_PKCS_V21 1 /**< Use PKCS#1 v2.1 encoding. */

100

101

#define MBEDTLS_RSA_SIGN 1 /**< Identifier for RSA signature operations. */

102

#define MBEDTLS_RSA_CRYPT 2 /**< Identifier for RSA encryption and decryption operations. */

103

104

#define MBEDTLS_RSA_SALT_LEN_ANY -1

105

106

107

* The above constants may be used even if the RSA module is compile out,

108

* eg for alternative (PKCS#11) RSA implemenations in the PK layers.

109

110

111

#ifdef __cplusplus

112

extern "C" {

113

#endif

114

115

#if !defined(MBEDTLS_RSA_ALT)

116

// Regular implementation

117

118

119

/**

120

* \brief The RSA context structure.

121

122

* \note Direct manipulation of the members of this structure

123

* is deprecated. All manipulation should instead be done through

124

* the public interface functions.

125

126

typedef struct mbedtls_rsa_context

127

{

128

int ver; /*!< Reserved for internal purposes.

129

* Do not set this field in application

130

* code. Its meaning might change without

131

* notice. */

132

size_t len; /*!< The size of \p N in Bytes. */

133

134

mbedtls_mpi N; /*!< The public modulus. */

135

mbedtls_mpi E; /*!< The public exponent. */

136

137

mbedtls_mpi D; /*!< The private exponent. */

138

mbedtls_mpi P; /*!< The first prime factor. */

139

mbedtls_mpi Q; /*!< The second prime factor. */

140

141

mbedtls_mpi DP; /*!< <code>D % (P - 1)</code>. */

142

mbedtls_mpi DQ; /*!< <code>D % (Q - 1)</code>. */

143

mbedtls_mpi QP; /*!< <code>1 / (Q % P)</code>. */

144

145

mbedtls_mpi RN; /*!< cached <code>R^2 mod N</code>. */

146

147

mbedtls_mpi RP; /*!< cached <code>R^2 mod P</code>. */

148

mbedtls_mpi RQ; /*!< cached <code>R^2 mod Q</code>. */

149

150

mbedtls_mpi Vi; /*!< The cached blinding value. */

151

mbedtls_mpi Vf; /*!< The cached un-blinding value. */

152

153

int padding; /*!< Selects padding mode:

154

#MBEDTLS_RSA_PKCS_V15 for 1.5 padding and

155

#MBEDTLS_RSA_PKCS_V21 for OAEP or PSS. */

156

int hash_id; /*!< Hash identifier of mbedtls_md_type_t type,

157

as specified in md.h for use in the MGF

158

mask generating function used in the

159

EME-OAEP and EMSA-PSS encodings. */

160

#if defined(MBEDTLS_THREADING_C)

161

/* Invariant: the mutex is initialized iff ver != 0. */

162

mbedtls_threading_mutex_t mutex; /*!< Thread-safety mutex. */

163

#endif

164

}

165

mbedtls_rsa_context;

166

167

#else /* MBEDTLS_RSA_ALT */

168

#include "rsa_alt.h"

169

#endif /* MBEDTLS_RSA_ALT */

170

171

/**

172

* \brief This function initializes an RSA context.

173

174

* \note Set padding to #MBEDTLS_RSA_PKCS_V21 for the RSAES-OAEP

175

* encryption scheme and the RSASSA-PSS signature scheme.

176

177

* \note The \p hash_id parameter is ignored when using

178

* #MBEDTLS_RSA_PKCS_V15 padding.

179

180

* \note The choice of padding mode is strictly enforced for private key

181

* operations, since there might be security concerns in

182

* mixing padding modes. For public key operations it is

183

* a default value, which can be overridden by calling specific

184

* \c rsa_rsaes_xxx or \c rsa_rsassa_xxx functions.

185

186

* \note The hash selected in \p hash_id is always used for OEAP

187

* encryption. For PSS signatures, it is always used for

188

* making signatures, but can be overridden for verifying them.

189

* If set to #MBEDTLS_MD_NONE, it is always overridden.

190

191

* \param ctx The RSA context to initialize. This must not be \c NULL.

192

* \param padding The padding mode to use. This must be either

193

* #MBEDTLS_RSA_PKCS_V15 or #MBEDTLS_RSA_PKCS_V21.

194

* \param hash_id The hash identifier of ::mbedtls_md_type_t type, if

195

* \p padding is #MBEDTLS_RSA_PKCS_V21. It is unused

196

* otherwise.

197

198

void mbedtls_rsa_init( mbedtls_rsa_context *ctx,

199

int padding,

200

int hash_id );

201

202

/**

203

* \brief This function imports a set of core parameters into an

204

* RSA context.

205

206

* \note This function can be called multiple times for successive

207

* imports, if the parameters are not simultaneously present.

208

209

* Any sequence of calls to this function should be followed

210

* by a call to mbedtls_rsa_complete(), which checks and

211

* completes the provided information to a ready-for-use

212

* public or private RSA key.

213

214

* \note See mbedtls_rsa_complete() for more information on which

215

* parameters are necessary to set up a private or public

216

* RSA key.

217

218

* \note The imported parameters are copied and need not be preserved

219

* for the lifetime of the RSA context being set up.

220

221

* \param ctx The initialized RSA context to store the parameters in.

222

* \param N The RSA modulus. This may be \c NULL.

223

* \param P The first prime factor of \p N. This may be \c NULL.

224

* \param Q The second prime factor of \p N. This may be \c NULL.

225

* \param D The private exponent. This may be \c NULL.

226

* \param E The public exponent. This may be \c NULL.

227

228

* \return \c 0 on success.

229

* \return A non-zero error code on failure.

230

231

int mbedtls_rsa_import( mbedtls_rsa_context *ctx,

232

const mbedtls_mpi *N,

233

const mbedtls_mpi *P, const mbedtls_mpi *Q,

234

const mbedtls_mpi *D, const mbedtls_mpi *E );

235

236

/**

237

* \brief This function imports core RSA parameters, in raw big-endian

238

* binary format, into an RSA context.

239

240

* \note This function can be called multiple times for successive

241

* imports, if the parameters are not simultaneously present.

242

243

* Any sequence of calls to this function should be followed

244

* by a call to mbedtls_rsa_complete(), which checks and

245

* completes the provided information to a ready-for-use

246

* public or private RSA key.

247

248

* \note See mbedtls_rsa_complete() for more information on which

249

* parameters are necessary to set up a private or public

250

* RSA key.

251

252

* \note The imported parameters are copied and need not be preserved

253

* for the lifetime of the RSA context being set up.

254

255

* \param ctx The initialized RSA context to store the parameters in.

256

* \param N The RSA modulus. This may be \c NULL.

257

* \param N_len The Byte length of \p N; it is ignored if \p N == NULL.

258

* \param P The first prime factor of \p N. This may be \c NULL.

259

* \param P_len The Byte length of \p P; it ns ignored if \p P == NULL.

260

* \param Q The second prime factor of \p N. This may be \c NULL.

261

* \param Q_len The Byte length of \p Q; it is ignored if \p Q == NULL.

262

* \param D The private exponent. This may be \c NULL.

263

* \param D_len The Byte length of \p D; it is ignored if \p D == NULL.

264

* \param E The public exponent. This may be \c NULL.

265

* \param E_len The Byte length of \p E; it is ignored if \p E == NULL.

266

267

* \return \c 0 on success.

268

* \return A non-zero error code on failure.

269

270

int mbedtls_rsa_import_raw( mbedtls_rsa_context *ctx,

271

unsigned char const *N, size_t N_len,

272

unsigned char const *P, size_t P_len,

273

unsigned char const *Q, size_t Q_len,

274

unsigned char const *D, size_t D_len,

275

unsigned char const *E, size_t E_len );

276

277

/**

278

* \brief This function completes an RSA context from

279

* a set of imported core parameters.

280

281

* To setup an RSA public key, precisely \p N and \p E

282

* must have been imported.

283

284

* To setup an RSA private key, sufficient information must

285

* be present for the other parameters to be derivable.

286

287

* The default implementation supports the following:

288

* <ul><li>Derive \p P, \p Q from \p N, \p D, \p E.</li>

289

* <li>Derive \p N, \p D from \p P, \p Q, \p E.</li></ul>

290

* Alternative implementations need not support these.

291

292

* If this function runs successfully, it guarantees that

293

* the RSA context can be used for RSA operations without

294

* the risk of failure or crash.

295

296

* \warning This function need not perform consistency checks

297

* for the imported parameters. In particular, parameters that

298

* are not needed by the implementation might be silently

299

* discarded and left unchecked. To check the consistency

300

* of the key material, see mbedtls_rsa_check_privkey().

301

302

* \param ctx The initialized RSA context holding imported parameters.

303

304

* \return \c 0 on success.

305

* \return #MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the attempted derivations

306

* failed.

307

308

309

int mbedtls_rsa_complete( mbedtls_rsa_context *ctx );

310

311

/**

312

* \brief This function exports the core parameters of an RSA key.

313

314

* If this function runs successfully, the non-NULL buffers

315

* pointed to by \p N, \p P, \p Q, \p D, and \p E are fully

316

* written, with additional unused space filled leading by

317

* zero Bytes.

318

319

* Possible reasons for returning

320

* #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED:<ul>

321

* <li>An alternative RSA implementation is in use, which

322

* stores the key externally, and either cannot or should

323

* not export it into RAM.</li>

324

* <li>A SW or HW implementation might not support a certain

325

* deduction. For example, \p P, \p Q from \p N, \p D,

326

* and \p E if the former are not part of the

327

* implementation.</li></ul>

328

329

* If the function fails due to an unsupported operation,

330

* the RSA context stays intact and remains usable.

331

332

* \param ctx The initialized RSA context.

333

* \param N The MPI to hold the RSA modulus.

334

* This may be \c NULL if this field need not be exported.

335

* \param P The MPI to hold the first prime factor of \p N.

336

* This may be \c NULL if this field need not be exported.

337

* \param Q The MPI to hold the second prime factor of \p N.

338

* This may be \c NULL if this field need not be exported.

339

* \param D The MPI to hold the private exponent.

340

* This may be \c NULL if this field need not be exported.

341

* \param E The MPI to hold the public exponent.

342

* This may be \c NULL if this field need not be exported.

343

344

* \return \c 0 on success.

345

* \return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED if exporting the

346

* requested parameters cannot be done due to missing

347

* functionality or because of security policies.

348

* \return A non-zero return code on any other failure.

349

350

351

int mbedtls_rsa_export( const mbedtls_rsa_context *ctx,

352

mbedtls_mpi *N, mbedtls_mpi *P, mbedtls_mpi *Q,

353

mbedtls_mpi *D, mbedtls_mpi *E );

354

355

/**

356

* \brief This function exports core parameters of an RSA key

357

* in raw big-endian binary format.

358

359

* If this function runs successfully, the non-NULL buffers

360

* pointed to by \p N, \p P, \p Q, \p D, and \p E are fully

361

* written, with additional unused space filled leading by

362

* zero Bytes.

363

364

* Possible reasons for returning

365

* #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED:<ul>

366

* <li>An alternative RSA implementation is in use, which

367

* stores the key externally, and either cannot or should

368

* not export it into RAM.</li>

369

* <li>A SW or HW implementation might not support a certain

370

* deduction. For example, \p P, \p Q from \p N, \p D,

371

* and \p E if the former are not part of the

372

* implementation.</li></ul>

373

* If the function fails due to an unsupported operation,

374

* the RSA context stays intact and remains usable.

375

376

* \note The length parameters are ignored if the corresponding

377

* buffer pointers are NULL.

378

379

* \param ctx The initialized RSA context.

380

* \param N The Byte array to store the RSA modulus,

381

* or \c NULL if this field need not be exported.

382

* \param N_len The size of the buffer for the modulus.

383

* \param P The Byte array to hold the first prime factor of \p N,

384

* or \c NULL if this field need not be exported.

385

* \param P_len The size of the buffer for the first prime factor.

386

* \param Q The Byte array to hold the second prime factor of \p N,

387

* or \c NULL if this field need not be exported.

388

* \param Q_len The size of the buffer for the second prime factor.

389

* \param D The Byte array to hold the private exponent,

390

* or \c NULL if this field need not be exported.

391

* \param D_len The size of the buffer for the private exponent.

392

* \param E The Byte array to hold the public exponent,

393

* or \c NULL if this field need not be exported.

394

* \param E_len The size of the buffer for the public exponent.

395

396

* \return \c 0 on success.

397

* \return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED if exporting the

398

* requested parameters cannot be done due to missing

399

* functionality or because of security policies.

400

* \return A non-zero return code on any other failure.

401

402

int mbedtls_rsa_export_raw( const mbedtls_rsa_context *ctx,

403

unsigned char *N, size_t N_len,

404

unsigned char *P, size_t P_len,

405

unsigned char *Q, size_t Q_len,

406

unsigned char *D, size_t D_len,

407

unsigned char *E, size_t E_len );

408

409

/**

410

* \brief This function exports CRT parameters of a private RSA key.

411

412

* \note Alternative RSA implementations not using CRT-parameters

413

* internally can implement this function based on

414

* mbedtls_rsa_deduce_opt().

415

416

* \param ctx The initialized RSA context.

417

* \param DP The MPI to hold \c D modulo `P-1`,

418

* or \c NULL if it need not be exported.

419

* \param DQ The MPI to hold \c D modulo `Q-1`,

420

* or \c NULL if it need not be exported.

421

* \param QP The MPI to hold modular inverse of \c Q modulo \c P,

422

* or \c NULL if it need not be exported.

423

424

* \return \c 0 on success.

425

* \return A non-zero error code on failure.

426

427

428

int mbedtls_rsa_export_crt( const mbedtls_rsa_context *ctx,

429

mbedtls_mpi *DP, mbedtls_mpi *DQ, mbedtls_mpi *QP );

430

431

/**

432

* \brief This function sets padding for an already initialized RSA

433

* context. See mbedtls_rsa_init() for details.

434

435

* \param ctx The initialized RSA context to be configured.

436

* \param padding The padding mode to use. This must be either

437

* #MBEDTLS_RSA_PKCS_V15 or #MBEDTLS_RSA_PKCS_V21.

438

* \param hash_id The #MBEDTLS_RSA_PKCS_V21 hash identifier.

439

440

void mbedtls_rsa_set_padding( mbedtls_rsa_context *ctx, int padding,

441

int hash_id );

442

443

/**

444

* \brief This function retrieves the length of RSA modulus in Bytes.

445

446

* \param ctx The initialized RSA context.

447

448

* \return The length of the RSA modulus in Bytes.

449

450

451

size_t mbedtls_rsa_get_len( const mbedtls_rsa_context *ctx );

452

453

/**

454

* \brief This function generates an RSA keypair.

455

456

* \note mbedtls_rsa_init() must be called before this function,

457

* to set up the RSA context.

458

459

* \param ctx The initialized RSA context used to hold the key.

460

* \param f_rng The RNG function to be used for key generation.

461

* This must not be \c NULL.

462

* \param p_rng The RNG context to be passed to \p f_rng.

463

* This may be \c NULL if \p f_rng doesn't need a context.

464

* \param nbits The size of the public key in bits.

465

* \param exponent The public exponent to use. For example, \c 65537.

466

* This must be odd and greater than \c 1.

467

468

* \return \c 0 on success.

469

* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.

470

471

int mbedtls_rsa_gen_key( mbedtls_rsa_context *ctx,

472

int (*f_rng)(void *, unsigned char *, size_t),

473

void *p_rng,

474

unsigned int nbits, int exponent );

475

476

/**

477

* \brief This function checks if a context contains at least an RSA

478

* public key.

479

480

* If the function runs successfully, it is guaranteed that

481

* enough information is present to perform an RSA public key

482

* operation using mbedtls_rsa_public().

483

484

* \param ctx The initialized RSA context to check.

485

486

* \return \c 0 on success.

487

* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.

488

489

490

int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx );

491

492

/**

493

* \brief This function checks if a context contains an RSA private key

494

* and perform basic consistency checks.

495

496

* \note The consistency checks performed by this function not only

497

* ensure that mbedtls_rsa_private() can be called successfully

498

* on the given context, but that the various parameters are

499

* mutually consistent with high probability, in the sense that

500

* mbedtls_rsa_public() and mbedtls_rsa_private() are inverses.

501

502

* \warning This function should catch accidental misconfigurations

503

* like swapping of parameters, but it cannot establish full

504

* trust in neither the quality nor the consistency of the key

505

* material that was used to setup the given RSA context:

506

* <ul><li>Consistency: Imported parameters that are irrelevant

507

* for the implementation might be silently dropped. If dropped,

508

* the current function does not have access to them,

509

* and therefore cannot check them. See mbedtls_rsa_complete().

510

* If you want to check the consistency of the entire

511

* content of an PKCS1-encoded RSA private key, for example, you

512

* should use mbedtls_rsa_validate_params() before setting

513

* up the RSA context.

514

* Additionally, if the implementation performs empirical checks,

515

* these checks substantiate but do not guarantee consistency.</li>

516

* <li>Quality: This function is not expected to perform

517

* extended quality assessments like checking that the prime

518

* factors are safe. Additionally, it is the responsibility of the

519

* user to ensure the trustworthiness of the source of his RSA

520

* parameters, which goes beyond what is effectively checkable

521

* by the library.</li></ul>

522

523

* \param ctx The initialized RSA context to check.

524

525

* \return \c 0 on success.

526

* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.

527

528

int mbedtls_rsa_check_privkey( const mbedtls_rsa_context *ctx );

529

530

/**

531

* \brief This function checks a public-private RSA key pair.

532

533

* It checks each of the contexts, and makes sure they match.

534

535

* \param pub The initialized RSA context holding the public key.

536

* \param prv The initialized RSA context holding the private key.

537

538

* \return \c 0 on success.

539

* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.

540

541

int mbedtls_rsa_check_pub_priv( const mbedtls_rsa_context *pub,

542

const mbedtls_rsa_context *prv );

543

544

/**

545

* \brief This function performs an RSA public key operation.

546

547

* \param ctx The initialized RSA context to use.

548

* \param input The input buffer. This must be a readable buffer

549

* of length \c ctx->len Bytes. For example, \c 256 Bytes

550

* for an 2048-bit RSA modulus.

551

* \param output The output buffer. This must be a writable buffer

552

* of length \c ctx->len Bytes. For example, \c 256 Bytes

553

* for an 2048-bit RSA modulus.

554

555

* \note This function does not handle message padding.

556

557

* \note Make sure to set \p input[0] = 0 or ensure that

558

* input is smaller than \p N.

559

560

* \return \c 0 on success.

561

* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.

562

563

int mbedtls_rsa_public( mbedtls_rsa_context *ctx,

564

const unsigned char *input,

565

unsigned char *output );

566

567

/**

568

* \brief This function performs an RSA private key operation.

569

570

* \note Blinding is used if and only if a PRNG is provided.

571

572

* \note If blinding is used, both the base of exponentation

573

* and the exponent are blinded, providing protection

574

* against some side-channel attacks.

575

576

* \warning It is deprecated and a security risk to not provide

577

* a PRNG here and thereby prevent the use of blinding.

578

* Future versions of the library may enforce the presence

579

* of a PRNG.

580

581

* \param ctx The initialized RSA context to use.

582

* \param f_rng The RNG function, used for blinding. It is discouraged

583

* and deprecated to pass \c NULL here, in which case

584

* blinding will be omitted.

585

* \param p_rng The RNG context to pass to \p f_rng. This may be \c NULL

586

* if \p f_rng is \c NULL or if \p f_rng doesn't need a context.

587

* \param input The input buffer. This must be a readable buffer

588

* of length \c ctx->len Bytes. For example, \c 256 Bytes

589

* for an 2048-bit RSA modulus.

590

* \param output The output buffer. This must be a writable buffer

591

* of length \c ctx->len Bytes. For example, \c 256 Bytes

592

* for an 2048-bit RSA modulus.

593

594

* \return \c 0 on success.

595

* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.

596

597

598

int mbedtls_rsa_private( mbedtls_rsa_context *ctx,

599

int (*f_rng)(void *, unsigned char *, size_t),

600

void *p_rng,

601

const unsigned char *input,

602

unsigned char *output );

603

604

/**

605

* \brief This function adds the message padding, then performs an RSA

606

* operation.

607

608

* It is the generic wrapper for performing a PKCS#1 encryption

609

* operation using the \p mode from the context.

610

611

* \disabled_deprecated It is deprecated and discouraged to call this function

612

* in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library

613

* are likely to remove the \p mode argument and have it

614

* implicitly set to #MBEDTLS_RSA_PUBLIC.

615

616

* \note Alternative implementations of RSA need not support

617

* mode being set to #MBEDTLS_RSA_PRIVATE and might instead

618

* return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.

619

620

* \param ctx The initialized RSA context to use.

621

* \param f_rng The RNG to use. It is mandatory for PKCS#1 v2.1 padding

622

* encoding, and for PKCS#1 v1.5 padding encoding when used

623

* with \p mode set to #MBEDTLS_RSA_PUBLIC. For PKCS#1 v1.5

624

* padding encoding and \p mode set to #MBEDTLS_RSA_PRIVATE,

625

* it is used for blinding and should be provided in this

626

* case; see mbedtls_rsa_private() for more.

627

* \param p_rng The RNG context to be passed to \p f_rng. May be

628

* \c NULL if \p f_rng is \c NULL or if \p f_rng doesn't

629

* need a context argument.

630

* \param mode The mode of operation. This must be either

631

* #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).

632

* \param ilen The length of the plaintext in Bytes.

633

* \param input The input data to encrypt. This must be a readable

634

* buffer of size \p ilen Bytes. This must not be \c NULL.

635

* \param output The output buffer. This must be a writable buffer

636

* of length \c ctx->len Bytes. For example, \c 256 Bytes

637

* for an 2048-bit RSA modulus.

638

639

* \return \c 0 on success.

640

* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.

641

642

int mbedtls_rsa_pkcs1_encrypt( mbedtls_rsa_context *ctx,

643

int (*f_rng)(void *, unsigned char *, size_t),

644

void *p_rng,

645

int mode, size_t ilen,

646

const unsigned char *input,

647

unsigned char *output );

648

649

/**

650

* \brief This function performs a PKCS#1 v1.5 encryption operation

651

* (RSAES-PKCS1-v1_5-ENCRYPT).

652

653

* \disabled_deprecated It is deprecated and discouraged to call this function

654

* in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library

655

* are likely to remove the \p mode argument and have it

656

* implicitly set to #MBEDTLS_RSA_PUBLIC.

657

658

* \note Alternative implementations of RSA need not support

659

* mode being set to #MBEDTLS_RSA_PRIVATE and might instead

660

* return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.

661

662

* \param ctx The initialized RSA context to use.

663

* \param f_rng The RNG function to use. It is needed for padding generation

664

* if \p mode is #MBEDTLS_RSA_PUBLIC. If \p mode is

665

* #MBEDTLS_RSA_PRIVATE (discouraged), it is used for

666

* blinding and should be provided; see mbedtls_rsa_private().

667

* \param p_rng The RNG context to be passed to \p f_rng. This may

668

* be \c NULL if \p f_rng is \c NULL or if \p f_rng

669

* doesn't need a context argument.

670

* \param mode The mode of operation. This must be either

671

* #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).

672

* \param ilen The length of the plaintext in Bytes.

673

* \param input The input data to encrypt. This must be a readable

674

* buffer of size \p ilen Bytes. This must not be \c NULL.

675

* \param output The output buffer. This must be a writable buffer

676

* of length \c ctx->len Bytes. For example, \c 256 Bytes

677

* for an 2048-bit RSA modulus.

678

679

* \return \c 0 on success.

680

* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.

681

682

int mbedtls_rsa_rsaes_pkcs1_v15_encrypt( mbedtls_rsa_context *ctx,

683

int (*f_rng)(void *, unsigned char *, size_t),

684

void *p_rng,

685

int mode, size_t ilen,

686

const unsigned char *input,

687

unsigned char *output );

688

689

/**

690

* \brief This function performs a PKCS#1 v2.1 OAEP encryption

691

* operation (RSAES-OAEP-ENCRYPT).

692

693

* \note The output buffer must be as large as the size

694

* of ctx->N. For example, 128 Bytes if RSA-1024 is used.

695

696

* \disabled_deprecated It is deprecated and discouraged to call this function

697

* in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library

698

* are likely to remove the \p mode argument and have it

699

* implicitly set to #MBEDTLS_RSA_PUBLIC.

700

701

* \note Alternative implementations of RSA need not support

702

* mode being set to #MBEDTLS_RSA_PRIVATE and might instead

703

* return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.

704

705

* \param ctx The initnialized RSA context to use.

706

* \param f_rng The RNG function to use. This is needed for padding

707

* generation and must be provided.

708

* \param p_rng The RNG context to be passed to \p f_rng. This may

709

* be \c NULL if \p f_rng doesn't need a context argument.

710

* \param mode The mode of operation. This must be either

711

* #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).

712

* \param label The buffer holding the custom label to use.

713

* This must be a readable buffer of length \p label_len

714

* Bytes. It may be \c NULL if \p label_len is \c 0.

715

* \param label_len The length of the label in Bytes.

716

* \param ilen The length of the plaintext buffer \p input in Bytes.

717

* \param input The input data to encrypt. This must be a readable

718

* buffer of size \p ilen Bytes. This must not be \c NULL.

719

* \param output The output buffer. This must be a writable buffer

720

* of length \c ctx->len Bytes. For example, \c 256 Bytes

721

* for an 2048-bit RSA modulus.

722

723

* \return \c 0 on success.

724

* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.

725

726

int mbedtls_rsa_rsaes_oaep_encrypt( mbedtls_rsa_context *ctx,

727

int (*f_rng)(void *, unsigned char *, size_t),

728

void *p_rng,

729

int mode,

730

const unsigned char *label, size_t label_len,

731

size_t ilen,

732

const unsigned char *input,

733

unsigned char *output );

734

735

/**

736

* \brief This function performs an RSA operation, then removes the

737

* message padding.

738

739

* It is the generic wrapper for performing a PKCS#1 decryption

740

* operation using the \p mode from the context.

741

742

* \note The output buffer length \c output_max_len should be

743

* as large as the size \p ctx->len of \p ctx->N (for example,

744

* 128 Bytes if RSA-1024 is used) to be able to hold an

745

* arbitrary decrypted message. If it is not large enough to

746

* hold the decryption of the particular ciphertext provided,

747

* the function returns \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.

748

749

* \disabled_deprecated It is deprecated and discouraged to call this function

750

* in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library

751

* are likely to remove the \p mode argument and have it

752

* implicitly set to #MBEDTLS_RSA_PRIVATE.

753

754

* \note Alternative implementations of RSA need not support

755

* mode being set to #MBEDTLS_RSA_PUBLIC and might instead

756

* return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.

757

758

* \param ctx The initialized RSA context to use.

759

* \param f_rng The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE,

760

* this is used for blinding and should be provided; see

761

* mbedtls_rsa_private() for more. If \p mode is

762

* #MBEDTLS_RSA_PUBLIC, it is ignored.

763

* \param p_rng The RNG context to be passed to \p f_rng. This may be

764

* \c NULL if \p f_rng is \c NULL or doesn't need a context.

765

* \param mode The mode of operation. This must be either

766

* #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).

767

* \param olen The address at which to store the length of

768

* the plaintext. This must not be \c NULL.

769

* \param input The ciphertext buffer. This must be a readable buffer

770

* of length \c ctx->len Bytes. For example, \c 256 Bytes

771

* for an 2048-bit RSA modulus.

772

* \param output The buffer used to hold the plaintext. This must

773

* be a writable buffer of length \p output_max_len Bytes.

774

* \param output_max_len The length in Bytes of the output buffer \p output.

775

776

* \return \c 0 on success.

777

* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.

778

779

int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx,

780

int (*f_rng)(void *, unsigned char *, size_t),

781

void *p_rng,

782

int mode, size_t *olen,

783

const unsigned char *input,

784

unsigned char *output,

785

size_t output_max_len );

786

787

/**

788

* \brief This function performs a PKCS#1 v1.5 decryption

789

* operation (RSAES-PKCS1-v1_5-DECRYPT).

790

791

* \note The output buffer length \c output_max_len should be

792

* as large as the size \p ctx->len of \p ctx->N, for example,

793

* 128 Bytes if RSA-1024 is used, to be able to hold an

794

* arbitrary decrypted message. If it is not large enough to

795

* hold the decryption of the particular ciphertext provided,

796

* the function returns #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.

797

798

* \disabled_deprecated It is deprecated and discouraged to call this function

799

* in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library

800

* are likely to remove the \p mode argument and have it

801

* implicitly set to #MBEDTLS_RSA_PRIVATE.

802

803

* \note Alternative implementations of RSA need not support

804

* mode being set to #MBEDTLS_RSA_PUBLIC and might instead

805

* return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.

806

807

* \param ctx The initialized RSA context to use.

808

* \param f_rng The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE,

809

* this is used for blinding and should be provided; see

810

* mbedtls_rsa_private() for more. If \p mode is

811

* #MBEDTLS_RSA_PUBLIC, it is ignored.

812

* \param p_rng The RNG context to be passed to \p f_rng. This may be

813

* \c NULL if \p f_rng is \c NULL or doesn't need a context.

814

* \param mode The mode of operation. This must be either

815

* #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).

816

* \param olen The address at which to store the length of

817

* the plaintext. This must not be \c NULL.

818

* \param input The ciphertext buffer. This must be a readable buffer

819

* of length \c ctx->len Bytes. For example, \c 256 Bytes

820

* for an 2048-bit RSA modulus.

821

* \param output The buffer used to hold the plaintext. This must

822

* be a writable buffer of length \p output_max_len Bytes.

823

* \param output_max_len The length in Bytes of the output buffer \p output.

824

825

* \return \c 0 on success.

826

* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.

827

828

829

int mbedtls_rsa_rsaes_pkcs1_v15_decrypt( mbedtls_rsa_context *ctx,

830

int (*f_rng)(void *, unsigned char *, size_t),

831

void *p_rng,

832

int mode, size_t *olen,

833

const unsigned char *input,

834

unsigned char *output,

835

size_t output_max_len );

836

837

/**

838

* \brief This function performs a PKCS#1 v2.1 OAEP decryption

839

* operation (RSAES-OAEP-DECRYPT).

840

841

* \note The output buffer length \c output_max_len should be

842

* as large as the size \p ctx->len of \p ctx->N, for

843

* example, 128 Bytes if RSA-1024 is used, to be able to

844

* hold an arbitrary decrypted message. If it is not

845

* large enough to hold the decryption of the particular

846

* ciphertext provided, the function returns

847

* #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.

848

849

* \disabled_deprecated It is deprecated and discouraged to call this function

850

* in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library

851

* are likely to remove the \p mode argument and have it

852

* implicitly set to #MBEDTLS_RSA_PRIVATE.

853

854

* \note Alternative implementations of RSA need not support

855

* mode being set to #MBEDTLS_RSA_PUBLIC and might instead

856

* return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.

857

858

* \param ctx The initialized RSA context to use.

859

* \param f_rng The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE,

860

* this is used for blinding and should be provided; see

861

* mbedtls_rsa_private() for more. If \p mode is

862

* #MBEDTLS_RSA_PUBLIC, it is ignored.

863

* \param p_rng The RNG context to be passed to \p f_rng. This may be

864

* \c NULL if \p f_rng is \c NULL or doesn't need a context.

865

* \param mode The mode of operation. This must be either

866

* #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).

867

* \param label The buffer holding the custom label to use.

868

* This must be a readable buffer of length \p label_len

869

* Bytes. It may be \c NULL if \p label_len is \c 0.

870

* \param label_len The length of the label in Bytes.

871

* \param olen The address at which to store the length of

872

* the plaintext. This must not be \c NULL.

873

* \param input The ciphertext buffer. This must be a readable buffer

874

* of length \c ctx->len Bytes. For example, \c 256 Bytes

875

* for an 2048-bit RSA modulus.

876

* \param output The buffer used to hold the plaintext. This must

877

* be a writable buffer of length \p output_max_len Bytes.

878

* \param output_max_len The length in Bytes of the output buffer \p output.

879

880

* \return \c 0 on success.

881

* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.

882

883

int mbedtls_rsa_rsaes_oaep_decrypt( mbedtls_rsa_context *ctx,

884

int (*f_rng)(void *, unsigned char *, size_t),

885

void *p_rng,

886

int mode,

887

const unsigned char *label, size_t label_len,

888

size_t *olen,

889

const unsigned char *input,

890

unsigned char *output,

891

size_t output_max_len );

892

893

/**

894

* \brief This function performs a private RSA operation to sign

895

* a message digest using PKCS#1.

896

897

* It is the generic wrapper for performing a PKCS#1

898

* signature using the \p mode from the context.

899

900

* \note The \p sig buffer must be as large as the size

901

* of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.

902

903

* \note For PKCS#1 v2.1 encoding, see comments on

904

* mbedtls_rsa_rsassa_pss_sign() for details on

905

* \p md_alg and \p hash_id.

906

907

* \disabled_deprecated It is deprecated and discouraged to call this function

908

* in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library

909

* are likely to remove the \p mode argument and have it

910

* implicitly set to #MBEDTLS_RSA_PRIVATE.

911

912

* \note Alternative implementations of RSA need not support

913

* mode being set to #MBEDTLS_RSA_PUBLIC and might instead

914

* return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.

915

916

* \param ctx The initialized RSA context to use.

917

* \param f_rng The RNG function to use. If the padding mode is PKCS#1 v2.1,

918

* this must be provided. If the padding mode is PKCS#1 v1.5 and

919

* \p mode is #MBEDTLS_RSA_PRIVATE, it is used for blinding

920

* and should be provided; see mbedtls_rsa_private() for more

921

* more. It is ignored otherwise.

922

* \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL

923

* if \p f_rng is \c NULL or doesn't need a context argument.

924

* \param mode The mode of operation. This must be either

925

* #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).

926

* \param md_alg The message-digest algorithm used to hash the original data.

927

* Use #MBEDTLS_MD_NONE for signing raw data.

928

* \param hashlen The length of the message digest.

929

* Ths is only used if \p md_alg is #MBEDTLS_MD_NONE.

930

* \param hash The buffer holding the message digest or raw data.

931

* If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable

932

* buffer of length \p hashlen Bytes. If \p md_alg is not

933

* #MBEDTLS_MD_NONE, it must be a readable buffer of length

934

* the size of the hash corresponding to \p md_alg.

935

* \param sig The buffer to hold the signature. This must be a writable

936

* buffer of length \c ctx->len Bytes. For example, \c 256 Bytes

937

* for an 2048-bit RSA modulus. A buffer length of

938

* #MBEDTLS_MPI_MAX_SIZE is always safe.

939

940

* \return \c 0 if the signing operation was successful.

941

* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.

942

943

int mbedtls_rsa_pkcs1_sign( mbedtls_rsa_context *ctx,

944

int (*f_rng)(void *, unsigned char *, size_t),

945

void *p_rng,

946

int mode,

947

mbedtls_md_type_t md_alg,

948

unsigned int hashlen,

949

const unsigned char *hash,

950

unsigned char *sig );

951

952

/**

953

* \brief This function performs a PKCS#1 v1.5 signature

954

* operation (RSASSA-PKCS1-v1_5-SIGN).

955

956

* \disabled_deprecated It is deprecated and discouraged to call this function

957

* in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library

958

* are likely to remove the \p mode argument and have it

959

* implicitly set to #MBEDTLS_RSA_PRIVATE.

960

961

* \note Alternative implementations of RSA need not support

962

* mode being set to #MBEDTLS_RSA_PUBLIC and might instead

963

* return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.

964

965

* \param ctx The initialized RSA context to use.

966

* \param f_rng The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE,

967

* this is used for blinding and should be provided; see

968

* mbedtls_rsa_private() for more. If \p mode is

969

* #MBEDTLS_RSA_PUBLIC, it is ignored.

970

* \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL

971

* if \p f_rng is \c NULL or doesn't need a context argument.

972

* \param mode The mode of operation. This must be either

973

* #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).

974

* \param md_alg The message-digest algorithm used to hash the original data.

975

* Use #MBEDTLS_MD_NONE for signing raw data.

976

* \param hashlen The length of the message digest.

977

* Ths is only used if \p md_alg is #MBEDTLS_MD_NONE.

978

* \param hash The buffer holding the message digest or raw data.

979

* If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable

980

* buffer of length \p hashlen Bytes. If \p md_alg is not

981

* #MBEDTLS_MD_NONE, it must be a readable buffer of length

982

* the size of the hash corresponding to \p md_alg.

983

* \param sig The buffer to hold the signature. This must be a writable

984

* buffer of length \c ctx->len Bytes. For example, \c 256 Bytes

985

* for an 2048-bit RSA modulus. A buffer length of

986

* #MBEDTLS_MPI_MAX_SIZE is always safe.

987

988

* \return \c 0 if the signing operation was successful.

989

* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.

990

991

int mbedtls_rsa_rsassa_pkcs1_v15_sign( mbedtls_rsa_context *ctx,

992

int (*f_rng)(void *, unsigned char *, size_t),

993

void *p_rng,

994

int mode,

995

mbedtls_md_type_t md_alg,

996

unsigned int hashlen,

997

const unsigned char *hash,

998

unsigned char *sig );

999

1000

/**

1001

* \brief This function performs a PKCS#1 v2.1 PSS signature

1002

* operation (RSASSA-PSS-SIGN).

1003

1004

* \note The \p hash_id in the RSA context is the one used for the

1005

* encoding. \p md_alg in the function call is the type of hash

1006

* that is encoded. According to RFC-3447: Public-Key

1007

* Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography

1008

* Specifications it is advised to keep both hashes the

1009

* same.

1010

1011

* \note This function always uses the maximum possible salt size,

1012

* up to the length of the payload hash. This choice of salt

1013

* size complies with FIPS 186-4 §5.5 (e) and RFC 8017 (PKCS#1

1014

* v2.2) §9.1.1 step 3. Furthermore this function enforces a

1015

* minimum salt size which is the hash size minus 2 bytes. If

1016

* this minimum size is too large given the key size (the salt

1017

* size, plus the hash size, plus 2 bytes must be no more than

1018

* the key size in bytes), this function returns

1019

* #MBEDTLS_ERR_RSA_BAD_INPUT_DATA.

1020

1021

* \disabled_deprecated It is deprecated and discouraged to call this function

1022

* in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library

1023

* are likely to remove the \p mode argument and have it

1024

* implicitly set to #MBEDTLS_RSA_PRIVATE.

1025

1026

* \note Alternative implementations of RSA need not support

1027

* mode being set to #MBEDTLS_RSA_PUBLIC and might instead

1028

* return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.

1029

1030

* \param ctx The initialized RSA context to use.

1031

* \param f_rng The RNG function. It must not be \c NULL.

1032

* \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL

1033

* if \p f_rng doesn't need a context argument.

1034

* \param mode The mode of operation. This must be either

1035

* #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).

1036

* \param md_alg The message-digest algorithm used to hash the original data.

1037

* Use #MBEDTLS_MD_NONE for signing raw data.

1038

* \param hashlen The length of the message digest.

1039

* Ths is only used if \p md_alg is #MBEDTLS_MD_NONE.

1040

* \param hash The buffer holding the message digest or raw data.

1041

* If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable

1042

* buffer of length \p hashlen Bytes. If \p md_alg is not

1043

* #MBEDTLS_MD_NONE, it must be a readable buffer of length

1044

* the size of the hash corresponding to \p md_alg.

1045

* \param sig The buffer to hold the signature. This must be a writable

1046

* buffer of length \c ctx->len Bytes. For example, \c 256 Bytes

1047

* for an 2048-bit RSA modulus. A buffer length of

1048

* #MBEDTLS_MPI_MAX_SIZE is always safe.

1049

1050

* \return \c 0 if the signing operation was successful.

1051

* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.

1052

1053

int mbedtls_rsa_rsassa_pss_sign( mbedtls_rsa_context *ctx,

1054

int (*f_rng)(void *, unsigned char *, size_t),

1055

void *p_rng,

1056

int mode,

1057

mbedtls_md_type_t md_alg,

1058

unsigned int hashlen,

1059

const unsigned char *hash,

1060

unsigned char *sig );

1061

1062

/**

1063

* \brief This function performs a public RSA operation and checks

1064

* the message digest.

1065

1066

* This is the generic wrapper for performing a PKCS#1

1067

* verification using the mode from the context.

1068

1069

* \note For PKCS#1 v2.1 encoding, see comments on

1070

* mbedtls_rsa_rsassa_pss_verify() about \p md_alg and

1071

* \p hash_id.

1072

1073

* \disabled_deprecated It is deprecated and discouraged to call this function

1074

* in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library

1075

* are likely to remove the \p mode argument and have it

1076

* set to #MBEDTLS_RSA_PUBLIC.

1077

1078

* \note Alternative implementations of RSA need not support

1079

* mode being set to #MBEDTLS_RSA_PRIVATE and might instead

1080

* return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.

1081

1082

* \param ctx The initialized RSA public key context to use.

1083

* \param f_rng The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE,

1084

* this is used for blinding and should be provided; see

1085

* mbedtls_rsa_private() for more. Otherwise, it is ignored.

1086

* \param p_rng The RNG context to be passed to \p f_rng. This may be

1087

* \c NULL if \p f_rng is \c NULL or doesn't need a context.

1088

* \param mode The mode of operation. This must be either

1089

* #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).

1090

* \param md_alg The message-digest algorithm used to hash the original data.

1091

* Use #MBEDTLS_MD_NONE for signing raw data.

1092

* \param hashlen The length of the message digest.

1093

* This is only used if \p md_alg is #MBEDTLS_MD_NONE.

1094

* \param hash The buffer holding the message digest or raw data.

1095

* If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable

1096

* buffer of length \p hashlen Bytes. If \p md_alg is not

1097

* #MBEDTLS_MD_NONE, it must be a readable buffer of length

1098

* the size of the hash corresponding to \p md_alg.

1099

* \param sig The buffer holding the signature. This must be a readable

1100

* buffer of length \c ctx->len Bytes. For example, \c 256 Bytes

1101

* for an 2048-bit RSA modulus.

1102

1103

* \return \c 0 if the verify operation was successful.

1104

* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.

1105

1106

int mbedtls_rsa_pkcs1_verify( mbedtls_rsa_context *ctx,

1107

int (*f_rng)(void *, unsigned char *, size_t),

1108

void *p_rng,

1109

int mode,

1110

mbedtls_md_type_t md_alg,

1111

unsigned int hashlen,

1112

const unsigned char *hash,

1113

const unsigned char *sig );

1114

1115

/**

1116

* \brief This function performs a PKCS#1 v1.5 verification

1117

* operation (RSASSA-PKCS1-v1_5-VERIFY).

1118

1119

* \disabled_deprecated It is deprecated and discouraged to call this function

1120

* in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library

1121

* are likely to remove the \p mode argument and have it

1122

* set to #MBEDTLS_RSA_PUBLIC.

1123

1124

* \note Alternative implementations of RSA need not support

1125

* mode being set to #MBEDTLS_RSA_PRIVATE and might instead

1126

* return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.

1127

1128

* \param ctx The initialized RSA public key context to use.

1129

* \param f_rng The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE,

1130

* this is used for blinding and should be provided; see

1131

* mbedtls_rsa_private() for more. Otherwise, it is ignored.

1132

* \param p_rng The RNG context to be passed to \p f_rng. This may be

1133

* \c NULL if \p f_rng is \c NULL or doesn't need a context.

1134

* \param mode The mode of operation. This must be either

1135

* #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).

1136

* \param md_alg The message-digest algorithm used to hash the original data.

1137

* Use #MBEDTLS_MD_NONE for signing raw data.

1138

* \param hashlen The length of the message digest.

1139

* This is only used if \p md_alg is #MBEDTLS_MD_NONE.

1140

* \param hash The buffer holding the message digest or raw data.

1141

* If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable

1142

* buffer of length \p hashlen Bytes. If \p md_alg is not

1143

* #MBEDTLS_MD_NONE, it must be a readable buffer of length

1144

* the size of the hash corresponding to \p md_alg.

1145

* \param sig The buffer holding the signature. This must be a readable

1146

* buffer of length \c ctx->len Bytes. For example, \c 256 Bytes

1147

* for an 2048-bit RSA modulus.

1148

1149

* \return \c 0 if the verify operation was successful.

1150

* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.

1151

1152

int mbedtls_rsa_rsassa_pkcs1_v15_verify( mbedtls_rsa_context *ctx,

1153

int (*f_rng)(void *, unsigned char *, size_t),

1154

void *p_rng,

1155

int mode,

1156

mbedtls_md_type_t md_alg,

1157

unsigned int hashlen,

1158

const unsigned char *hash,

1159

const unsigned char *sig );

1160

1161

/**

1162

* \brief This function performs a PKCS#1 v2.1 PSS verification

1163

* operation (RSASSA-PSS-VERIFY).

1164

1165

* The hash function for the MGF mask generating function

1166

* is that specified in the RSA context.

1167

1168

* \note The \p hash_id in the RSA context is the one used for the

1169

* verification. \p md_alg in the function call is the type of

1170

* hash that is verified. According to RFC-3447: Public-Key

1171

* Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography

1172

* Specifications it is advised to keep both hashes the

1173

* same. If \p hash_id in the RSA context is unset,

1174

* the \p md_alg from the function call is used.

1175

1176

* \disabled_deprecated It is deprecated and discouraged to call this function

1177

* in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library

1178

* are likely to remove the \p mode argument and have it

1179

* implicitly set to #MBEDTLS_RSA_PUBLIC.

1180

1181

* \note Alternative implementations of RSA need not support

1182

* mode being set to #MBEDTLS_RSA_PRIVATE and might instead

1183

* return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.

1184

1185

* \param ctx The initialized RSA public key context to use.

1186

* \param f_rng The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE,

1187

* this is used for blinding and should be provided; see

1188

* mbedtls_rsa_private() for more. Otherwise, it is ignored.

1189

* \param p_rng The RNG context to be passed to \p f_rng. This may be

1190

* \c NULL if \p f_rng is \c NULL or doesn't need a context.

1191

* \param mode The mode of operation. This must be either

1192

* #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).

1193

* \param md_alg The message-digest algorithm used to hash the original data.

1194

* Use #MBEDTLS_MD_NONE for signing raw data.

1195

* \param hashlen The length of the message digest.

1196

* This is only used if \p md_alg is #MBEDTLS_MD_NONE.

1197

* \param hash The buffer holding the message digest or raw data.

1198

* If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable

1199

* buffer of length \p hashlen Bytes. If \p md_alg is not

1200

* #MBEDTLS_MD_NONE, it must be a readable buffer of length

1201

* the size of the hash corresponding to \p md_alg.

1202

* \param sig The buffer holding the signature. This must be a readable

1203

* buffer of length \c ctx->len Bytes. For example, \c 256 Bytes

1204

* for an 2048-bit RSA modulus.

1205

1206

* \return \c 0 if the verify operation was successful.

1207

* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.

1208

1209

int mbedtls_rsa_rsassa_pss_verify( mbedtls_rsa_context *ctx,

1210

int (*f_rng)(void *, unsigned char *, size_t),

1211

void *p_rng,

1212

int mode,

1213

mbedtls_md_type_t md_alg,

1214

unsigned int hashlen,

1215

const unsigned char *hash,

1216

const unsigned char *sig );

1217

1218

/**

1219

* \brief This function performs a PKCS#1 v2.1 PSS verification

1220

* operation (RSASSA-PSS-VERIFY).

1221

1222

* The hash function for the MGF mask generating function

1223

* is that specified in \p mgf1_hash_id.

1224

1225

* \note The \p sig buffer must be as large as the size

1226

* of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.

1227

1228

* \note The \p hash_id in the RSA context is ignored.

1229

1230

* \param ctx The initialized RSA public key context to use.

1231

* \param f_rng The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE,

1232

* this is used for blinding and should be provided; see

1233

* mbedtls_rsa_private() for more. Otherwise, it is ignored.

1234

* \param p_rng The RNG context to be passed to \p f_rng. This may be

1235

* \c NULL if \p f_rng is \c NULL or doesn't need a context.

1236

* \param mode The mode of operation. This must be either

1237

* #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.

1238

* \param md_alg The message-digest algorithm used to hash the original data.

1239

* Use #MBEDTLS_MD_NONE for signing raw data.

1240

* \param hashlen The length of the message digest.

1241

* This is only used if \p md_alg is #MBEDTLS_MD_NONE.

1242

* \param hash The buffer holding the message digest or raw data.

1243

* If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable

1244

* buffer of length \p hashlen Bytes. If \p md_alg is not

1245

* #MBEDTLS_MD_NONE, it must be a readable buffer of length

1246

* the size of the hash corresponding to \p md_alg.

1247

* \param mgf1_hash_id The message digest used for mask generation.

1248

* \param expected_salt_len The length of the salt used in padding. Use

1249

* #MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length.

1250

* \param sig The buffer holding the signature. This must be a readable

1251

* buffer of length \c ctx->len Bytes. For example, \c 256 Bytes

1252

* for an 2048-bit RSA modulus.

1253

1254

* \return \c 0 if the verify operation was successful.

1255

* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.

1256

1257

int mbedtls_rsa_rsassa_pss_verify_ext( mbedtls_rsa_context *ctx,

1258

int (*f_rng)(void *, unsigned char *, size_t),

1259

void *p_rng,

1260

int mode,

1261

mbedtls_md_type_t md_alg,

1262

unsigned int hashlen,

1263

const unsigned char *hash,

1264

mbedtls_md_type_t mgf1_hash_id,

1265

int expected_salt_len,

1266

const unsigned char *sig );

1267

1268

/**

1269

* \brief This function copies the components of an RSA context.

1270

1271

* \param dst The destination context. This must be initialized.

1272

* \param src The source context. This must be initialized.

1273

1274

* \return \c 0 on success.

1275

* \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure.

1276

1277

int mbedtls_rsa_copy( mbedtls_rsa_context *dst, const mbedtls_rsa_context *src );

1278

1279

/**

1280

* \brief This function frees the components of an RSA key.

1281

1282

* \param ctx The RSA context to free. May be \c NULL, in which case

1283

* this function is a no-op. If it is not \c NULL, it must

1284

* point to an initialized RSA context.

1285

1286

void mbedtls_rsa_free( mbedtls_rsa_context *ctx );

1287

1288

#if defined(MBEDTLS_SELF_TEST)

1289

1290

/**

1291

* \brief The RSA checkup routine.

1292

1293

* \return \c 0 on success.

1294

* \return \c 1 on failure.

1295

1296

int mbedtls_rsa_self_test( int verbose );

1297

1298

#endif /* MBEDTLS_SELF_TEST */

1299

1300

#ifdef __cplusplus

1301

}

1302

#endif

1303

1304

#endif /* rsa.h */

Older »