Commit 863dfb59 authored by Nathaniel Wesley Filardo's avatar Nathaniel Wesley Filardo Committed by Marcel Stör
Browse files

SSL rampage (#2938)

* Remove stale putative MD2 support

This hasn't worked in a while, presumably since one of our upstream
merges.  Don't bother making it work, since MD2 is generally considered
insecure.

* Land mbedtls 2.16.3-77-gf02988e57

* TLS: remove some dead code from espconn_mbedtls

There was some... frankly kind of scary buffer and data shuffling if
ESP8266_PLATFORM was defined.  Since we don't, in fact, define that
preprocessor symbol, just drop the code lest anyone (possibly future-me)
be scared.

* TLS: espconn_mbedtls: run through astyle

No functional changes

* TLS: espconn_mbedtls: put the file_params on the stack

There's no need to malloc a structure that's used only locally.

* TLS: Further minor tidying of mbedtls glue

What an absolute shitshow this is.  mbedtls should absolutely not
be mentioned inside sys/socket.h and app/mbedtls/app/lwIPSocket.c is not
so much glue as it as a complete copy of a random subset of lwIP; it
should go, but we aren't there yet.

Get rid of the mysterious "mbedlts_record" struct, which housed merely a
length of bytes sent solely for gating the "record sent" callback.

Remove spurious __attribute__((weak)) from symbols not otherwise
defined and rename them to emphasize that they are not actually part of
mbedtls proper.

* TLS: Rampage esp mbedtls glue and delete unused code

This at least makes the shitshow smaller

* TLS: lwip: fix some memp definitions

I presume these also need the new arguments

* TLS: Remove more non-NodeMCU code from our mbedtls

* TLS: drop support for 1.1

Depending on who you ask it's either EOL already or EOL soon, so
we may as well get rid of it now.
parent f5672207
...@@ -37,16 +37,17 @@ ...@@ -37,16 +37,17 @@
#include <stddef.h> #include <stddef.h>
#include <stdint.h> #include <stdint.h>
/* MBEDTLS_ERR_MD5_HW_ACCEL_FAILED is deprecated and should not be used. */
#define MBEDTLS_ERR_MD5_HW_ACCEL_FAILED -0x002F /**< MD5 hardware accelerator failed */ #define MBEDTLS_ERR_MD5_HW_ACCEL_FAILED -0x002F /**< MD5 hardware accelerator failed */
#if !defined(MBEDTLS_MD5_ALT)
// Regular implementation
//
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
#endif #endif
#if !defined(MBEDTLS_MD5_ALT)
// Regular implementation
//
/** /**
* \brief MD5 context structure * \brief MD5 context structure
* *
...@@ -55,7 +56,7 @@ extern "C" { ...@@ -55,7 +56,7 @@ extern "C" {
* stronger message digests instead. * stronger message digests instead.
* *
*/ */
typedef struct typedef struct mbedtls_md5_context
{ {
uint32_t total[2]; /*!< number of bytes processed */ uint32_t total[2]; /*!< number of bytes processed */
uint32_t state[4]; /*!< intermediate digest state */ uint32_t state[4]; /*!< intermediate digest state */
...@@ -63,6 +64,10 @@ typedef struct ...@@ -63,6 +64,10 @@ typedef struct
} }
mbedtls_md5_context; mbedtls_md5_context;
#else /* MBEDTLS_MD5_ALT */
#include "md5_alt.h"
#endif /* MBEDTLS_MD5_ALT */
/** /**
* \brief Initialize MD5 context * \brief Initialize MD5 context
* *
...@@ -238,18 +243,6 @@ MBEDTLS_DEPRECATED void mbedtls_md5_process( mbedtls_md5_context *ctx, ...@@ -238,18 +243,6 @@ MBEDTLS_DEPRECATED void mbedtls_md5_process( mbedtls_md5_context *ctx,
#undef MBEDTLS_DEPRECATED #undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */ #endif /* !MBEDTLS_DEPRECATED_REMOVED */
#ifdef __cplusplus
}
#endif
#else /* MBEDTLS_MD5_ALT */
#include "md5_alt.h"
#endif /* MBEDTLS_MD5_ALT */
#ifdef __cplusplus
extern "C" {
#endif
/** /**
* \brief Output = MD5( input buffer ) * \brief Output = MD5( input buffer )
* *
...@@ -295,6 +288,8 @@ MBEDTLS_DEPRECATED void mbedtls_md5( const unsigned char *input, ...@@ -295,6 +288,8 @@ MBEDTLS_DEPRECATED void mbedtls_md5( const unsigned char *input,
#undef MBEDTLS_DEPRECATED #undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */ #endif /* !MBEDTLS_DEPRECATED_REMOVED */
#if defined(MBEDTLS_SELF_TEST)
/** /**
* \brief Checkup routine * \brief Checkup routine
* *
...@@ -307,6 +302,8 @@ MBEDTLS_DEPRECATED void mbedtls_md5( const unsigned char *input, ...@@ -307,6 +302,8 @@ MBEDTLS_DEPRECATED void mbedtls_md5( const unsigned char *input,
*/ */
int mbedtls_md5_self_test( int verbose ); int mbedtls_md5_self_test( int verbose );
#endif /* MBEDTLS_SELF_TEST */
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif
......
...@@ -23,6 +23,11 @@ ...@@ -23,6 +23,11 @@
* *
* This file is part of mbed TLS (https://tls.mbed.org) * This file is part of mbed TLS (https://tls.mbed.org)
*/ */
#if !defined(MBEDTLS_CONFIG_FILE)
#include "config.h"
#else
#include MBEDTLS_CONFIG_FILE
#endif
#if !defined(MBEDTLS_DEPRECATED_REMOVED) #if !defined(MBEDTLS_DEPRECATED_REMOVED)
#include "net_sockets.h" #include "net_sockets.h"
......
/** /**
* \file net_sockets.h * \file net_sockets.h
* *
* \brief Network communication functions * \brief Network sockets abstraction layer to integrate Mbed TLS into a
* BSD-style sockets API.
*
* The network sockets module provides an example integration of the
* Mbed TLS library into a BSD sockets implementation. The module is
* intended to be an example of how Mbed TLS can be integrated into a
* networking stack, as well as to be Mbed TLS's network integration
* for its supported platforms.
*
* The module is intended only to be used with the Mbed TLS library and
* is not intended to be used by third party application software
* directly.
*
* The supported platforms are as follows:
* * Microsoft Windows and Windows CE
* * POSIX/Unix platforms including Linux, OS X
*
*/ */
/* /*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
...@@ -46,12 +62,17 @@ ...@@ -46,12 +62,17 @@
#define MBEDTLS_ERR_NET_UNKNOWN_HOST -0x0052 /**< Failed to get an IP address for the given hostname. */ #define MBEDTLS_ERR_NET_UNKNOWN_HOST -0x0052 /**< Failed to get an IP address for the given hostname. */
#define MBEDTLS_ERR_NET_BUFFER_TOO_SMALL -0x0043 /**< Buffer is too small to hold the data. */ #define MBEDTLS_ERR_NET_BUFFER_TOO_SMALL -0x0043 /**< Buffer is too small to hold the data. */
#define MBEDTLS_ERR_NET_INVALID_CONTEXT -0x0045 /**< The context is invalid, eg because it was free()ed. */ #define MBEDTLS_ERR_NET_INVALID_CONTEXT -0x0045 /**< The context is invalid, eg because it was free()ed. */
#define MBEDTLS_ERR_NET_POLL_FAILED -0x0047 /**< Polling the net context failed. */
#define MBEDTLS_ERR_NET_BAD_INPUT_DATA -0x0049 /**< Input invalid. */
#define MBEDTLS_NET_LISTEN_BACKLOG 10 /**< The backlog that listen() should use. */ #define MBEDTLS_NET_LISTEN_BACKLOG 10 /**< The backlog that listen() should use. */
#define MBEDTLS_NET_PROTO_TCP 0 /**< The TCP transport protocol */ #define MBEDTLS_NET_PROTO_TCP 0 /**< The TCP transport protocol */
#define MBEDTLS_NET_PROTO_UDP 1 /**< The UDP transport protocol */ #define MBEDTLS_NET_PROTO_UDP 1 /**< The UDP transport protocol */
#define MBEDTLS_NET_POLL_READ 1 /**< Used in \c mbedtls_net_poll to check for pending data */
#define MBEDTLS_NET_POLL_WRITE 2 /**< Used in \c mbedtls_net_poll to check if write possible */
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
#endif #endif
...@@ -63,7 +84,7 @@ extern "C" { ...@@ -63,7 +84,7 @@ extern "C" {
* (eg two file descriptors for combined IPv4 + IPv6 support, or additional * (eg two file descriptors for combined IPv4 + IPv6 support, or additional
* structures for hand-made UDP demultiplexing). * structures for hand-made UDP demultiplexing).
*/ */
typedef struct typedef struct mbedtls_net_context
{ {
int fd; /**< The underlying file descriptor */ int fd; /**< The underlying file descriptor */
} }
...@@ -133,6 +154,29 @@ int mbedtls_net_accept( mbedtls_net_context *bind_ctx, ...@@ -133,6 +154,29 @@ int mbedtls_net_accept( mbedtls_net_context *bind_ctx,
mbedtls_net_context *client_ctx, mbedtls_net_context *client_ctx,
void *client_ip, size_t buf_size, size_t *ip_len ); void *client_ip, size_t buf_size, size_t *ip_len );
/**
* \brief Check and wait for the context to be ready for read/write
*
* \param ctx Socket to check
* \param rw Bitflag composed of MBEDTLS_NET_POLL_READ and
* MBEDTLS_NET_POLL_WRITE specifying the events
* to wait for:
* - If MBEDTLS_NET_POLL_READ is set, the function
* will return as soon as the net context is available
* for reading.
* - If MBEDTLS_NET_POLL_WRITE is set, the function
* will return as soon as the net context is available
* for writing.
* \param timeout Maximal amount of time to wait before returning,
* in milliseconds. If \c timeout is zero, the
* function returns immediately. If \c timeout is
* -1u, the function blocks potentially indefinitely.
*
* \return Bitmask composed of MBEDTLS_NET_POLL_READ/WRITE
* on success or timeout, or a negative return code otherwise.
*/
int mbedtls_net_poll( mbedtls_net_context *ctx, uint32_t rw, uint32_t timeout );
/** /**
* \brief Set the socket blocking * \brief Set the socket blocking
* *
......
/**
* \file nist_kw.h
*
* \brief This file provides an API for key wrapping (KW) and key wrapping with
* padding (KWP) as defined in NIST SP 800-38F.
* https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf
*
* Key wrapping specifies a deterministic authenticated-encryption mode
* of operation, according to <em>NIST SP 800-38F: Recommendation for
* Block Cipher Modes of Operation: Methods for Key Wrapping</em>. Its
* purpose is to protect cryptographic keys.
*
* Its equivalent is RFC 3394 for KW, and RFC 5649 for KWP.
* https://tools.ietf.org/html/rfc3394
* https://tools.ietf.org/html/rfc5649
*
*/
/*
* Copyright (C) 2018, Arm Limited (or its affiliates), All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may
* not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
* This file is part of Mbed TLS (https://tls.mbed.org)
*/
#ifndef MBEDTLS_NIST_KW_H
#define MBEDTLS_NIST_KW_H
#if !defined(MBEDTLS_CONFIG_FILE)
#include "config.h"
#else
#include MBEDTLS_CONFIG_FILE
#endif
#include "cipher.h"
#ifdef __cplusplus
extern "C" {
#endif
typedef enum
{
MBEDTLS_KW_MODE_KW = 0,
MBEDTLS_KW_MODE_KWP = 1
} mbedtls_nist_kw_mode_t;
#if !defined(MBEDTLS_NIST_KW_ALT)
// Regular implementation
//
/**
* \brief The key wrapping context-type definition. The key wrapping context is passed
* to the APIs called.
*
* \note The definition of this type may change in future library versions.
* Don't make any assumptions on this context!
*/
typedef struct {
mbedtls_cipher_context_t cipher_ctx; /*!< The cipher context used. */
} mbedtls_nist_kw_context;
#else /* MBEDTLS_NIST_key wrapping_ALT */
#include "nist_kw_alt.h"
#endif /* MBEDTLS_NIST_KW_ALT */
/**
* \brief This function initializes the specified key wrapping context
* to make references valid and prepare the context
* for mbedtls_nist_kw_setkey() or mbedtls_nist_kw_free().
*
* \param ctx The key wrapping context to initialize.
*
*/
void mbedtls_nist_kw_init( mbedtls_nist_kw_context *ctx );
/**
* \brief This function initializes the key wrapping context set in the
* \p ctx parameter and sets the encryption key.
*
* \param ctx The key wrapping context.
* \param cipher The 128-bit block cipher to use. Only AES is supported.
* \param key The Key Encryption Key (KEK).
* \param keybits The KEK size in bits. This must be acceptable by the cipher.
* \param is_wrap Specify whether the operation within the context is wrapping or unwrapping
*
* \return \c 0 on success.
* \return \c MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA for any invalid input.
* \return \c MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE for 128-bit block ciphers
* which are not supported.
* \return cipher-specific error code on failure of the underlying cipher.
*/
int mbedtls_nist_kw_setkey( mbedtls_nist_kw_context *ctx,
mbedtls_cipher_id_t cipher,
const unsigned char *key,
unsigned int keybits,
const int is_wrap );
/**
* \brief This function releases and clears the specified key wrapping context
* and underlying cipher sub-context.
*
* \param ctx The key wrapping context to clear.
*/
void mbedtls_nist_kw_free( mbedtls_nist_kw_context *ctx );
/**
* \brief This function encrypts a buffer using key wrapping.
*
* \param ctx The key wrapping context to use for encryption.
* \param mode The key wrapping mode to use (MBEDTLS_KW_MODE_KW or MBEDTLS_KW_MODE_KWP)
* \param input The buffer holding the input data.
* \param in_len The length of the input data in Bytes.
* The input uses units of 8 Bytes called semiblocks.
* <ul><li>For KW mode: a multiple of 8 bytes between 16 and 2^57-8 inclusive. </li>
* <li>For KWP mode: any length between 1 and 2^32-1 inclusive.</li></ul>
* \param[out] output The buffer holding the output data.
* <ul><li>For KW mode: Must be at least 8 bytes larger than \p in_len.</li>
* <li>For KWP mode: Must be at least 8 bytes larger rounded up to a multiple of
* 8 bytes for KWP (15 bytes at most).</li></ul>
* \param[out] out_len The number of bytes written to the output buffer. \c 0 on failure.
* \param[in] out_size The capacity of the output buffer.
*
* \return \c 0 on success.
* \return \c MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA for invalid input length.
* \return cipher-specific error code on failure of the underlying cipher.
*/
int mbedtls_nist_kw_wrap( mbedtls_nist_kw_context *ctx, mbedtls_nist_kw_mode_t mode,
const unsigned char *input, size_t in_len,
unsigned char *output, size_t* out_len, size_t out_size );
/**
* \brief This function decrypts a buffer using key wrapping.
*
* \param ctx The key wrapping context to use for decryption.
* \param mode The key wrapping mode to use (MBEDTLS_KW_MODE_KW or MBEDTLS_KW_MODE_KWP)
* \param input The buffer holding the input data.
* \param in_len The length of the input data in Bytes.
* The input uses units of 8 Bytes called semiblocks.
* The input must be a multiple of semiblocks.
* <ul><li>For KW mode: a multiple of 8 bytes between 24 and 2^57 inclusive. </li>
* <li>For KWP mode: a multiple of 8 bytes between 16 and 2^32 inclusive.</li></ul>
* \param[out] output The buffer holding the output data.
* The output buffer's minimal length is 8 bytes shorter than \p in_len.
* \param[out] out_len The number of bytes written to the output buffer. \c 0 on failure.
* For KWP mode, the length could be up to 15 bytes shorter than \p in_len,
* depending on how much padding was added to the data.
* \param[in] out_size The capacity of the output buffer.
*
* \return \c 0 on success.
* \return \c MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA for invalid input length.
* \return \c MBEDTLS_ERR_CIPHER_AUTH_FAILED for verification failure of the ciphertext.
* \return cipher-specific error code on failure of the underlying cipher.
*/
int mbedtls_nist_kw_unwrap( mbedtls_nist_kw_context *ctx, mbedtls_nist_kw_mode_t mode,
const unsigned char *input, size_t in_len,
unsigned char *output, size_t* out_len, size_t out_size);
#if defined(MBEDTLS_SELF_TEST) && defined(MBEDTLS_AES_C)
/**
* \brief The key wrapping checkup routine.
*
* \return \c 0 on success.
* \return \c 1 on failure.
*/
int mbedtls_nist_kw_self_test( int verbose );
#endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */
#ifdef __cplusplus
}
#endif
#endif /* MBEDTLS_NIST_KW_H */
...@@ -97,6 +97,8 @@ ...@@ -97,6 +97,8 @@
/* ISO arc for standard certificate and CRL extensions */ /* ISO arc for standard certificate and CRL extensions */
#define MBEDTLS_OID_ID_CE MBEDTLS_OID_ISO_CCITT_DS "\x1D" /**< id-ce OBJECT IDENTIFIER ::= {joint-iso-ccitt(2) ds(5) 29} */ #define MBEDTLS_OID_ID_CE MBEDTLS_OID_ISO_CCITT_DS "\x1D" /**< id-ce OBJECT IDENTIFIER ::= {joint-iso-ccitt(2) ds(5) 29} */
#define MBEDTLS_OID_NIST_ALG MBEDTLS_OID_GOV "\x03\x04" /** { joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3) nistAlgorithm(4) */
/** /**
* Private Internet Extensions * Private Internet Extensions
* { iso(1) identified-organization(3) dod(6) internet(1) * { iso(1) identified-organization(3) dod(6) internet(1)
...@@ -219,12 +221,12 @@ ...@@ -219,12 +221,12 @@
#define MBEDTLS_OID_DIGEST_ALG_MD4 MBEDTLS_OID_RSA_COMPANY "\x02\x04" /**< id-mbedtls_md4 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) rsadsi(113549) digestAlgorithm(2) 4 } */ #define MBEDTLS_OID_DIGEST_ALG_MD4 MBEDTLS_OID_RSA_COMPANY "\x02\x04" /**< id-mbedtls_md4 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) rsadsi(113549) digestAlgorithm(2) 4 } */
#define MBEDTLS_OID_DIGEST_ALG_MD5 MBEDTLS_OID_RSA_COMPANY "\x02\x05" /**< id-mbedtls_md5 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) rsadsi(113549) digestAlgorithm(2) 5 } */ #define MBEDTLS_OID_DIGEST_ALG_MD5 MBEDTLS_OID_RSA_COMPANY "\x02\x05" /**< id-mbedtls_md5 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) rsadsi(113549) digestAlgorithm(2) 5 } */
#define MBEDTLS_OID_DIGEST_ALG_SHA1 MBEDTLS_OID_ISO_IDENTIFIED_ORG MBEDTLS_OID_OIW_SECSIG_SHA1 /**< id-mbedtls_sha1 OBJECT IDENTIFIER ::= { iso(1) identified-organization(3) oiw(14) secsig(3) algorithms(2) 26 } */ #define MBEDTLS_OID_DIGEST_ALG_SHA1 MBEDTLS_OID_ISO_IDENTIFIED_ORG MBEDTLS_OID_OIW_SECSIG_SHA1 /**< id-mbedtls_sha1 OBJECT IDENTIFIER ::= { iso(1) identified-organization(3) oiw(14) secsig(3) algorithms(2) 26 } */
#define MBEDTLS_OID_DIGEST_ALG_SHA224 MBEDTLS_OID_GOV "\x03\x04\x02\x04" /**< id-sha224 OBJECT IDENTIFIER ::= { joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3) nistalgorithm(4) hashalgs(2) 4 } */ #define MBEDTLS_OID_DIGEST_ALG_SHA224 MBEDTLS_OID_NIST_ALG "\x02\x04" /**< id-sha224 OBJECT IDENTIFIER ::= { joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3) nistalgorithm(4) hashalgs(2) 4 } */
#define MBEDTLS_OID_DIGEST_ALG_SHA256 MBEDTLS_OID_GOV "\x03\x04\x02\x01" /**< id-mbedtls_sha256 OBJECT IDENTIFIER ::= { joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3) nistalgorithm(4) hashalgs(2) 1 } */ #define MBEDTLS_OID_DIGEST_ALG_SHA256 MBEDTLS_OID_NIST_ALG "\x02\x01" /**< id-mbedtls_sha256 OBJECT IDENTIFIER ::= { joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3) nistalgorithm(4) hashalgs(2) 1 } */
#define MBEDTLS_OID_DIGEST_ALG_SHA384 MBEDTLS_OID_GOV "\x03\x04\x02\x02" /**< id-sha384 OBJECT IDENTIFIER ::= { joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3) nistalgorithm(4) hashalgs(2) 2 } */ #define MBEDTLS_OID_DIGEST_ALG_SHA384 MBEDTLS_OID_NIST_ALG "\x02\x02" /**< id-sha384 OBJECT IDENTIFIER ::= { joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3) nistalgorithm(4) hashalgs(2) 2 } */
#define MBEDTLS_OID_DIGEST_ALG_SHA512 MBEDTLS_OID_GOV "\x03\x04\x02\x03" /**< id-mbedtls_sha512 OBJECT IDENTIFIER ::= { joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3) nistalgorithm(4) hashalgs(2) 3 } */ #define MBEDTLS_OID_DIGEST_ALG_SHA512 MBEDTLS_OID_NIST_ALG "\x02\x03" /**< id-mbedtls_sha512 OBJECT IDENTIFIER ::= { joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3) nistalgorithm(4) hashalgs(2) 3 } */
#define MBEDTLS_OID_HMAC_SHA1 MBEDTLS_OID_RSA_COMPANY "\x02\x07" /**< id-hmacWithSHA1 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) rsadsi(113549) digestAlgorithm(2) 7 } */ #define MBEDTLS_OID_HMAC_SHA1 MBEDTLS_OID_RSA_COMPANY "\x02\x07" /**< id-hmacWithSHA1 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) rsadsi(113549) digestAlgorithm(2) 7 } */
...@@ -241,7 +243,20 @@ ...@@ -241,7 +243,20 @@
*/ */
#define MBEDTLS_OID_DES_CBC MBEDTLS_OID_ISO_IDENTIFIED_ORG MBEDTLS_OID_OIW_SECSIG_ALG "\x07" /**< desCBC OBJECT IDENTIFIER ::= { iso(1) identified-organization(3) oiw(14) secsig(3) algorithms(2) 7 } */ #define MBEDTLS_OID_DES_CBC MBEDTLS_OID_ISO_IDENTIFIED_ORG MBEDTLS_OID_OIW_SECSIG_ALG "\x07" /**< desCBC OBJECT IDENTIFIER ::= { iso(1) identified-organization(3) oiw(14) secsig(3) algorithms(2) 7 } */
#define MBEDTLS_OID_DES_EDE3_CBC MBEDTLS_OID_RSA_COMPANY "\x03\x07" /**< des-ede3-cbc OBJECT IDENTIFIER ::= { iso(1) member-body(2) -- us(840) rsadsi(113549) encryptionAlgorithm(3) 7 } */ #define MBEDTLS_OID_DES_EDE3_CBC MBEDTLS_OID_RSA_COMPANY "\x03\x07" /**< des-ede3-cbc OBJECT IDENTIFIER ::= { iso(1) member-body(2) -- us(840) rsadsi(113549) encryptionAlgorithm(3) 7 } */
#define MBEDTLS_OID_AES MBEDTLS_OID_NIST_ALG "\x01" /** aes OBJECT IDENTIFIER ::= { joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3) nistAlgorithm(4) 1 } */
/*
* Key Wrapping algorithms
*/
/*
* RFC 5649
*/
#define MBEDTLS_OID_AES128_KW MBEDTLS_OID_AES "\x05" /** id-aes128-wrap OBJECT IDENTIFIER ::= { aes 5 } */
#define MBEDTLS_OID_AES128_KWP MBEDTLS_OID_AES "\x08" /** id-aes128-wrap-pad OBJECT IDENTIFIER ::= { aes 8 } */
#define MBEDTLS_OID_AES192_KW MBEDTLS_OID_AES "\x19" /** id-aes192-wrap OBJECT IDENTIFIER ::= { aes 25 } */
#define MBEDTLS_OID_AES192_KWP MBEDTLS_OID_AES "\x1c" /** id-aes192-wrap-pad OBJECT IDENTIFIER ::= { aes 28 } */
#define MBEDTLS_OID_AES256_KW MBEDTLS_OID_AES "\x2d" /** id-aes256-wrap OBJECT IDENTIFIER ::= { aes 45 } */
#define MBEDTLS_OID_AES256_KWP MBEDTLS_OID_AES "\x30" /** id-aes256-wrap-pad OBJECT IDENTIFIER ::= { aes 48 } */
/* /*
* PKCS#5 OIDs * PKCS#5 OIDs
*/ */
...@@ -388,7 +403,8 @@ extern "C" { ...@@ -388,7 +403,8 @@ extern "C" {
/** /**
* \brief Base OID descriptor structure * \brief Base OID descriptor structure
*/ */
typedef struct { typedef struct mbedtls_oid_descriptor_t
{
const char *asn1; /*!< OID ASN.1 representation */ const char *asn1; /*!< OID ASN.1 representation */
size_t asn1_len; /*!< length of asn1 */ size_t asn1_len; /*!< length of asn1 */
const char *name; /*!< official name (e.g. from RFC) */ const char *name; /*!< official name (e.g. from RFC) */
......
...@@ -3,6 +3,9 @@ ...@@ -3,6 +3,9 @@
* *
* \brief VIA PadLock ACE for HW encryption/decryption supported by some * \brief VIA PadLock ACE for HW encryption/decryption supported by some
* processors * processors
*
* \warning These functions are only for internal use by other library
* functions; you must not call them directly.
*/ */
/* /*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
...@@ -25,6 +28,12 @@ ...@@ -25,6 +28,12 @@
#ifndef MBEDTLS_PADLOCK_H #ifndef MBEDTLS_PADLOCK_H
#define MBEDTLS_PADLOCK_H #define MBEDTLS_PADLOCK_H
#if !defined(MBEDTLS_CONFIG_FILE)
#include "config.h"
#else
#include MBEDTLS_CONFIG_FILE
#endif
#include "aes.h" #include "aes.h"
#define MBEDTLS_ERR_PADLOCK_DATA_MISALIGNED -0x0030 /**< Input data should be aligned. */ #define MBEDTLS_ERR_PADLOCK_DATA_MISALIGNED -0x0030 /**< Input data should be aligned. */
...@@ -50,14 +59,17 @@ ...@@ -50,14 +59,17 @@
#define MBEDTLS_PADLOCK_PHE 0x0C00 #define MBEDTLS_PADLOCK_PHE 0x0C00
#define MBEDTLS_PADLOCK_PMM 0x3000 #define MBEDTLS_PADLOCK_PMM 0x3000
#define MBEDTLS_PADLOCK_ALIGN16(x) (uint32_t *) (16 + ((int32_t) x & ~15)) #define MBEDTLS_PADLOCK_ALIGN16(x) (uint32_t *) (16 + ((int32_t) (x) & ~15))
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
#endif #endif
/** /**
* \brief PadLock detection routine * \brief Internal PadLock detection routine
*
* \note This function is only for internal use by other library
* functions; you must not call it directly.
* *
* \param feature The feature to detect * \param feature The feature to detect
* *
...@@ -66,7 +78,10 @@ extern "C" { ...@@ -66,7 +78,10 @@ extern "C" {
int mbedtls_padlock_has_support( int feature ); int mbedtls_padlock_has_support( int feature );
/** /**
* \brief PadLock AES-ECB block en(de)cryption * \brief Internal PadLock AES-ECB block en(de)cryption
*
* \note This function is only for internal use by other library
* functions; you must not call it directly.
* *
* \param ctx AES context * \param ctx AES context
* \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT * \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT
...@@ -76,12 +91,15 @@ int mbedtls_padlock_has_support( int feature ); ...@@ -76,12 +91,15 @@ int mbedtls_padlock_has_support( int feature );
* \return 0 if success, 1 if operation failed * \return 0 if success, 1 if operation failed
*/ */
int mbedtls_padlock_xcryptecb( mbedtls_aes_context *ctx, int mbedtls_padlock_xcryptecb( mbedtls_aes_context *ctx,
int mode, int mode,
const unsigned char input[16], const unsigned char input[16],
unsigned char output[16] ); unsigned char output[16] );
/** /**
* \brief PadLock AES-CBC buffer en(de)cryption * \brief Internal PadLock AES-CBC buffer en(de)cryption
*
* \note This function is only for internal use by other library
* functions; you must not call it directly.
* *
* \param ctx AES context * \param ctx AES context
* \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT * \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT
...@@ -93,11 +111,11 @@ int mbedtls_padlock_xcryptecb( mbedtls_aes_context *ctx, ...@@ -93,11 +111,11 @@ int mbedtls_padlock_xcryptecb( mbedtls_aes_context *ctx,
* \return 0 if success, 1 if operation failed * \return 0 if success, 1 if operation failed
*/ */
int mbedtls_padlock_xcryptcbc( mbedtls_aes_context *ctx, int mbedtls_padlock_xcryptcbc( mbedtls_aes_context *ctx,
int mode, int mode,
size_t length, size_t length,
unsigned char iv[16], unsigned char iv[16],
const unsigned char *input, const unsigned char *input,
unsigned char *output ); unsigned char *output );
#ifdef __cplusplus #ifdef __cplusplus
} }
......
...@@ -24,6 +24,12 @@ ...@@ -24,6 +24,12 @@
#ifndef MBEDTLS_PEM_H #ifndef MBEDTLS_PEM_H
#define MBEDTLS_PEM_H #define MBEDTLS_PEM_H
#if !defined(MBEDTLS_CONFIG_FILE)
#include "config.h"
#else
#include MBEDTLS_CONFIG_FILE
#endif
#include <stddef.h> #include <stddef.h>
/** /**
...@@ -51,7 +57,7 @@ extern "C" { ...@@ -51,7 +57,7 @@ extern "C" {
/** /**
* \brief PEM context structure * \brief PEM context structure
*/ */
typedef struct typedef struct mbedtls_pem_context
{ {
unsigned char *buf; /*!< buffer for decoded data */ unsigned char *buf; /*!< buffer for decoded data */
size_t buflen; /*!< length of the buffer */ size_t buflen; /*!< length of the buffer */
......
...@@ -64,6 +64,8 @@ ...@@ -64,6 +64,8 @@
#define MBEDTLS_ERR_PK_UNKNOWN_NAMED_CURVE -0x3A00 /**< Elliptic curve is unsupported (only NIST curves are supported). */ #define MBEDTLS_ERR_PK_UNKNOWN_NAMED_CURVE -0x3A00 /**< Elliptic curve is unsupported (only NIST curves are supported). */
#define MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE -0x3980 /**< Unavailable feature, e.g. RSA disabled for RSA key. */ #define MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE -0x3980 /**< Unavailable feature, e.g. RSA disabled for RSA key. */
#define MBEDTLS_ERR_PK_SIG_LEN_MISMATCH -0x3900 /**< The buffer contains a valid signature followed by more data. */ #define MBEDTLS_ERR_PK_SIG_LEN_MISMATCH -0x3900 /**< The buffer contains a valid signature followed by more data. */
/* MBEDTLS_ERR_PK_HW_ACCEL_FAILED is deprecated and should not be used. */
#define MBEDTLS_ERR_PK_HW_ACCEL_FAILED -0x3880 /**< PK hardware accelerator failed. */ #define MBEDTLS_ERR_PK_HW_ACCEL_FAILED -0x3880 /**< PK hardware accelerator failed. */
#ifdef __cplusplus #ifdef __cplusplus
...@@ -87,7 +89,7 @@ typedef enum { ...@@ -87,7 +89,7 @@ typedef enum {
* \brief Options for RSASSA-PSS signature verification. * \brief Options for RSASSA-PSS signature verification.
* See \c mbedtls_rsa_rsassa_pss_verify_ext() * See \c mbedtls_rsa_rsassa_pss_verify_ext()
*/ */
typedef struct typedef struct mbedtls_pk_rsassa_pss_options
{ {
mbedtls_md_type_t mgf1_hash_id; mbedtls_md_type_t mgf1_hash_id;
int expected_salt_len; int expected_salt_len;
...@@ -107,7 +109,7 @@ typedef enum ...@@ -107,7 +109,7 @@ typedef enum
/** /**
* \brief Item to send to the debug module * \brief Item to send to the debug module
*/ */
typedef struct typedef struct mbedtls_pk_debug_item
{ {
mbedtls_pk_debug_type type; mbedtls_pk_debug_type type;
const char *name; const char *name;
...@@ -125,12 +127,26 @@ typedef struct mbedtls_pk_info_t mbedtls_pk_info_t; ...@@ -125,12 +127,26 @@ typedef struct mbedtls_pk_info_t mbedtls_pk_info_t;
/** /**
* \brief Public key container * \brief Public key container
*/ */
typedef struct typedef struct mbedtls_pk_context
{ {
const mbedtls_pk_info_t * pk_info; /**< Public key informations */ const mbedtls_pk_info_t * pk_info; /**< Public key information */
void * pk_ctx; /**< Underlying public key context */ void * pk_ctx; /**< Underlying public key context */
} mbedtls_pk_context; } mbedtls_pk_context;
#if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
/**
* \brief Context for resuming operations
*/
typedef struct
{
const mbedtls_pk_info_t * pk_info; /**< Public key information */
void * rs_ctx; /**< Underlying restart context */
} mbedtls_pk_restart_ctx;
#else /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
/* Now we can declare functions that take a pointer to that */
typedef void mbedtls_pk_restart_ctx;
#endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
#if defined(MBEDTLS_RSA_C) #if defined(MBEDTLS_RSA_C)
/** /**
* Quick access to an RSA context inside a PK context. * Quick access to an RSA context inside a PK context.
...@@ -181,20 +197,45 @@ typedef size_t (*mbedtls_pk_rsa_alt_key_len_func)( void *ctx ); ...@@ -181,20 +197,45 @@ typedef size_t (*mbedtls_pk_rsa_alt_key_len_func)( void *ctx );
const mbedtls_pk_info_t *mbedtls_pk_info_from_type( mbedtls_pk_type_t pk_type ); const mbedtls_pk_info_t *mbedtls_pk_info_from_type( mbedtls_pk_type_t pk_type );
/** /**
* \brief Initialize a mbedtls_pk_context (as NONE) * \brief Initialize a #mbedtls_pk_context (as NONE).
*
* \param ctx The context to initialize.
* This must not be \c NULL.
*/ */
void mbedtls_pk_init( mbedtls_pk_context *ctx ); void mbedtls_pk_init( mbedtls_pk_context *ctx );
/** /**
* \brief Free a mbedtls_pk_context * \brief Free the components of a #mbedtls_pk_context.
*
* \param ctx The context to clear. It must have been initialized.
* If this is \c NULL, this function does nothing.
*/ */
void mbedtls_pk_free( mbedtls_pk_context *ctx ); void mbedtls_pk_free( mbedtls_pk_context *ctx );
#if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
/**
* \brief Initialize a restart context
*
* \param ctx The context to initialize.
* This must not be \c NULL.
*/
void mbedtls_pk_restart_init( mbedtls_pk_restart_ctx *ctx );
/**
* \brief Free the components of a restart context
*
* \param ctx The context to clear. It must have been initialized.
* If this is \c NULL, this function does nothing.
*/
void mbedtls_pk_restart_free( mbedtls_pk_restart_ctx *ctx );
#endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
/** /**
* \brief Initialize a PK context with the information given * \brief Initialize a PK context with the information given
* and allocates the type-specific PK subcontext. * and allocates the type-specific PK subcontext.
* *
* \param ctx Context to initialize. Must be empty (type NONE). * \param ctx Context to initialize. It must not have been set
* up yet (type #MBEDTLS_PK_NONE).
* \param info Information to use * \param info Information to use
* *
* \return 0 on success, * \return 0 on success,
...@@ -210,7 +251,8 @@ int mbedtls_pk_setup( mbedtls_pk_context *ctx, const mbedtls_pk_info_t *info ); ...@@ -210,7 +251,8 @@ int mbedtls_pk_setup( mbedtls_pk_context *ctx, const mbedtls_pk_info_t *info );
/** /**
* \brief Initialize an RSA-alt context * \brief Initialize an RSA-alt context
* *
* \param ctx Context to initialize. Must be empty (type NONE). * \param ctx Context to initialize. It must not have been set
* up yet (type #MBEDTLS_PK_NONE).
* \param key RSA key pointer * \param key RSA key pointer
* \param decrypt_func Decryption function * \param decrypt_func Decryption function
* \param sign_func Signing function * \param sign_func Signing function
...@@ -230,7 +272,7 @@ int mbedtls_pk_setup_rsa_alt( mbedtls_pk_context *ctx, void * key, ...@@ -230,7 +272,7 @@ int mbedtls_pk_setup_rsa_alt( mbedtls_pk_context *ctx, void * key,
/** /**
* \brief Get the size in bits of the underlying key * \brief Get the size in bits of the underlying key
* *
* \param ctx Context to use * \param ctx The context to query. It must have been initialized.
* *
* \return Key size in bits, or 0 on error * \return Key size in bits, or 0 on error
*/ */
...@@ -238,7 +280,8 @@ size_t mbedtls_pk_get_bitlen( const mbedtls_pk_context *ctx ); ...@@ -238,7 +280,8 @@ size_t mbedtls_pk_get_bitlen( const mbedtls_pk_context *ctx );
/** /**
* \brief Get the length in bytes of the underlying key * \brief Get the length in bytes of the underlying key
* \param ctx Context to use *
* \param ctx The context to query. It must have been initialized.
* *
* \return Key length in bytes, or 0 on error * \return Key length in bytes, or 0 on error
*/ */
...@@ -250,18 +293,21 @@ static inline size_t mbedtls_pk_get_len( const mbedtls_pk_context *ctx ) ...@@ -250,18 +293,21 @@ static inline size_t mbedtls_pk_get_len( const mbedtls_pk_context *ctx )
/** /**
* \brief Tell if a context can do the operation given by type * \brief Tell if a context can do the operation given by type
* *
* \param ctx Context to test * \param ctx The context to query. It must have been initialized.
* \param type Target type * \param type The desired type.
* *
* \return 0 if context can't do the operations, * \return 1 if the context can do operations on the given type.
* 1 otherwise. * \return 0 if the context cannot do the operations on the given
* type. This is always the case for a context that has
* been initialized but not set up, or that has been
* cleared with mbedtls_pk_free().
*/ */
int mbedtls_pk_can_do( const mbedtls_pk_context *ctx, mbedtls_pk_type_t type ); int mbedtls_pk_can_do( const mbedtls_pk_context *ctx, mbedtls_pk_type_t type );
/** /**
* \brief Verify signature (including padding if relevant). * \brief Verify signature (including padding if relevant).
* *
* \param ctx PK context to use * \param ctx The PK context to use. It must have been set up.
* \param md_alg Hash algorithm used (see notes) * \param md_alg Hash algorithm used (see notes)
* \param hash Hash of the message to sign * \param hash Hash of the message to sign
* \param hash_len Hash length or 0 (see notes) * \param hash_len Hash length or 0 (see notes)
...@@ -286,13 +332,39 @@ int mbedtls_pk_verify( mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg, ...@@ -286,13 +332,39 @@ int mbedtls_pk_verify( mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
const unsigned char *hash, size_t hash_len, const unsigned char *hash, size_t hash_len,
const unsigned char *sig, size_t sig_len ); const unsigned char *sig, size_t sig_len );
/**
* \brief Restartable version of \c mbedtls_pk_verify()
*
* \note Performs the same job as \c mbedtls_pk_verify(), but can
* return early and restart according to the limit set with
* \c mbedtls_ecp_set_max_ops() to reduce blocking for ECC
* operations. For RSA, same as \c mbedtls_pk_verify().
*
* \param ctx The PK context to use. It must have been set up.
* \param md_alg Hash algorithm used (see notes)
* \param hash Hash of the message to sign
* \param hash_len Hash length or 0 (see notes)
* \param sig Signature to verify
* \param sig_len Signature length
* \param rs_ctx Restart context (NULL to disable restart)
*
* \return See \c mbedtls_pk_verify(), or
* \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
* operations was reached: see \c mbedtls_ecp_set_max_ops().
*/
int mbedtls_pk_verify_restartable( mbedtls_pk_context *ctx,
mbedtls_md_type_t md_alg,
const unsigned char *hash, size_t hash_len,
const unsigned char *sig, size_t sig_len,
mbedtls_pk_restart_ctx *rs_ctx );
/** /**
* \brief Verify signature, with options. * \brief Verify signature, with options.
* (Includes verification of the padding depending on type.) * (Includes verification of the padding depending on type.)
* *
* \param type Signature type (inc. possible padding type) to verify * \param type Signature type (inc. possible padding type) to verify
* \param options Pointer to type-specific options, or NULL * \param options Pointer to type-specific options, or NULL
* \param ctx PK context to use * \param ctx The PK context to use. It must have been set up.
* \param md_alg Hash algorithm used (see notes) * \param md_alg Hash algorithm used (see notes)
* \param hash Hash of the message to sign * \param hash Hash of the message to sign
* \param hash_len Hash length or 0 (see notes) * \param hash_len Hash length or 0 (see notes)
...@@ -323,7 +395,8 @@ int mbedtls_pk_verify_ext( mbedtls_pk_type_t type, const void *options, ...@@ -323,7 +395,8 @@ int mbedtls_pk_verify_ext( mbedtls_pk_type_t type, const void *options,
/** /**
* \brief Make signature, including padding if relevant. * \brief Make signature, including padding if relevant.
* *
* \param ctx PK context to use - must hold a private key * \param ctx The PK context to use. It must have been set up
* with a private key.
* \param md_alg Hash algorithm used (see notes) * \param md_alg Hash algorithm used (see notes)
* \param hash Hash of the message to sign * \param hash Hash of the message to sign
* \param hash_len Hash length or 0 (see notes) * \param hash_len Hash length or 0 (see notes)
...@@ -343,16 +416,55 @@ int mbedtls_pk_verify_ext( mbedtls_pk_type_t type, const void *options, ...@@ -343,16 +416,55 @@ int mbedtls_pk_verify_ext( mbedtls_pk_type_t type, const void *options,
* *
* \note For RSA, md_alg may be MBEDTLS_MD_NONE if hash_len != 0. * \note For RSA, md_alg may be MBEDTLS_MD_NONE if hash_len != 0.
* For ECDSA, md_alg may never be MBEDTLS_MD_NONE. * For ECDSA, md_alg may never be MBEDTLS_MD_NONE.
*
* \note In order to ensure enough space for the signature, the
* \p sig buffer size must be of at least
* `max(MBEDTLS_ECDSA_MAX_LEN, MBEDTLS_MPI_MAX_SIZE)` bytes.
*/ */
int mbedtls_pk_sign( mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg, int mbedtls_pk_sign( mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
const unsigned char *hash, size_t hash_len, const unsigned char *hash, size_t hash_len,
unsigned char *sig, size_t *sig_len, unsigned char *sig, size_t *sig_len,
int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
/**
* \brief Restartable version of \c mbedtls_pk_sign()
*
* \note Performs the same job as \c mbedtls_pk_sign(), but can
* return early and restart according to the limit set with
* \c mbedtls_ecp_set_max_ops() to reduce blocking for ECC
* operations. For RSA, same as \c mbedtls_pk_sign().
*
* \note In order to ensure enough space for the signature, the
* \p sig buffer size must be of at least
* `max(MBEDTLS_ECDSA_MAX_LEN, MBEDTLS_MPI_MAX_SIZE)` bytes.
*
* \param ctx The PK context to use. It must have been set up
* with a private key.
* \param md_alg Hash algorithm used (see notes)
* \param hash Hash of the message to sign
* \param hash_len Hash length or 0 (see notes)
* \param sig Place to write the signature
* \param sig_len Number of bytes written
* \param f_rng RNG function
* \param p_rng RNG parameter
* \param rs_ctx Restart context (NULL to disable restart)
*
* \return See \c mbedtls_pk_sign(), or
* \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
* operations was reached: see \c mbedtls_ecp_set_max_ops().
*/
int mbedtls_pk_sign_restartable( mbedtls_pk_context *ctx,
mbedtls_md_type_t md_alg,
const unsigned char *hash, size_t hash_len,
unsigned char *sig, size_t *sig_len,
int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
mbedtls_pk_restart_ctx *rs_ctx );
/** /**
* \brief Decrypt message (including padding if relevant). * \brief Decrypt message (including padding if relevant).
* *
* \param ctx PK context to use - must hold a private key * \param ctx The PK context to use. It must have been set up
* with a private key.
* \param input Input to decrypt * \param input Input to decrypt
* \param ilen Input size * \param ilen Input size
* \param output Decrypted output * \param output Decrypted output
...@@ -373,7 +485,7 @@ int mbedtls_pk_decrypt( mbedtls_pk_context *ctx, ...@@ -373,7 +485,7 @@ int mbedtls_pk_decrypt( mbedtls_pk_context *ctx,
/** /**
* \brief Encrypt message (including padding if relevant). * \brief Encrypt message (including padding if relevant).
* *
* \param ctx PK context to use * \param ctx The PK context to use. It must have been set up.
* \param input Message to encrypt * \param input Message to encrypt
* \param ilen Message size * \param ilen Message size
* \param output Encrypted output * \param output Encrypted output
...@@ -404,7 +516,7 @@ int mbedtls_pk_check_pair( const mbedtls_pk_context *pub, const mbedtls_pk_conte ...@@ -404,7 +516,7 @@ int mbedtls_pk_check_pair( const mbedtls_pk_context *pub, const mbedtls_pk_conte
/** /**
* \brief Export debug information * \brief Export debug information
* *
* \param ctx Context to use * \param ctx The PK context to use. It must have been initialized.
* \param items Place to write debug items * \param items Place to write debug items
* *
* \return 0 on success or MBEDTLS_ERR_PK_BAD_INPUT_DATA * \return 0 on success or MBEDTLS_ERR_PK_BAD_INPUT_DATA
...@@ -414,7 +526,7 @@ int mbedtls_pk_debug( const mbedtls_pk_context *ctx, mbedtls_pk_debug_item *item ...@@ -414,7 +526,7 @@ int mbedtls_pk_debug( const mbedtls_pk_context *ctx, mbedtls_pk_debug_item *item
/** /**
* \brief Access the type name * \brief Access the type name
* *
* \param ctx Context to use * \param ctx The PK context to use. It must have been initialized.
* *
* \return Type name on success, or "invalid PK" * \return Type name on success, or "invalid PK"
*/ */
...@@ -423,9 +535,10 @@ const char * mbedtls_pk_get_name( const mbedtls_pk_context *ctx ); ...@@ -423,9 +535,10 @@ const char * mbedtls_pk_get_name( const mbedtls_pk_context *ctx );
/** /**
* \brief Get the key type * \brief Get the key type
* *
* \param ctx Context to use * \param ctx The PK context to use. It must have been initialized.
* *
* \return Type on success, or MBEDTLS_PK_NONE * \return Type on success.
* \return #MBEDTLS_PK_NONE for a context that has not been set up.
*/ */
mbedtls_pk_type_t mbedtls_pk_get_type( const mbedtls_pk_context *ctx ); mbedtls_pk_type_t mbedtls_pk_get_type( const mbedtls_pk_context *ctx );
...@@ -434,12 +547,22 @@ mbedtls_pk_type_t mbedtls_pk_get_type( const mbedtls_pk_context *ctx ); ...@@ -434,12 +547,22 @@ mbedtls_pk_type_t mbedtls_pk_get_type( const mbedtls_pk_context *ctx );
/** /**
* \brief Parse a private key in PEM or DER format * \brief Parse a private key in PEM or DER format
* *
* \param ctx key to be initialized * \param ctx The PK context to fill. It must have been initialized
* \param key input buffer * but not set up.
* \param keylen size of the buffer * \param key Input buffer to parse.
* (including the terminating null byte for PEM data) * The buffer must contain the input exactly, with no
* \param pwd password for decryption (optional) * extra trailing material. For PEM, the buffer must
* \param pwdlen size of the password * contain a null-terminated string.
* \param keylen Size of \b key in bytes.
* For PEM data, this includes the terminating null byte,
* so \p keylen must be equal to `strlen(key) + 1`.
* \param pwd Optional password for decryption.
* Pass \c NULL if expecting a non-encrypted key.
* Pass a string of \p pwdlen bytes if expecting an encrypted
* key; a non-encrypted key will also be accepted.
* The empty password is not supported.
* \param pwdlen Size of the password in bytes.
* Ignored if \p pwd is \c NULL.
* *
* \note On entry, ctx must be empty, either freshly initialised * \note On entry, ctx must be empty, either freshly initialised
* with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a * with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
...@@ -457,10 +580,15 @@ int mbedtls_pk_parse_key( mbedtls_pk_context *ctx, ...@@ -457,10 +580,15 @@ int mbedtls_pk_parse_key( mbedtls_pk_context *ctx,
/** /**
* \brief Parse a public key in PEM or DER format * \brief Parse a public key in PEM or DER format
* *
* \param ctx key to be initialized * \param ctx The PK context to fill. It must have been initialized
* \param key input buffer * but not set up.
* \param keylen size of the buffer * \param key Input buffer to parse.
* (including the terminating null byte for PEM data) * The buffer must contain the input exactly, with no
* extra trailing material. For PEM, the buffer must
* contain a null-terminated string.
* \param keylen Size of \b key in bytes.
* For PEM data, this includes the terminating null byte,
* so \p keylen must be equal to `strlen(key) + 1`.
* *
* \note On entry, ctx must be empty, either freshly initialised * \note On entry, ctx must be empty, either freshly initialised
* with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a * with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
...@@ -478,9 +606,14 @@ int mbedtls_pk_parse_public_key( mbedtls_pk_context *ctx, ...@@ -478,9 +606,14 @@ int mbedtls_pk_parse_public_key( mbedtls_pk_context *ctx,
/** /**
* \brief Load and parse a private key * \brief Load and parse a private key
* *
* \param ctx key to be initialized * \param ctx The PK context to fill. It must have been initialized
* but not set up.
* \param path filename to read the private key from * \param path filename to read the private key from
* \param password password to decrypt the file (can be NULL) * \param password Optional password to decrypt the file.
* Pass \c NULL if expecting a non-encrypted key.
* Pass a null-terminated string if expecting an encrypted
* key; a non-encrypted key will also be accepted.
* The empty password is not supported.
* *
* \note On entry, ctx must be empty, either freshly initialised * \note On entry, ctx must be empty, either freshly initialised
* with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a * with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
...@@ -497,7 +630,8 @@ int mbedtls_pk_parse_keyfile( mbedtls_pk_context *ctx, ...@@ -497,7 +630,8 @@ int mbedtls_pk_parse_keyfile( mbedtls_pk_context *ctx,
/** /**
* \brief Load and parse a public key * \brief Load and parse a public key
* *
* \param ctx key to be initialized * \param ctx The PK context to fill. It must have been initialized
* but not set up.
* \param path filename to read the public key from * \param path filename to read the public key from
* *
* \note On entry, ctx must be empty, either freshly initialised * \note On entry, ctx must be empty, either freshly initialised
...@@ -520,7 +654,7 @@ int mbedtls_pk_parse_public_keyfile( mbedtls_pk_context *ctx, const char *path ) ...@@ -520,7 +654,7 @@ int mbedtls_pk_parse_public_keyfile( mbedtls_pk_context *ctx, const char *path )
* return value to determine where you should start * return value to determine where you should start
* using the buffer * using the buffer
* *
* \param ctx private to write away * \param ctx PK context which must contain a valid private key.
* \param buf buffer to write to * \param buf buffer to write to
* \param size size of the buffer * \param size size of the buffer
* *
...@@ -535,7 +669,7 @@ int mbedtls_pk_write_key_der( mbedtls_pk_context *ctx, unsigned char *buf, size_ ...@@ -535,7 +669,7 @@ int mbedtls_pk_write_key_der( mbedtls_pk_context *ctx, unsigned char *buf, size_
* return value to determine where you should start * return value to determine where you should start
* using the buffer * using the buffer
* *
* \param ctx public key to write away * \param ctx PK context which must contain a valid public or private key.
* \param buf buffer to write to * \param buf buffer to write to
* \param size size of the buffer * \param size size of the buffer
* *
...@@ -548,9 +682,10 @@ int mbedtls_pk_write_pubkey_der( mbedtls_pk_context *ctx, unsigned char *buf, si ...@@ -548,9 +682,10 @@ int mbedtls_pk_write_pubkey_der( mbedtls_pk_context *ctx, unsigned char *buf, si
/** /**
* \brief Write a public key to a PEM string * \brief Write a public key to a PEM string
* *
* \param ctx public key to write away * \param ctx PK context which must contain a valid public or private key.
* \param buf buffer to write to * \param buf Buffer to write to. The output includes a
* \param size size of the buffer * terminating null byte.
* \param size Size of the buffer in bytes.
* *
* \return 0 if successful, or a specific error code * \return 0 if successful, or a specific error code
*/ */
...@@ -559,9 +694,10 @@ int mbedtls_pk_write_pubkey_pem( mbedtls_pk_context *ctx, unsigned char *buf, si ...@@ -559,9 +694,10 @@ int mbedtls_pk_write_pubkey_pem( mbedtls_pk_context *ctx, unsigned char *buf, si
/** /**
* \brief Write a private key to a PKCS#1 or SEC1 PEM string * \brief Write a private key to a PKCS#1 or SEC1 PEM string
* *
* \param ctx private to write away * \param ctx PK context which must contain a valid private key.
* \param buf buffer to write to * \param buf Buffer to write to. The output includes a
* \param size size of the buffer * terminating null byte.
* \param size Size of the buffer in bytes.
* *
* \return 0 if successful, or a specific error code * \return 0 if successful, or a specific error code
*/ */
...@@ -580,7 +716,8 @@ int mbedtls_pk_write_key_pem( mbedtls_pk_context *ctx, unsigned char *buf, size_ ...@@ -580,7 +716,8 @@ int mbedtls_pk_write_key_pem( mbedtls_pk_context *ctx, unsigned char *buf, size_
* *
* \param p the position in the ASN.1 data * \param p the position in the ASN.1 data
* \param end end of the buffer * \param end end of the buffer
* \param pk the key to fill * \param pk The PK context to fill. It must have been initialized
* but not set up.
* *
* \return 0 if successful, or a specific PK error code * \return 0 if successful, or a specific PK error code
*/ */
...@@ -595,7 +732,7 @@ int mbedtls_pk_parse_subpubkey( unsigned char **p, const unsigned char *end, ...@@ -595,7 +732,7 @@ int mbedtls_pk_parse_subpubkey( unsigned char **p, const unsigned char *end,
* *
* \param p reference to current position pointer * \param p reference to current position pointer
* \param start start of the buffer (for bounds-checking) * \param start start of the buffer (for bounds-checking)
* \param key public key to write away * \param key PK context which must contain a valid public or private key.
* *
* \return the length written or a negative error code * \return the length written or a negative error code
*/ */
......
...@@ -59,6 +59,21 @@ struct mbedtls_pk_info_t ...@@ -59,6 +59,21 @@ struct mbedtls_pk_info_t
int (*f_rng)(void *, unsigned char *, size_t), int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng ); void *p_rng );
#if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
/** Verify signature (restartable) */
int (*verify_rs_func)( void *ctx, mbedtls_md_type_t md_alg,
const unsigned char *hash, size_t hash_len,
const unsigned char *sig, size_t sig_len,
void *rs_ctx );
/** Make signature (restartable) */
int (*sign_rs_func)( void *ctx, mbedtls_md_type_t md_alg,
const unsigned char *hash, size_t hash_len,
unsigned char *sig, size_t *sig_len,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng, void *rs_ctx );
#endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
/** Decrypt message */ /** Decrypt message */
int (*decrypt_func)( void *ctx, const unsigned char *input, size_t ilen, int (*decrypt_func)( void *ctx, const unsigned char *input, size_t ilen,
unsigned char *output, size_t *olen, size_t osize, unsigned char *output, size_t *olen, size_t osize,
...@@ -80,6 +95,14 @@ struct mbedtls_pk_info_t ...@@ -80,6 +95,14 @@ struct mbedtls_pk_info_t
/** Free the given context */ /** Free the given context */
void (*ctx_free_func)( void *ctx ); void (*ctx_free_func)( void *ctx );
#if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
/** Allocate the restart context */
void * (*rs_alloc_func)( void );
/** Free the restart context */
void (*rs_free_func)( void *rs_ctx );
#endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
/** Interface with the debug module */ /** Interface with the debug module */
void (*debug_func)( const void *ctx, mbedtls_pk_debug_item *items ); void (*debug_func)( const void *ctx, mbedtls_pk_debug_item *items );
......
...@@ -50,7 +50,8 @@ extern "C" { ...@@ -50,7 +50,8 @@ extern "C" {
/** /**
* Context for PKCS #11 private keys. * Context for PKCS #11 private keys.
*/ */
typedef struct { typedef struct mbedtls_pkcs11_context
{
pkcs11h_certificate_t pkcs11h_cert; pkcs11h_certificate_t pkcs11h_cert;
int len; int len;
} mbedtls_pkcs11_context; } mbedtls_pkcs11_context;
......
...@@ -91,6 +91,8 @@ int mbedtls_pkcs5_pbkdf2_hmac( mbedtls_md_context_t *ctx, const unsigned char *p ...@@ -91,6 +91,8 @@ int mbedtls_pkcs5_pbkdf2_hmac( mbedtls_md_context_t *ctx, const unsigned char *p
unsigned int iteration_count, unsigned int iteration_count,
uint32_t key_length, unsigned char *output ); uint32_t key_length, unsigned char *output );
#if defined(MBEDTLS_SELF_TEST)
/** /**
* \brief Checkup routine * \brief Checkup routine
* *
...@@ -98,6 +100,8 @@ int mbedtls_pkcs5_pbkdf2_hmac( mbedtls_md_context_t *ctx, const unsigned char *p ...@@ -98,6 +100,8 @@ int mbedtls_pkcs5_pbkdf2_hmac( mbedtls_md_context_t *ctx, const unsigned char *p
*/ */
int mbedtls_pkcs5_self_test( int verbose ); int mbedtls_pkcs5_self_test( int verbose );
#endif /* MBEDTLS_SELF_TEST */
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif
......
/** /**
* \file platform.h * \file platform.h
* *
* \brief The Mbed TLS platform abstraction layer. * \brief This file contains the definitions and functions of the
* Mbed TLS platform abstraction layer.
*
* The platform abstraction layer removes the need for the library
* to directly link to standard C library functions or operating
* system services, making the library easier to port and embed.
* Application developers and users of the library can provide their own
* implementations of these functions, or implementations specific to
* their platform, which can be statically linked to the library or
* dynamically configured at runtime.
*/ */
/* /*
* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
...@@ -34,6 +43,9 @@ ...@@ -34,6 +43,9 @@
#include "platform_time.h" #include "platform_time.h"
#endif #endif
#define MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED -0x0070 /**< Hardware accelerator failed */
#define MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED -0x0072 /**< The requested feature is not supported by the platform */
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
#endif #endif
...@@ -102,7 +114,7 @@ extern "C" { ...@@ -102,7 +114,7 @@ extern "C" {
/* \} name SECTION: Module settings */ /* \} name SECTION: Module settings */
/* /*
* The function pointers for calloc and free * The function pointers for calloc and free.
*/ */
#if defined(MBEDTLS_PLATFORM_MEMORY) #if defined(MBEDTLS_PLATFORM_MEMORY)
#if defined(MBEDTLS_PLATFORM_FREE_MACRO) && \ #if defined(MBEDTLS_PLATFORM_FREE_MACRO) && \
...@@ -112,11 +124,12 @@ extern "C" { ...@@ -112,11 +124,12 @@ extern "C" {
#else #else
/* For size_t */ /* For size_t */
#include <stddef.h> #include <stddef.h>
extern void * (*mbedtls_calloc)( size_t n, size_t size ); extern void *mbedtls_calloc( size_t n, size_t size );
extern void (*mbedtls_free)( void *ptr ); extern void mbedtls_free( void *ptr );
/** /**
* \brief This function allows configuring custom memory-management functions. * \brief This function dynamically sets the memory-management
* functions used by the library, during runtime.
* *
* \param calloc_func The \c calloc function implementation. * \param calloc_func The \c calloc function implementation.
* \param free_func The \c free function implementation. * \param free_func The \c free function implementation.
...@@ -140,7 +153,9 @@ int mbedtls_platform_set_calloc_free( void * (*calloc_func)( size_t, size_t ), ...@@ -140,7 +153,9 @@ int mbedtls_platform_set_calloc_free( void * (*calloc_func)( size_t, size_t ),
extern int (*mbedtls_fprintf)( FILE *stream, const char *format, ... ); extern int (*mbedtls_fprintf)( FILE *stream, const char *format, ... );
/** /**
* \brief This function allows configuring a custom \p fprintf function pointer. * \brief This function dynamically configures the fprintf
* function that is called when the
* mbedtls_fprintf() function is invoked by the library.
* *
* \param fprintf_func The \c fprintf function implementation. * \param fprintf_func The \c fprintf function implementation.
* *
...@@ -163,8 +178,9 @@ int mbedtls_platform_set_fprintf( int (*fprintf_func)( FILE *stream, const char ...@@ -163,8 +178,9 @@ int mbedtls_platform_set_fprintf( int (*fprintf_func)( FILE *stream, const char
extern int (*mbedtls_printf)( const char *format, ... ); extern int (*mbedtls_printf)( const char *format, ... );
/** /**
* \brief This function allows configuring a custom \c printf function * \brief This function dynamically configures the snprintf
* pointer. * function that is called when the mbedtls_snprintf()
* function is invoked by the library.
* *
* \param printf_func The \c printf function implementation. * \param printf_func The \c printf function implementation.
* *
...@@ -197,12 +213,12 @@ int mbedtls_platform_win32_snprintf( char *s, size_t n, const char *fmt, ... ); ...@@ -197,12 +213,12 @@ int mbedtls_platform_win32_snprintf( char *s, size_t n, const char *fmt, ... );
extern int (*mbedtls_snprintf)( char * s, size_t n, const char * format, ... ); extern int (*mbedtls_snprintf)( char * s, size_t n, const char * format, ... );
/** /**
* \brief This function allows configuring a custom \c snprintf function * \brief This function allows configuring a custom
* pointer. * \c snprintf function pointer.
* *
* \param snprintf_func The \c snprintf function implementation. * \param snprintf_func The \c snprintf function implementation.
* *
* \return \c 0 on success. * \return \c 0 on success.
*/ */
int mbedtls_platform_set_snprintf( int (*snprintf_func)( char * s, size_t n, int mbedtls_platform_set_snprintf( int (*snprintf_func)( char * s, size_t n,
const char * format, ... ) ); const char * format, ... ) );
...@@ -211,8 +227,8 @@ int mbedtls_platform_set_snprintf( int (*snprintf_func)( char * s, size_t n, ...@@ -211,8 +227,8 @@ int mbedtls_platform_set_snprintf( int (*snprintf_func)( char * s, size_t n,
#define mbedtls_snprintf MBEDTLS_PLATFORM_SNPRINTF_MACRO #define mbedtls_snprintf MBEDTLS_PLATFORM_SNPRINTF_MACRO
#define mbedtls_vsnprintf MBEDTLS_PLATFORM_VSNPRINTF_MACRO #define mbedtls_vsnprintf MBEDTLS_PLATFORM_VSNPRINTF_MACRO
#else #else
#define mbedtls_snprintf snprintf
#define mbedtls_vsnprintf vsnprintf #define mbedtls_vsnprintf vsnprintf
#define mbedtls_snprintf MBEDTLS_PLATFORM_STD_SNPRINTF
#endif /* MBEDTLS_PLATFORM_SNPRINTF_MACRO */ #endif /* MBEDTLS_PLATFORM_SNPRINTF_MACRO */
#endif /* MBEDTLS_PLATFORM_SNPRINTF_ALT */ #endif /* MBEDTLS_PLATFORM_SNPRINTF_ALT */
...@@ -223,12 +239,13 @@ int mbedtls_platform_set_snprintf( int (*snprintf_func)( char * s, size_t n, ...@@ -223,12 +239,13 @@ int mbedtls_platform_set_snprintf( int (*snprintf_func)( char * s, size_t n,
extern void (*mbedtls_exit)( int status ); extern void (*mbedtls_exit)( int status );
/** /**
* \brief This function allows configuring a custom \c exit function * \brief This function dynamically configures the exit
* pointer. * function that is called when the mbedtls_exit()
* function is invoked by the library.
* *
* \param exit_func The \c exit function implementation. * \param exit_func The \c exit function implementation.
* *
* \return \c 0 on success. * \return \c 0 on success.
*/ */
int mbedtls_platform_set_exit( void (*exit_func)( int status ) ); int mbedtls_platform_set_exit( void (*exit_func)( int status ) );
#else #else
...@@ -303,8 +320,9 @@ int mbedtls_platform_set_nv_seed( ...@@ -303,8 +320,9 @@ int mbedtls_platform_set_nv_seed(
* \note This structure may be used to assist platform-specific * \note This structure may be used to assist platform-specific
* setup or teardown operations. * setup or teardown operations.
*/ */
typedef struct { typedef struct mbedtls_platform_context
char dummy; /**< Placeholder member, as empty structs are not portable. */ {
char dummy; /**< A placeholder member, as empty structs are not portable. */
} }
mbedtls_platform_context; mbedtls_platform_context;
...@@ -313,33 +331,34 @@ mbedtls_platform_context; ...@@ -313,33 +331,34 @@ mbedtls_platform_context;
#endif /* !MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT */ #endif /* !MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT */
/** /**
* \brief This function performs any platform initialization operations. * \brief This function performs any platform-specific initialization
* operations.
* *
* \param ctx The Mbed TLS context. * \note This function should be called before any other library functions.
* *
* \return \c 0 on success. * Its implementation is platform-specific, and unless
*
* \note This function is intended to allow platform-specific initialization,
* and should be called before any other library functions. Its
* implementation is platform-specific, and unless
* platform-specific code is provided, it does nothing. * platform-specific code is provided, it does nothing.
* *
* Its use and whether it is necessary to call it is dependent on the * \note The usage and necessity of this function is dependent on the platform.
* platform. *
* \param ctx The platform context.
*
* \return \c 0 on success.
*/ */
int mbedtls_platform_setup( mbedtls_platform_context *ctx ); int mbedtls_platform_setup( mbedtls_platform_context *ctx );
/** /**
* \brief This function performs any platform teardown operations. * \brief This function performs any platform teardown operations.
* *
* \param ctx The Mbed TLS context.
*
* \note This function should be called after every other Mbed TLS module * \note This function should be called after every other Mbed TLS module
* has been correctly freed using the appropriate free function. * has been correctly freed using the appropriate free function.
*
* Its implementation is platform-specific, and unless * Its implementation is platform-specific, and unless
* platform-specific code is provided, it does nothing. * platform-specific code is provided, it does nothing.
* *
* Its use and whether it is necessary to call it is dependent on the * \note The usage and necessity of this function is dependent on the platform.
* platform. *
* \param ctx The platform context.
*
*/ */
void mbedtls_platform_teardown( mbedtls_platform_context *ctx ); void mbedtls_platform_teardown( mbedtls_platform_context *ctx );
......
/**
* \file platform_util.h
*
* \brief Common and shared functions used by multiple modules in the Mbed TLS
* library.
*/
/*
* Copyright (C) 2018, Arm Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may
* not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
* This file is part of Mbed TLS (https://tls.mbed.org)
*/
#ifndef MBEDTLS_PLATFORM_UTIL_H
#define MBEDTLS_PLATFORM_UTIL_H
#if !defined(MBEDTLS_CONFIG_FILE)
#include "config.h"
#else
#include MBEDTLS_CONFIG_FILE
#endif
#include <stddef.h>
#if defined(MBEDTLS_HAVE_TIME_DATE)
#include "platform_time.h"
#include <time.h>
#endif /* MBEDTLS_HAVE_TIME_DATE */
#ifdef __cplusplus
extern "C" {
#endif
#if defined(MBEDTLS_CHECK_PARAMS)
#if defined(MBEDTLS_CHECK_PARAMS_ASSERT)
/* Allow the user to define MBEDTLS_PARAM_FAILED to something like assert
* (which is what our config.h suggests). */
#include <assert.h>
#endif /* MBEDTLS_CHECK_PARAMS_ASSERT */
#if defined(MBEDTLS_PARAM_FAILED)
/** An alternative definition of MBEDTLS_PARAM_FAILED has been set in config.h.
*
* This flag can be used to check whether it is safe to assume that
* MBEDTLS_PARAM_FAILED() will expand to a call to mbedtls_param_failed().
*/
#define MBEDTLS_PARAM_FAILED_ALT
#elif defined(MBEDTLS_CHECK_PARAMS_ASSERT)
#define MBEDTLS_PARAM_FAILED( cond ) assert( cond )
#define MBEDTLS_PARAM_FAILED_ALT
#else /* MBEDTLS_PARAM_FAILED */
#define MBEDTLS_PARAM_FAILED( cond ) \
mbedtls_param_failed( #cond, __FILE__, __LINE__ )
/**
* \brief User supplied callback function for parameter validation failure.
* See #MBEDTLS_CHECK_PARAMS for context.
*
* This function will be called unless an alternative treatement
* is defined through the #MBEDTLS_PARAM_FAILED macro.
*
* This function can return, and the operation will be aborted, or
* alternatively, through use of setjmp()/longjmp() can resume
* execution in the application code.
*
* \param failure_condition The assertion that didn't hold.
* \param file The file where the assertion failed.
* \param line The line in the file where the assertion failed.
*/
void mbedtls_param_failed( const char *failure_condition,
const char *file,
int line );
#endif /* MBEDTLS_PARAM_FAILED */
/* Internal macro meant to be called only from within the library. */
#define MBEDTLS_INTERNAL_VALIDATE_RET( cond, ret ) \
do { \
if( !(cond) ) \
{ \
MBEDTLS_PARAM_FAILED( cond ); \
return( ret ); \
} \
} while( 0 )
/* Internal macro meant to be called only from within the library. */
#define MBEDTLS_INTERNAL_VALIDATE( cond ) \
do { \
if( !(cond) ) \
{ \
MBEDTLS_PARAM_FAILED( cond ); \
return; \
} \
} while( 0 )
#else /* MBEDTLS_CHECK_PARAMS */
/* Internal macros meant to be called only from within the library. */
#define MBEDTLS_INTERNAL_VALIDATE_RET( cond, ret ) do { } while( 0 )
#define MBEDTLS_INTERNAL_VALIDATE( cond ) do { } while( 0 )
#endif /* MBEDTLS_CHECK_PARAMS */
/* Internal helper macros for deprecating API constants. */
#if !defined(MBEDTLS_DEPRECATED_REMOVED)
#if defined(MBEDTLS_DEPRECATED_WARNING)
/* Deliberately don't (yet) export MBEDTLS_DEPRECATED here
* to avoid conflict with other headers which define and use
* it, too. We might want to move all these definitions here at
* some point for uniformity. */
#define MBEDTLS_DEPRECATED __attribute__((deprecated))
MBEDTLS_DEPRECATED typedef char const * mbedtls_deprecated_string_constant_t;
#define MBEDTLS_DEPRECATED_STRING_CONSTANT( VAL ) \
( (mbedtls_deprecated_string_constant_t) ( VAL ) )
MBEDTLS_DEPRECATED typedef int mbedtls_deprecated_numeric_constant_t;
#define MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( VAL ) \
( (mbedtls_deprecated_numeric_constant_t) ( VAL ) )
#undef MBEDTLS_DEPRECATED
#else /* MBEDTLS_DEPRECATED_WARNING */
#define MBEDTLS_DEPRECATED_STRING_CONSTANT( VAL ) VAL
#define MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( VAL ) VAL
#endif /* MBEDTLS_DEPRECATED_WARNING */
#endif /* MBEDTLS_DEPRECATED_REMOVED */
/**
* \brief Securely zeroize a buffer
*
* The function is meant to wipe the data contained in a buffer so
* that it can no longer be recovered even if the program memory
* is later compromised. Call this function on sensitive data
* stored on the stack before returning from a function, and on
* sensitive data stored on the heap before freeing the heap
* object.
*
* It is extremely difficult to guarantee that calls to
* mbedtls_platform_zeroize() are not removed by aggressive
* compiler optimizations in a portable way. For this reason, Mbed
* TLS provides the configuration option
* MBEDTLS_PLATFORM_ZEROIZE_ALT, which allows users to configure
* mbedtls_platform_zeroize() to use a suitable implementation for
* their platform and needs
*
* \param buf Buffer to be zeroized
* \param len Length of the buffer in bytes
*
*/
void mbedtls_platform_zeroize( void *buf, size_t len );
#if defined(MBEDTLS_HAVE_TIME_DATE)
/**
* \brief Platform-specific implementation of gmtime_r()
*
* The function is a thread-safe abstraction that behaves
* similarly to the gmtime_r() function from Unix/POSIX.
*
* Mbed TLS will try to identify the underlying platform and
* make use of an appropriate underlying implementation (e.g.
* gmtime_r() for POSIX and gmtime_s() for Windows). If this is
* not possible, then gmtime() will be used. In this case, calls
* from the library to gmtime() will be guarded by the mutex
* mbedtls_threading_gmtime_mutex if MBEDTLS_THREADING_C is
* enabled. It is recommended that calls from outside the library
* are also guarded by this mutex.
*
* If MBEDTLS_PLATFORM_GMTIME_R_ALT is defined, then Mbed TLS will
* unconditionally use the alternative implementation for
* mbedtls_platform_gmtime_r() supplied by the user at compile time.
*
* \param tt Pointer to an object containing time (in seconds) since the
* epoch to be converted
* \param tm_buf Pointer to an object where the results will be stored
*
* \return Pointer to an object of type struct tm on success, otherwise
* NULL
*/
struct tm *mbedtls_platform_gmtime_r( const mbedtls_time_t *tt,
struct tm *tm_buf );
#endif /* MBEDTLS_HAVE_TIME_DATE */
#ifdef __cplusplus
}
#endif
#endif /* MBEDTLS_PLATFORM_UTIL_H */
/**
* \file poly1305.h
*
* \brief This file contains Poly1305 definitions and functions.
*
* Poly1305 is a one-time message authenticator that can be used to
* authenticate messages. Poly1305-AES was created by Daniel
* Bernstein https://cr.yp.to/mac/poly1305-20050329.pdf The generic
* Poly1305 algorithm (not tied to AES) was also standardized in RFC
* 7539.
*
* \author Daniel King <damaki.gh@gmail.com>
*/
/* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved.
* SPDX-License-Identifier: Apache-2.0
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may
* not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
* This file is part of Mbed TLS (https://tls.mbed.org)
*/
#ifndef MBEDTLS_POLY1305_H
#define MBEDTLS_POLY1305_H
#if !defined(MBEDTLS_CONFIG_FILE)
#include "config.h"
#else
#include MBEDTLS_CONFIG_FILE
#endif
#include <stdint.h>
#include <stddef.h>
#define MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA -0x0057 /**< Invalid input parameter(s). */
/* MBEDTLS_ERR_POLY1305_FEATURE_UNAVAILABLE is deprecated and should not be
* used. */
#define MBEDTLS_ERR_POLY1305_FEATURE_UNAVAILABLE -0x0059 /**< Feature not available. For example, s part of the API is not implemented. */
/* MBEDTLS_ERR_POLY1305_HW_ACCEL_FAILED is deprecated and should not be used.
*/
#define MBEDTLS_ERR_POLY1305_HW_ACCEL_FAILED -0x005B /**< Poly1305 hardware accelerator failed. */
#ifdef __cplusplus
extern "C" {
#endif
#if !defined(MBEDTLS_POLY1305_ALT)
typedef struct mbedtls_poly1305_context
{
uint32_t r[4]; /** The value for 'r' (low 128 bits of the key). */
uint32_t s[4]; /** The value for 's' (high 128 bits of the key). */
uint32_t acc[5]; /** The accumulator number. */
uint8_t queue[16]; /** The current partial block of data. */
size_t queue_len; /** The number of bytes stored in 'queue'. */
}
mbedtls_poly1305_context;
#else /* MBEDTLS_POLY1305_ALT */
#include "poly1305_alt.h"
#endif /* MBEDTLS_POLY1305_ALT */
/**
* \brief This function initializes the specified Poly1305 context.
*
* It must be the first API called before using
* the context.
*
* It is usually followed by a call to
* \c mbedtls_poly1305_starts(), then one or more calls to
* \c mbedtls_poly1305_update(), then one call to
* \c mbedtls_poly1305_finish(), then finally
* \c mbedtls_poly1305_free().
*
* \param ctx The Poly1305 context to initialize. This must
* not be \c NULL.
*/
void mbedtls_poly1305_init( mbedtls_poly1305_context *ctx );
/**
* \brief This function releases and clears the specified
* Poly1305 context.
*
* \param ctx The Poly1305 context to clear. This may be \c NULL, in which
* case this function is a no-op. If it is not \c NULL, it must
* point to an initialized Poly1305 context.
*/
void mbedtls_poly1305_free( mbedtls_poly1305_context *ctx );
/**
* \brief This function sets the one-time authentication key.
*
* \warning The key must be unique and unpredictable for each
* invocation of Poly1305.
*
* \param ctx The Poly1305 context to which the key should be bound.
* This must be initialized.
* \param key The buffer containing the \c 32 Byte (\c 256 Bit) key.
*
* \return \c 0 on success.
* \return A negative error code on failure.
*/
int mbedtls_poly1305_starts( mbedtls_poly1305_context *ctx,
const unsigned char key[32] );
/**
* \brief This functions feeds an input buffer into an ongoing
* Poly1305 computation.
*
* It is called between \c mbedtls_cipher_poly1305_starts() and
* \c mbedtls_cipher_poly1305_finish().
* It can be called repeatedly to process a stream of data.
*
* \param ctx The Poly1305 context to use for the Poly1305 operation.
* This must be initialized and bound to a key.
* \param ilen The length of the input data in Bytes.
* Any value is accepted.
* \param input The buffer holding the input data.
* This pointer can be \c NULL if `ilen == 0`.
*
* \return \c 0 on success.
* \return A negative error code on failure.
*/
int mbedtls_poly1305_update( mbedtls_poly1305_context *ctx,
const unsigned char *input,
size_t ilen );
/**
* \brief This function generates the Poly1305 Message
* Authentication Code (MAC).
*
* \param ctx The Poly1305 context to use for the Poly1305 operation.
* This must be initialized and bound to a key.
* \param mac The buffer to where the MAC is written. This must
* be a writable buffer of length \c 16 Bytes.
*
* \return \c 0 on success.
* \return A negative error code on failure.
*/
int mbedtls_poly1305_finish( mbedtls_poly1305_context *ctx,
unsigned char mac[16] );
/**
* \brief This function calculates the Poly1305 MAC of the input
* buffer with the provided key.
*
* \warning The key must be unique and unpredictable for each
* invocation of Poly1305.
*
* \param key The buffer containing the \c 32 Byte (\c 256 Bit) key.
* \param ilen The length of the input data in Bytes.
* Any value is accepted.
* \param input The buffer holding the input data.
* This pointer can be \c NULL if `ilen == 0`.
* \param mac The buffer to where the MAC is written. This must be
* a writable buffer of length \c 16 Bytes.
*
* \return \c 0 on success.
* \return A negative error code on failure.
*/
int mbedtls_poly1305_mac( const unsigned char key[32],
const unsigned char *input,
size_t ilen,
unsigned char mac[16] );
#if defined(MBEDTLS_SELF_TEST)
/**
* \brief The Poly1305 checkup routine.
*
* \return \c 0 on success.
* \return \c 1 on failure.
*/
int mbedtls_poly1305_self_test( int verbose );
#endif /* MBEDTLS_SELF_TEST */
#ifdef __cplusplus
}
#endif
#endif /* MBEDTLS_POLY1305_H */
...@@ -33,20 +33,22 @@ ...@@ -33,20 +33,22 @@
#include <stddef.h> #include <stddef.h>
#include <stdint.h> #include <stdint.h>
/* MBEDTLS_ERR_RIPEMD160_HW_ACCEL_FAILED is deprecated and should not be used.
*/
#define MBEDTLS_ERR_RIPEMD160_HW_ACCEL_FAILED -0x0031 /**< RIPEMD160 hardware accelerator failed */ #define MBEDTLS_ERR_RIPEMD160_HW_ACCEL_FAILED -0x0031 /**< RIPEMD160 hardware accelerator failed */
#if !defined(MBEDTLS_RIPEMD160_ALT)
// Regular implementation
//
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
#endif #endif
#if !defined(MBEDTLS_RIPEMD160_ALT)
// Regular implementation
//
/** /**
* \brief RIPEMD-160 context structure * \brief RIPEMD-160 context structure
*/ */
typedef struct typedef struct mbedtls_ripemd160_context
{ {
uint32_t total[2]; /*!< number of bytes processed */ uint32_t total[2]; /*!< number of bytes processed */
uint32_t state[5]; /*!< intermediate digest state */ uint32_t state[5]; /*!< intermediate digest state */
...@@ -54,6 +56,10 @@ typedef struct ...@@ -54,6 +56,10 @@ typedef struct
} }
mbedtls_ripemd160_context; mbedtls_ripemd160_context;
#else /* MBEDTLS_RIPEMD160_ALT */
#include "ripemd160.h"
#endif /* MBEDTLS_RIPEMD160_ALT */
/** /**
* \brief Initialize RIPEMD-160 context * \brief Initialize RIPEMD-160 context
* *
...@@ -178,18 +184,6 @@ MBEDTLS_DEPRECATED void mbedtls_ripemd160_process( ...@@ -178,18 +184,6 @@ MBEDTLS_DEPRECATED void mbedtls_ripemd160_process(
#undef MBEDTLS_DEPRECATED #undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */ #endif /* !MBEDTLS_DEPRECATED_REMOVED */
#ifdef __cplusplus
}
#endif
#else /* MBEDTLS_RIPEMD160_ALT */
#include "ripemd160_alt.h"
#endif /* MBEDTLS_RIPEMD160_ALT */
#ifdef __cplusplus
extern "C" {
#endif
/** /**
* \brief Output = RIPEMD-160( input buffer ) * \brief Output = RIPEMD-160( input buffer )
* *
...@@ -225,6 +219,8 @@ MBEDTLS_DEPRECATED void mbedtls_ripemd160( const unsigned char *input, ...@@ -225,6 +219,8 @@ MBEDTLS_DEPRECATED void mbedtls_ripemd160( const unsigned char *input,
#undef MBEDTLS_DEPRECATED #undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */ #endif /* !MBEDTLS_DEPRECATED_REMOVED */
#if defined(MBEDTLS_SELF_TEST)
/** /**
* \brief Checkup routine * \brief Checkup routine
* *
...@@ -232,6 +228,8 @@ MBEDTLS_DEPRECATED void mbedtls_ripemd160( const unsigned char *input, ...@@ -232,6 +228,8 @@ MBEDTLS_DEPRECATED void mbedtls_ripemd160( const unsigned char *input,
*/ */
int mbedtls_ripemd160_self_test( int verbose ); int mbedtls_ripemd160_self_test( int verbose );
#endif /* MBEDTLS_SELF_TEST */
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif
......
/** /**
* \file rsa.h * \file rsa.h
* *
* \brief The RSA public-key cryptosystem. * \brief This file provides an API for the RSA public-key cryptosystem.
* *
* For more information, see <em>Public-Key Cryptography Standards (PKCS) * The RSA public-key cryptosystem is defined in <em>Public-Key
* #1 v1.5: RSA Encryption</em> and <em>Public-Key Cryptography Standards * Cryptography Standards (PKCS) #1 v1.5: RSA Encryption</em>
* (PKCS) #1 v2.1: RSA Cryptography Specifications</em>. * and <em>Public-Key Cryptography Standards (PKCS) #1 v2.1:
* RSA Cryptography Specifications</em>.
* *
*/ */
/* /*
...@@ -54,7 +55,12 @@ ...@@ -54,7 +55,12 @@
#define MBEDTLS_ERR_RSA_VERIFY_FAILED -0x4380 /**< The PKCS#1 verification failed. */ #define MBEDTLS_ERR_RSA_VERIFY_FAILED -0x4380 /**< The PKCS#1 verification failed. */
#define MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE -0x4400 /**< The output buffer for decryption is not large enough. */ #define MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE -0x4400 /**< The output buffer for decryption is not large enough. */
#define MBEDTLS_ERR_RSA_RNG_FAILED -0x4480 /**< The random generator failed to generate non-zeros. */ #define MBEDTLS_ERR_RSA_RNG_FAILED -0x4480 /**< The random generator failed to generate non-zeros. */
/* MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION is deprecated and should not be used.
*/
#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. */ #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. */ #define MBEDTLS_ERR_RSA_HW_ACCEL_FAILED -0x4580 /**< RSA hardware accelerator failed. */
/* /*
...@@ -63,8 +69,8 @@ ...@@ -63,8 +69,8 @@
#define MBEDTLS_RSA_PUBLIC 0 /**< Request private key operation. */ #define MBEDTLS_RSA_PUBLIC 0 /**< Request private key operation. */
#define MBEDTLS_RSA_PRIVATE 1 /**< Request public 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_V15 0 /**< Use PKCS#1 v1.5 encoding. */
#define MBEDTLS_RSA_PKCS_V21 1 /**< Use PKCS-1 v2.1 encoding. */ #define MBEDTLS_RSA_PKCS_V21 1 /**< Use PKCS#1 v2.1 encoding. */
#define MBEDTLS_RSA_SIGN 1 /**< Identifier for RSA signature operations. */ #define MBEDTLS_RSA_SIGN 1 /**< Identifier for RSA signature operations. */
#define MBEDTLS_RSA_CRYPT 2 /**< Identifier for RSA encryption and decryption operations. */ #define MBEDTLS_RSA_CRYPT 2 /**< Identifier for RSA encryption and decryption operations. */
...@@ -76,14 +82,14 @@ ...@@ -76,14 +82,14 @@
* eg for alternative (PKCS#11) RSA implemenations in the PK layers. * eg for alternative (PKCS#11) RSA implemenations in the PK layers.
*/ */
#if !defined(MBEDTLS_RSA_ALT)
// Regular implementation
//
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
#endif #endif
#if !defined(MBEDTLS_RSA_ALT)
// Regular implementation
//
/** /**
* \brief The RSA context structure. * \brief The RSA context structure.
* *
...@@ -91,29 +97,29 @@ extern "C" { ...@@ -91,29 +97,29 @@ extern "C" {
* is deprecated. All manipulation should instead be done through * is deprecated. All manipulation should instead be done through
* the public interface functions. * the public interface functions.
*/ */
typedef struct typedef struct mbedtls_rsa_context
{ {
int ver; /*!< Always 0.*/ int ver; /*!< Always 0.*/
size_t len; /*!< The size of \p N in Bytes. */ size_t len; /*!< The size of \p N in Bytes. */
mbedtls_mpi N; /*!< The public modulus. */ mbedtls_mpi N; /*!< The public modulus. */
mbedtls_mpi E; /*!< The public exponent. */ mbedtls_mpi E; /*!< The public exponent. */
mbedtls_mpi D; /*!< The private exponent. */ mbedtls_mpi D; /*!< The private exponent. */
mbedtls_mpi P; /*!< The first prime factor. */ mbedtls_mpi P; /*!< The first prime factor. */
mbedtls_mpi Q; /*!< The second prime factor. */ mbedtls_mpi Q; /*!< The second prime factor. */
mbedtls_mpi DP; /*!< \p D % (P - 1) */ mbedtls_mpi DP; /*!< <code>D % (P - 1)</code>. */
mbedtls_mpi DQ; /*!< \p D % (Q - 1) */ mbedtls_mpi DQ; /*!< <code>D % (Q - 1)</code>. */
mbedtls_mpi QP; /*!< 1 / (Q % P) */ mbedtls_mpi QP; /*!< <code>1 / (Q % P)</code>. */
mbedtls_mpi RN; /*!< cached R^2 mod \p N */ mbedtls_mpi RN; /*!< cached <code>R^2 mod N</code>. */
mbedtls_mpi RP; /*!< cached R^2 mod \p P */ mbedtls_mpi RP; /*!< cached <code>R^2 mod P</code>. */
mbedtls_mpi RQ; /*!< cached R^2 mod \p Q */ mbedtls_mpi RQ; /*!< cached <code>R^2 mod Q</code>. */
mbedtls_mpi Vi; /*!< The cached blinding value. */ mbedtls_mpi Vi; /*!< The cached blinding value. */
mbedtls_mpi Vf; /*!< The cached un-blinding value. */ mbedtls_mpi Vf; /*!< The cached un-blinding value. */
int padding; /*!< Selects padding mode: int padding; /*!< Selects padding mode:
#MBEDTLS_RSA_PKCS_V15 for 1.5 padding and #MBEDTLS_RSA_PKCS_V15 for 1.5 padding and
...@@ -128,47 +134,45 @@ typedef struct ...@@ -128,47 +134,45 @@ typedef struct
} }
mbedtls_rsa_context; mbedtls_rsa_context;
#else /* MBEDTLS_RSA_ALT */
#include "rsa_alt.h"
#endif /* MBEDTLS_RSA_ALT */
/** /**
* \brief This function initializes an RSA context. * \brief This function initializes an RSA context.
* *
* \note Set padding to #MBEDTLS_RSA_PKCS_V21 for the RSAES-OAEP * \note Set padding to #MBEDTLS_RSA_PKCS_V21 for the RSAES-OAEP
* encryption scheme and the RSASSA-PSS signature scheme. * encryption scheme and the RSASSA-PSS signature scheme.
* *
* \param ctx The RSA context to initialize.
* \param padding Selects padding mode: #MBEDTLS_RSA_PKCS_V15 or
* #MBEDTLS_RSA_PKCS_V21.
* \param hash_id The hash identifier of #mbedtls_md_type_t type, if
* \p padding is #MBEDTLS_RSA_PKCS_V21.
*
* \note The \p hash_id parameter is ignored when using * \note The \p hash_id parameter is ignored when using
* #MBEDTLS_RSA_PKCS_V15 padding. * #MBEDTLS_RSA_PKCS_V15 padding.
* *
* \note The choice of padding mode is strictly enforced for private key * \note The choice of padding mode is strictly enforced for private key
* operations, since there might be security concerns in * operations, since there might be security concerns in
* mixing padding modes. For public key operations it is * mixing padding modes. For public key operations it is
* a default value, which can be overriden by calling specific * a default value, which can be overridden by calling specific
* \c rsa_rsaes_xxx or \c rsa_rsassa_xxx functions. * \c rsa_rsaes_xxx or \c rsa_rsassa_xxx functions.
* *
* \note The hash selected in \p hash_id is always used for OEAP * \note The hash selected in \p hash_id is always used for OEAP
* encryption. For PSS signatures, it is always used for * encryption. For PSS signatures, it is always used for
* making signatures, but can be overriden for verifying them. * making signatures, but can be overridden for verifying them.
* If set to #MBEDTLS_MD_NONE, it is always overriden. * If set to #MBEDTLS_MD_NONE, it is always overridden.
*
* \param ctx The RSA context to initialize. This must not be \c NULL.
* \param padding The padding mode to use. This must be either
* #MBEDTLS_RSA_PKCS_V15 or #MBEDTLS_RSA_PKCS_V21.
* \param hash_id The hash identifier of ::mbedtls_md_type_t type, if
* \p padding is #MBEDTLS_RSA_PKCS_V21. It is unused
* otherwise.
*/ */
void mbedtls_rsa_init( mbedtls_rsa_context *ctx, void mbedtls_rsa_init( mbedtls_rsa_context *ctx,
int padding, int padding,
int hash_id); int hash_id );
/** /**
* \brief This function imports a set of core parameters into an * \brief This function imports a set of core parameters into an
* RSA context. * RSA context.
* *
* \param ctx The initialized RSA context to store the parameters in.
* \param N The RSA modulus, or NULL.
* \param P The first prime factor of \p N, or NULL.
* \param Q The second prime factor of \p N, or NULL.
* \param D The private exponent, or NULL.
* \param E The public exponent, or NULL.
*
* \note This function can be called multiple times for successive * \note This function can be called multiple times for successive
* imports, if the parameters are not simultaneously present. * imports, if the parameters are not simultaneously present.
* *
...@@ -184,7 +188,15 @@ void mbedtls_rsa_init( mbedtls_rsa_context *ctx, ...@@ -184,7 +188,15 @@ void mbedtls_rsa_init( mbedtls_rsa_context *ctx,
* \note The imported parameters are copied and need not be preserved * \note The imported parameters are copied and need not be preserved
* for the lifetime of the RSA context being set up. * for the lifetime of the RSA context being set up.
* *
* \return \c 0 on success, or a non-zero error code on failure. * \param ctx The initialized RSA context to store the parameters in.
* \param N The RSA modulus. This may be \c NULL.
* \param P The first prime factor of \p N. This may be \c NULL.
* \param Q The second prime factor of \p N. This may be \c NULL.
* \param D The private exponent. This may be \c NULL.
* \param E The public exponent. This may be \c NULL.
*
* \return \c 0 on success.
* \return A non-zero error code on failure.
*/ */
int mbedtls_rsa_import( mbedtls_rsa_context *ctx, int mbedtls_rsa_import( mbedtls_rsa_context *ctx,
const mbedtls_mpi *N, const mbedtls_mpi *N,
...@@ -195,18 +207,6 @@ int mbedtls_rsa_import( mbedtls_rsa_context *ctx, ...@@ -195,18 +207,6 @@ int mbedtls_rsa_import( mbedtls_rsa_context *ctx,
* \brief This function imports core RSA parameters, in raw big-endian * \brief This function imports core RSA parameters, in raw big-endian
* binary format, into an RSA context. * binary format, into an RSA context.
* *
* \param ctx The initialized RSA context to store the parameters in.
* \param N The RSA modulus, or NULL.
* \param N_len The Byte length of \p N, ignored if \p N == NULL.
* \param P The first prime factor of \p N, or NULL.
* \param P_len The Byte length of \p P, ignored if \p P == NULL.
* \param Q The second prime factor of \p N, or NULL.
* \param Q_len The Byte length of \p Q, ignored if \p Q == NULL.
* \param D The private exponent, or NULL.
* \param D_len The Byte length of \p D, ignored if \p D == NULL.
* \param E The public exponent, or NULL.
* \param E_len The Byte length of \p E, ignored if \p E == NULL.
*
* \note This function can be called multiple times for successive * \note This function can be called multiple times for successive
* imports, if the parameters are not simultaneously present. * imports, if the parameters are not simultaneously present.
* *
...@@ -222,7 +222,20 @@ int mbedtls_rsa_import( mbedtls_rsa_context *ctx, ...@@ -222,7 +222,20 @@ int mbedtls_rsa_import( mbedtls_rsa_context *ctx,
* \note The imported parameters are copied and need not be preserved * \note The imported parameters are copied and need not be preserved
* for the lifetime of the RSA context being set up. * for the lifetime of the RSA context being set up.
* *
* \return \c 0 on success, or a non-zero error code on failure. * \param ctx The initialized RSA context to store the parameters in.
* \param N The RSA modulus. This may be \c NULL.
* \param N_len The Byte length of \p N; it is ignored if \p N == NULL.
* \param P The first prime factor of \p N. This may be \c NULL.
* \param P_len The Byte length of \p P; it ns ignored if \p P == NULL.
* \param Q The second prime factor of \p N. This may be \c NULL.
* \param Q_len The Byte length of \p Q; it is ignored if \p Q == NULL.
* \param D The private exponent. This may be \c NULL.
* \param D_len The Byte length of \p D; it is ignored if \p D == NULL.
* \param E The public exponent. This may be \c NULL.
* \param E_len The Byte length of \p E; it is ignored if \p E == NULL.
*
* \return \c 0 on success.
* \return A non-zero error code on failure.
*/ */
int mbedtls_rsa_import_raw( mbedtls_rsa_context *ctx, int mbedtls_rsa_import_raw( mbedtls_rsa_context *ctx,
unsigned char const *N, size_t N_len, unsigned char const *N, size_t N_len,
...@@ -250,17 +263,18 @@ int mbedtls_rsa_import_raw( mbedtls_rsa_context *ctx, ...@@ -250,17 +263,18 @@ int mbedtls_rsa_import_raw( mbedtls_rsa_context *ctx,
* the RSA context can be used for RSA operations without * the RSA context can be used for RSA operations without
* the risk of failure or crash. * the risk of failure or crash.
* *
* \param ctx The initialized RSA context holding imported parameters.
*
* \return \c 0 on success, or #MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the
* attempted derivations failed.
*
* \warning This function need not perform consistency checks * \warning This function need not perform consistency checks
* for the imported parameters. In particular, parameters that * for the imported parameters. In particular, parameters that
* are not needed by the implementation might be silently * are not needed by the implementation might be silently
* discarded and left unchecked. To check the consistency * discarded and left unchecked. To check the consistency
* of the key material, see mbedtls_rsa_check_privkey(). * of the key material, see mbedtls_rsa_check_privkey().
* *
* \param ctx The initialized RSA context holding imported parameters.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the attempted derivations
* failed.
*
*/ */
int mbedtls_rsa_complete( mbedtls_rsa_context *ctx ); int mbedtls_rsa_complete( mbedtls_rsa_context *ctx );
...@@ -273,7 +287,7 @@ int mbedtls_rsa_complete( mbedtls_rsa_context *ctx ); ...@@ -273,7 +287,7 @@ int mbedtls_rsa_complete( mbedtls_rsa_context *ctx );
* zero Bytes. * zero Bytes.
* *
* Possible reasons for returning * Possible reasons for returning
* #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION:<ul> * #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED:<ul>
* <li>An alternative RSA implementation is in use, which * <li>An alternative RSA implementation is in use, which
* stores the key externally, and either cannot or should * stores the key externally, and either cannot or should
* not export it into RAM.</li> * not export it into RAM.</li>
...@@ -286,17 +300,22 @@ int mbedtls_rsa_complete( mbedtls_rsa_context *ctx ); ...@@ -286,17 +300,22 @@ int mbedtls_rsa_complete( mbedtls_rsa_context *ctx );
* the RSA context stays intact and remains usable. * the RSA context stays intact and remains usable.
* *
* \param ctx The initialized RSA context. * \param ctx The initialized RSA context.
* \param N The MPI to hold the RSA modulus, or NULL. * \param N The MPI to hold the RSA modulus.
* \param P The MPI to hold the first prime factor of \p N, or NULL. * This may be \c NULL if this field need not be exported.
* \param Q The MPI to hold the second prime factor of \p N, or NULL. * \param P The MPI to hold the first prime factor of \p N.
* \param D The MPI to hold the private exponent, or NULL. * This may be \c NULL if this field need not be exported.
* \param E The MPI to hold the public exponent, or NULL. * \param Q The MPI to hold the second prime factor of \p N.
* * This may be \c NULL if this field need not be exported.
* \return \c 0 on success, * \param D The MPI to hold the private exponent.
* #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the * This may be \c NULL if this field need not be exported.
* \param E The MPI to hold the public exponent.
* This may be \c NULL if this field need not be exported.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED if exporting the
* requested parameters cannot be done due to missing * requested parameters cannot be done due to missing
* functionality or because of security policies, * functionality or because of security policies.
* or a non-zero return code on any other failure. * \return A non-zero return code on any other failure.
* *
*/ */
int mbedtls_rsa_export( const mbedtls_rsa_context *ctx, int mbedtls_rsa_export( const mbedtls_rsa_context *ctx,
...@@ -313,7 +332,7 @@ int mbedtls_rsa_export( const mbedtls_rsa_context *ctx, ...@@ -313,7 +332,7 @@ int mbedtls_rsa_export( const mbedtls_rsa_context *ctx,
* zero Bytes. * zero Bytes.
* *
* Possible reasons for returning * Possible reasons for returning
* #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION:<ul> * #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED:<ul>
* <li>An alternative RSA implementation is in use, which * <li>An alternative RSA implementation is in use, which
* stores the key externally, and either cannot or should * stores the key externally, and either cannot or should
* not export it into RAM.</li> * not export it into RAM.</li>
...@@ -324,28 +343,31 @@ int mbedtls_rsa_export( const mbedtls_rsa_context *ctx, ...@@ -324,28 +343,31 @@ int mbedtls_rsa_export( const mbedtls_rsa_context *ctx,
* If the function fails due to an unsupported operation, * If the function fails due to an unsupported operation,
* the RSA context stays intact and remains usable. * the RSA context stays intact and remains usable.
* *
* \note The length parameters are ignored if the corresponding
* buffer pointers are NULL.
*
* \param ctx The initialized RSA context. * \param ctx The initialized RSA context.
* \param N The Byte array to store the RSA modulus, or NULL. * \param N The Byte array to store the RSA modulus,
* or \c NULL if this field need not be exported.
* \param N_len The size of the buffer for the modulus. * \param N_len The size of the buffer for the modulus.
* \param P The Byte array to hold the first prime factor of \p N, or * \param P The Byte array to hold the first prime factor of \p N,
* NULL. * or \c NULL if this field need not be exported.
* \param P_len The size of the buffer for the first prime factor. * \param P_len The size of the buffer for the first prime factor.
* \param Q The Byte array to hold the second prime factor of \p N, or * \param Q The Byte array to hold the second prime factor of \p N,
NULL. * or \c NULL if this field need not be exported.
* \param Q_len The size of the buffer for the second prime factor. * \param Q_len The size of the buffer for the second prime factor.
* \param D The Byte array to hold the private exponent, or NULL. * \param D The Byte array to hold the private exponent,
* or \c NULL if this field need not be exported.
* \param D_len The size of the buffer for the private exponent. * \param D_len The size of the buffer for the private exponent.
* \param E The Byte array to hold the public exponent, or NULL. * \param E The Byte array to hold the public exponent,
* or \c NULL if this field need not be exported.
* \param E_len The size of the buffer for the public exponent. * \param E_len The size of the buffer for the public exponent.
* *
* \note The length fields are ignored if the corresponding * \return \c 0 on success.
* buffer pointers are NULL. * \return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED if exporting the
*
* \return \c 0 on success,
* #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the
* requested parameters cannot be done due to missing * requested parameters cannot be done due to missing
* functionality or because of security policies, * functionality or because of security policies.
* or a non-zero return code on any other failure. * \return A non-zero return code on any other failure.
*/ */
int mbedtls_rsa_export_raw( const mbedtls_rsa_context *ctx, int mbedtls_rsa_export_raw( const mbedtls_rsa_context *ctx,
unsigned char *N, size_t N_len, unsigned char *N, size_t N_len,
...@@ -357,17 +379,21 @@ int mbedtls_rsa_export_raw( const mbedtls_rsa_context *ctx, ...@@ -357,17 +379,21 @@ int mbedtls_rsa_export_raw( const mbedtls_rsa_context *ctx,
/** /**
* \brief This function exports CRT parameters of a private RSA key. * \brief This function exports CRT parameters of a private RSA key.
* *
* \param ctx The initialized RSA context.
* \param DP The MPI to hold D modulo P-1, or NULL.
* \param DQ The MPI to hold D modulo Q-1, or NULL.
* \param QP The MPI to hold modular inverse of Q modulo P, or NULL.
*
* \return \c 0 on success, non-zero error code otherwise.
*
* \note Alternative RSA implementations not using CRT-parameters * \note Alternative RSA implementations not using CRT-parameters
* internally can implement this function based on * internally can implement this function based on
* mbedtls_rsa_deduce_opt(). * mbedtls_rsa_deduce_opt().
* *
* \param ctx The initialized RSA context.
* \param DP The MPI to hold \c D modulo `P-1`,
* or \c NULL if it need not be exported.
* \param DQ The MPI to hold \c D modulo `Q-1`,
* or \c NULL if it need not be exported.
* \param QP The MPI to hold modular inverse of \c Q modulo \c P,
* or \c NULL if it need not be exported.
*
* \return \c 0 on success.
* \return A non-zero error code on failure.
*
*/ */
int mbedtls_rsa_export_crt( const mbedtls_rsa_context *ctx, int mbedtls_rsa_export_crt( const mbedtls_rsa_context *ctx,
mbedtls_mpi *DP, mbedtls_mpi *DQ, mbedtls_mpi *QP ); mbedtls_mpi *DP, mbedtls_mpi *DQ, mbedtls_mpi *QP );
...@@ -376,13 +402,13 @@ int mbedtls_rsa_export_crt( const mbedtls_rsa_context *ctx, ...@@ -376,13 +402,13 @@ int mbedtls_rsa_export_crt( const mbedtls_rsa_context *ctx,
* \brief This function sets padding for an already initialized RSA * \brief This function sets padding for an already initialized RSA
* context. See mbedtls_rsa_init() for details. * context. See mbedtls_rsa_init() for details.
* *
* \param ctx The RSA context to be set. * \param ctx The initialized RSA context to be configured.
* \param padding Selects padding mode: #MBEDTLS_RSA_PKCS_V15 or * \param padding The padding mode to use. This must be either
* #MBEDTLS_RSA_PKCS_V21. * #MBEDTLS_RSA_PKCS_V15 or #MBEDTLS_RSA_PKCS_V21.
* \param hash_id The #MBEDTLS_RSA_PKCS_V21 hash identifier. * \param hash_id The #MBEDTLS_RSA_PKCS_V21 hash identifier.
*/ */
void mbedtls_rsa_set_padding( mbedtls_rsa_context *ctx, int padding, void mbedtls_rsa_set_padding( mbedtls_rsa_context *ctx, int padding,
int hash_id); int hash_id );
/** /**
* \brief This function retrieves the length of RSA modulus in Bytes. * \brief This function retrieves the length of RSA modulus in Bytes.
...@@ -397,17 +423,20 @@ size_t mbedtls_rsa_get_len( const mbedtls_rsa_context *ctx ); ...@@ -397,17 +423,20 @@ size_t mbedtls_rsa_get_len( const mbedtls_rsa_context *ctx );
/** /**
* \brief This function generates an RSA keypair. * \brief This function generates an RSA keypair.
* *
* \param ctx The RSA context used to hold the key.
* \param f_rng The RNG function.
* \param p_rng The RNG parameter.
* \param nbits The size of the public key in bits.
* \param exponent The public exponent. For example, 65537.
*
* \note mbedtls_rsa_init() must be called before this function, * \note mbedtls_rsa_init() must be called before this function,
* to set up the RSA context. * to set up the RSA context.
* *
* \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code * \param ctx The initialized RSA context used to hold the key.
on failure. * \param f_rng The RNG function to be used for key generation.
* This must not be \c NULL.
* \param p_rng The RNG context to be passed to \p f_rng.
* This may be \c NULL if \p f_rng doesn't need a context.
* \param nbits The size of the public key in bits.
* \param exponent The public exponent to use. For example, \c 65537.
* This must be odd and greater than \c 1.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/ */
int mbedtls_rsa_gen_key( mbedtls_rsa_context *ctx, int mbedtls_rsa_gen_key( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t), int (*f_rng)(void *, unsigned char *, size_t),
...@@ -422,10 +451,10 @@ int mbedtls_rsa_gen_key( mbedtls_rsa_context *ctx, ...@@ -422,10 +451,10 @@ int mbedtls_rsa_gen_key( mbedtls_rsa_context *ctx,
* enough information is present to perform an RSA public key * enough information is present to perform an RSA public key
* operation using mbedtls_rsa_public(). * operation using mbedtls_rsa_public().
* *
* \param ctx The RSA context to check. * \param ctx The initialized RSA context to check.
* *
* \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code * \return \c 0 on success.
* on failure. * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
* *
*/ */
int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx ); int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx );
...@@ -434,11 +463,6 @@ int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx ); ...@@ -434,11 +463,6 @@ int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx );
* \brief This function checks if a context contains an RSA private key * \brief This function checks if a context contains an RSA private key
* and perform basic consistency checks. * and perform basic consistency checks.
* *
* \param ctx The RSA context to check.
*
* \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code on
* failure.
*
* \note The consistency checks performed by this function not only * \note The consistency checks performed by this function not only
* ensure that mbedtls_rsa_private() can be called successfully * ensure that mbedtls_rsa_private() can be called successfully
* on the given context, but that the various parameters are * on the given context, but that the various parameters are
...@@ -465,6 +489,11 @@ int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx ); ...@@ -465,6 +489,11 @@ int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx );
* user to ensure the trustworthiness of the source of his RSA * user to ensure the trustworthiness of the source of his RSA
* parameters, which goes beyond what is effectively checkable * parameters, which goes beyond what is effectively checkable
* by the library.</li></ul> * by the library.</li></ul>
*
* \param ctx The initialized RSA context to check.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/ */
int mbedtls_rsa_check_privkey( const mbedtls_rsa_context *ctx ); int mbedtls_rsa_check_privkey( const mbedtls_rsa_context *ctx );
...@@ -473,11 +502,11 @@ int mbedtls_rsa_check_privkey( const mbedtls_rsa_context *ctx ); ...@@ -473,11 +502,11 @@ int mbedtls_rsa_check_privkey( const mbedtls_rsa_context *ctx );
* *
* It checks each of the contexts, and makes sure they match. * It checks each of the contexts, and makes sure they match.
* *
* \param pub The RSA context holding the public key. * \param pub The initialized RSA context holding the public key.
* \param prv The RSA context holding the private key. * \param prv The initialized RSA context holding the private key.
* *
* \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code * \return \c 0 on success.
* on failure. * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/ */
int mbedtls_rsa_check_pub_priv( const mbedtls_rsa_context *pub, int mbedtls_rsa_check_pub_priv( const mbedtls_rsa_context *pub,
const mbedtls_rsa_context *prv ); const mbedtls_rsa_context *prv );
...@@ -485,20 +514,21 @@ int mbedtls_rsa_check_pub_priv( const mbedtls_rsa_context *pub, ...@@ -485,20 +514,21 @@ int mbedtls_rsa_check_pub_priv( const mbedtls_rsa_context *pub,
/** /**
* \brief This function performs an RSA public key operation. * \brief This function performs an RSA public key operation.
* *
* \param ctx The RSA context. * \param ctx The initialized RSA context to use.
* \param input The input buffer. * \param input The input buffer. This must be a readable buffer
* \param output The output buffer. * of length \c ctx->len Bytes. For example, \c 256 Bytes
* * for an 2048-bit RSA modulus.
* \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code * \param output The output buffer. This must be a writable buffer
* on failure. * of length \c ctx->len Bytes. For example, \c 256 Bytes
* for an 2048-bit RSA modulus.
* *
* \note This function does not handle message padding. * \note This function does not handle message padding.
* *
* \note Make sure to set \p input[0] = 0 or ensure that * \note Make sure to set \p input[0] = 0 or ensure that
* input is smaller than \p N. * input is smaller than \p N.
* *
* \note The input and output buffers must be large * \return \c 0 on success.
* enough. For example, 128 Bytes if RSA-1024 is used. * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/ */
int mbedtls_rsa_public( mbedtls_rsa_context *ctx, int mbedtls_rsa_public( mbedtls_rsa_context *ctx,
const unsigned char *input, const unsigned char *input,
...@@ -507,18 +537,6 @@ int mbedtls_rsa_public( mbedtls_rsa_context *ctx, ...@@ -507,18 +537,6 @@ int mbedtls_rsa_public( mbedtls_rsa_context *ctx,
/** /**
* \brief This function performs an RSA private key operation. * \brief This function performs an RSA private key operation.
* *
* \param ctx The RSA context.
* \param f_rng The RNG function. Needed for blinding.
* \param p_rng The RNG parameter.
* \param input The input buffer.
* \param output The output buffer.
*
* \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
* on failure.
*
* \note The input and output buffers must be large
* enough. For example, 128 Bytes if RSA-1024 is used.
*
* \note Blinding is used if and only if a PRNG is provided. * \note Blinding is used if and only if a PRNG is provided.
* *
* \note If blinding is used, both the base of exponentation * \note If blinding is used, both the base of exponentation
...@@ -530,6 +548,22 @@ int mbedtls_rsa_public( mbedtls_rsa_context *ctx, ...@@ -530,6 +548,22 @@ int mbedtls_rsa_public( mbedtls_rsa_context *ctx,
* Future versions of the library may enforce the presence * Future versions of the library may enforce the presence
* of a PRNG. * of a PRNG.
* *
* \param ctx The initialized RSA context to use.
* \param f_rng The RNG function, used for blinding. It is discouraged
* and deprecated to pass \c NULL here, in which case
* blinding will be omitted.
* \param p_rng The RNG context to pass to \p f_rng. This may be \c NULL
* if \p f_rng is \c NULL or if \p f_rng doesn't need a context.
* \param input The input buffer. This must be a readable buffer
* of length \c ctx->len Bytes. For example, \c 256 Bytes
* for an 2048-bit RSA modulus.
* \param output The output buffer. This must be a writable buffer
* of length \c ctx->len Bytes. For example, \c 256 Bytes
* for an 2048-bit RSA modulus.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*
*/ */
int mbedtls_rsa_private( mbedtls_rsa_context *ctx, int mbedtls_rsa_private( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t), int (*f_rng)(void *, unsigned char *, size_t),
...@@ -544,16 +578,6 @@ int mbedtls_rsa_private( mbedtls_rsa_context *ctx, ...@@ -544,16 +578,6 @@ int mbedtls_rsa_private( mbedtls_rsa_context *ctx,
* It is the generic wrapper for performing a PKCS#1 encryption * It is the generic wrapper for performing a PKCS#1 encryption
* operation using the \p mode from the context. * operation using the \p mode from the context.
* *
*
* \param ctx The RSA context.
* \param f_rng The RNG function. Needed for padding, PKCS#1 v2.1
* encoding, and #MBEDTLS_RSA_PRIVATE.
* \param p_rng The RNG parameter.
* \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
* \param ilen The length of the plaintext.
* \param input The buffer holding the data to encrypt.
* \param output The buffer used to hold the ciphertext.
*
* \deprecated It is deprecated and discouraged to call this function * \deprecated It is deprecated and discouraged to call this function
* in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
* are likely to remove the \p mode argument and have it * are likely to remove the \p mode argument and have it
...@@ -561,13 +585,29 @@ int mbedtls_rsa_private( mbedtls_rsa_context *ctx, ...@@ -561,13 +585,29 @@ int mbedtls_rsa_private( mbedtls_rsa_context *ctx,
* *
* \note Alternative implementations of RSA need not support * \note Alternative implementations of RSA need not support
* mode being set to #MBEDTLS_RSA_PRIVATE and might instead * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
* return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
* *
* \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code * \param ctx The initialized RSA context to use.
* on failure. * \param f_rng The RNG to use. It is mandatory for PKCS#1 v2.1 padding
* * encoding, and for PKCS#1 v1.5 padding encoding when used
* \note The input and output buffers must be as large as the size * with \p mode set to #MBEDTLS_RSA_PUBLIC. For PKCS#1 v1.5
* of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. * padding encoding and \p mode set to #MBEDTLS_RSA_PRIVATE,
* it is used for blinding and should be provided in this
* case; see mbedtls_rsa_private() for more.
* \param p_rng The RNG context to be passed to \p f_rng. May be
* \c NULL if \p f_rng is \c NULL or if \p f_rng doesn't
* need a context argument.
* \param mode The mode of operation. This must be either
* #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).
* \param ilen The length of the plaintext in Bytes.
* \param input The input data to encrypt. This must be a readable
* buffer of size \p ilen Bytes. This must not be \c NULL.
* \param output The output buffer. This must be a writable buffer
* of length \c ctx->len Bytes. For example, \c 256 Bytes
* for an 2048-bit RSA modulus.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/ */
int mbedtls_rsa_pkcs1_encrypt( mbedtls_rsa_context *ctx, int mbedtls_rsa_pkcs1_encrypt( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t), int (*f_rng)(void *, unsigned char *, size_t),
...@@ -580,15 +620,6 @@ int mbedtls_rsa_pkcs1_encrypt( mbedtls_rsa_context *ctx, ...@@ -580,15 +620,6 @@ int mbedtls_rsa_pkcs1_encrypt( mbedtls_rsa_context *ctx,
* \brief This function performs a PKCS#1 v1.5 encryption operation * \brief This function performs a PKCS#1 v1.5 encryption operation
* (RSAES-PKCS1-v1_5-ENCRYPT). * (RSAES-PKCS1-v1_5-ENCRYPT).
* *
* \param ctx The RSA context.
* \param f_rng The RNG function. Needed for padding and
* #MBEDTLS_RSA_PRIVATE.
* \param p_rng The RNG parameter.
* \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
* \param ilen The length of the plaintext.
* \param input The buffer holding the data to encrypt.
* \param output The buffer used to hold the ciphertext.
*
* \deprecated It is deprecated and discouraged to call this function * \deprecated It is deprecated and discouraged to call this function
* in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
* are likely to remove the \p mode argument and have it * are likely to remove the \p mode argument and have it
...@@ -596,13 +627,27 @@ int mbedtls_rsa_pkcs1_encrypt( mbedtls_rsa_context *ctx, ...@@ -596,13 +627,27 @@ int mbedtls_rsa_pkcs1_encrypt( mbedtls_rsa_context *ctx,
* *
* \note Alternative implementations of RSA need not support * \note Alternative implementations of RSA need not support
* mode being set to #MBEDTLS_RSA_PRIVATE and might instead * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
* return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
* *
* \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code * \param ctx The initialized RSA context to use.
* on failure. * \param f_rng The RNG function to use. It is needed for padding generation
* * if \p mode is #MBEDTLS_RSA_PUBLIC. If \p mode is
* \note The output buffer must be as large as the size * #MBEDTLS_RSA_PRIVATE (discouraged), it is used for
* of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. * blinding and should be provided; see mbedtls_rsa_private().
* \param p_rng The RNG context to be passed to \p f_rng. This may
* be \c NULL if \p f_rng is \c NULL or if \p f_rng
* doesn't need a context argument.
* \param mode The mode of operation. This must be either
* #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).
* \param ilen The length of the plaintext in Bytes.
* \param input The input data to encrypt. This must be a readable
* buffer of size \p ilen Bytes. This must not be \c NULL.
* \param output The output buffer. This must be a writable buffer
* of length \c ctx->len Bytes. For example, \c 256 Bytes
* for an 2048-bit RSA modulus.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/ */
int mbedtls_rsa_rsaes_pkcs1_v15_encrypt( mbedtls_rsa_context *ctx, int mbedtls_rsa_rsaes_pkcs1_v15_encrypt( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t), int (*f_rng)(void *, unsigned char *, size_t),
...@@ -615,31 +660,38 @@ int mbedtls_rsa_rsaes_pkcs1_v15_encrypt( mbedtls_rsa_context *ctx, ...@@ -615,31 +660,38 @@ int mbedtls_rsa_rsaes_pkcs1_v15_encrypt( mbedtls_rsa_context *ctx,
* \brief This function performs a PKCS#1 v2.1 OAEP encryption * \brief This function performs a PKCS#1 v2.1 OAEP encryption
* operation (RSAES-OAEP-ENCRYPT). * operation (RSAES-OAEP-ENCRYPT).
* *
* \param ctx The RSA context. * \note The output buffer must be as large as the size
* \param f_rng The RNG function. Needed for padding and PKCS#1 v2.1 * of ctx->N. For example, 128 Bytes if RSA-1024 is used.
* encoding and #MBEDTLS_RSA_PRIVATE. *
* \param p_rng The RNG parameter. * \deprecated It is deprecated and discouraged to call this function
* \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
* are likely to remove the \p mode argument and have it
* implicitly set to #MBEDTLS_RSA_PUBLIC.
*
* \note Alternative implementations of RSA need not support
* mode being set to #MBEDTLS_RSA_PRIVATE and might instead
* return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
*
* \param ctx The initnialized RSA context to use.
* \param f_rng The RNG function to use. This is needed for padding
* generation and must be provided.
* \param p_rng The RNG context to be passed to \p f_rng. This may
* be \c NULL if \p f_rng doesn't need a context argument.
* \param mode The mode of operation. This must be either
* #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).
* \param label The buffer holding the custom label to use. * \param label The buffer holding the custom label to use.
* \param label_len The length of the label. * This must be a readable buffer of length \p label_len
* \param ilen The length of the plaintext. * Bytes. It may be \c NULL if \p label_len is \c 0.
* \param input The buffer holding the data to encrypt. * \param label_len The length of the label in Bytes.
* \param output The buffer used to hold the ciphertext. * \param ilen The length of the plaintext buffer \p input in Bytes.
* * \param input The input data to encrypt. This must be a readable
* \deprecated It is deprecated and discouraged to call this function * buffer of size \p ilen Bytes. This must not be \c NULL.
* in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library * \param output The output buffer. This must be a writable buffer
* are likely to remove the \p mode argument and have it * of length \c ctx->len Bytes. For example, \c 256 Bytes
* implicitly set to #MBEDTLS_RSA_PUBLIC. * for an 2048-bit RSA modulus.
* *
* \note Alternative implementations of RSA need not support * \return \c 0 on success.
* mode being set to #MBEDTLS_RSA_PRIVATE and might instead * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
* return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
*
* \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
* on failure.
*
* \note The output buffer must be as large as the size
* of ctx->N. For example, 128 Bytes if RSA-1024 is used.
*/ */
int mbedtls_rsa_rsaes_oaep_encrypt( mbedtls_rsa_context *ctx, int mbedtls_rsa_rsaes_oaep_encrypt( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t), int (*f_rng)(void *, unsigned char *, size_t),
...@@ -657,14 +709,12 @@ int mbedtls_rsa_rsaes_oaep_encrypt( mbedtls_rsa_context *ctx, ...@@ -657,14 +709,12 @@ int mbedtls_rsa_rsaes_oaep_encrypt( mbedtls_rsa_context *ctx,
* It is the generic wrapper for performing a PKCS#1 decryption * It is the generic wrapper for performing a PKCS#1 decryption
* operation using the \p mode from the context. * operation using the \p mode from the context.
* *
* \param ctx The RSA context. * \note The output buffer length \c output_max_len should be
* \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. * as large as the size \p ctx->len of \p ctx->N (for example,
* \param p_rng The RNG parameter. * 128 Bytes if RSA-1024 is used) to be able to hold an
* \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. * arbitrary decrypted message. If it is not large enough to
* \param olen The length of the plaintext. * hold the decryption of the particular ciphertext provided,
* \param input The buffer holding the encrypted data. * the function returns \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
* \param output The buffer used to hold the plaintext.
* \param output_max_len The maximum length of the output buffer.
* *
* \deprecated It is deprecated and discouraged to call this function * \deprecated It is deprecated and discouraged to call this function
* in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
...@@ -673,20 +723,28 @@ int mbedtls_rsa_rsaes_oaep_encrypt( mbedtls_rsa_context *ctx, ...@@ -673,20 +723,28 @@ int mbedtls_rsa_rsaes_oaep_encrypt( mbedtls_rsa_context *ctx,
* *
* \note Alternative implementations of RSA need not support * \note Alternative implementations of RSA need not support
* mode being set to #MBEDTLS_RSA_PUBLIC and might instead * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
* return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
* *
* \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code * \param ctx The initialized RSA context to use.
* on failure. * \param f_rng The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE,
* * this is used for blinding and should be provided; see
* \note The output buffer length \c output_max_len should be * mbedtls_rsa_private() for more. If \p mode is
* as large as the size \p ctx->len of \p ctx->N (for example, * #MBEDTLS_RSA_PUBLIC, it is ignored.
* 128 Bytes if RSA-1024 is used) to be able to hold an * \param p_rng The RNG context to be passed to \p f_rng. This may be
* arbitrary decrypted message. If it is not large enough to * \c NULL if \p f_rng is \c NULL or doesn't need a context.
* hold the decryption of the particular ciphertext provided, * \param mode The mode of operation. This must be either
* the function returns \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE. * #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).
* * \param olen The address at which to store the length of
* \note The input buffer must be as large as the size * the plaintext. This must not be \c NULL.
* of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. * \param input The ciphertext buffer. This must be a readable buffer
* of length \c ctx->len Bytes. For example, \c 256 Bytes
* for an 2048-bit RSA modulus.
* \param output The buffer used to hold the plaintext. This must
* be a writable buffer of length \p output_max_len Bytes.
* \param output_max_len The length in Bytes of the output buffer \p output.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/ */
int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx, int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t), int (*f_rng)(void *, unsigned char *, size_t),
...@@ -700,14 +758,12 @@ int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx, ...@@ -700,14 +758,12 @@ int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx,
* \brief This function performs a PKCS#1 v1.5 decryption * \brief This function performs a PKCS#1 v1.5 decryption
* operation (RSAES-PKCS1-v1_5-DECRYPT). * operation (RSAES-PKCS1-v1_5-DECRYPT).
* *
* \param ctx The RSA context. * \note The output buffer length \c output_max_len should be
* \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. * as large as the size \p ctx->len of \p ctx->N, for example,
* \param p_rng The RNG parameter. * 128 Bytes if RSA-1024 is used, to be able to hold an
* \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. * arbitrary decrypted message. If it is not large enough to
* \param olen The length of the plaintext. * hold the decryption of the particular ciphertext provided,
* \param input The buffer holding the encrypted data. * the function returns #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
* \param output The buffer to hold the plaintext.
* \param output_max_len The maximum length of the output buffer.
* *
* \deprecated It is deprecated and discouraged to call this function * \deprecated It is deprecated and discouraged to call this function
* in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
...@@ -716,20 +772,29 @@ int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx, ...@@ -716,20 +772,29 @@ int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx,
* *
* \note Alternative implementations of RSA need not support * \note Alternative implementations of RSA need not support
* mode being set to #MBEDTLS_RSA_PUBLIC and might instead * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
* return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
* *
* \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code * \param ctx The initialized RSA context to use.
* on failure. * \param f_rng The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE,
* this is used for blinding and should be provided; see
* mbedtls_rsa_private() for more. If \p mode is
* #MBEDTLS_RSA_PUBLIC, it is ignored.
* \param p_rng The RNG context to be passed to \p f_rng. This may be
* \c NULL if \p f_rng is \c NULL or doesn't need a context.
* \param mode The mode of operation. This must be either
* #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).
* \param olen The address at which to store the length of
* the plaintext. This must not be \c NULL.
* \param input The ciphertext buffer. This must be a readable buffer
* of length \c ctx->len Bytes. For example, \c 256 Bytes
* for an 2048-bit RSA modulus.
* \param output The buffer used to hold the plaintext. This must
* be a writable buffer of length \p output_max_len Bytes.
* \param output_max_len The length in Bytes of the output buffer \p output.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
* *
* \note The output buffer length \c output_max_len should be
* as large as the size \p ctx->len of \p ctx->N, for example,
* 128 Bytes if RSA-1024 is used, to be able to hold an
* arbitrary decrypted message. If it is not large enough to
* hold the decryption of the particular ciphertext provided,
* the function returns #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
*
* \note The input buffer must be as large as the size
* of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
*/ */
int mbedtls_rsa_rsaes_pkcs1_v15_decrypt( mbedtls_rsa_context *ctx, int mbedtls_rsa_rsaes_pkcs1_v15_decrypt( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t), int (*f_rng)(void *, unsigned char *, size_t),
...@@ -740,42 +805,50 @@ int mbedtls_rsa_rsaes_pkcs1_v15_decrypt( mbedtls_rsa_context *ctx, ...@@ -740,42 +805,50 @@ int mbedtls_rsa_rsaes_pkcs1_v15_decrypt( mbedtls_rsa_context *ctx,
size_t output_max_len ); size_t output_max_len );
/** /**
* \brief This function performs a PKCS#1 v2.1 OAEP decryption * \brief This function performs a PKCS#1 v2.1 OAEP decryption
* operation (RSAES-OAEP-DECRYPT). * operation (RSAES-OAEP-DECRYPT).
* *
* \param ctx The RSA context. * \note The output buffer length \c output_max_len should be
* \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. * as large as the size \p ctx->len of \p ctx->N, for
* \param p_rng The RNG parameter. * example, 128 Bytes if RSA-1024 is used, to be able to
* \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. * hold an arbitrary decrypted message. If it is not
* large enough to hold the decryption of the particular
* ciphertext provided, the function returns
* #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
*
* \deprecated It is deprecated and discouraged to call this function
* in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
* are likely to remove the \p mode argument and have it
* implicitly set to #MBEDTLS_RSA_PRIVATE.
*
* \note Alternative implementations of RSA need not support
* mode being set to #MBEDTLS_RSA_PUBLIC and might instead
* return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
*
* \param ctx The initialized RSA context to use.
* \param f_rng The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE,
* this is used for blinding and should be provided; see
* mbedtls_rsa_private() for more. If \p mode is
* #MBEDTLS_RSA_PUBLIC, it is ignored.
* \param p_rng The RNG context to be passed to \p f_rng. This may be
* \c NULL if \p f_rng is \c NULL or doesn't need a context.
* \param mode The mode of operation. This must be either
* #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).
* \param label The buffer holding the custom label to use. * \param label The buffer holding the custom label to use.
* \param label_len The length of the label. * This must be a readable buffer of length \p label_len
* \param olen The length of the plaintext. * Bytes. It may be \c NULL if \p label_len is \c 0.
* \param input The buffer holding the encrypted data. * \param label_len The length of the label in Bytes.
* \param output The buffer to hold the plaintext. * \param olen The address at which to store the length of
* \param output_max_len The maximum length of the output buffer. * the plaintext. This must not be \c NULL.
* * \param input The ciphertext buffer. This must be a readable buffer
* \deprecated It is deprecated and discouraged to call this function * of length \c ctx->len Bytes. For example, \c 256 Bytes
* in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library * for an 2048-bit RSA modulus.
* are likely to remove the \p mode argument and have it * \param output The buffer used to hold the plaintext. This must
* implicitly set to #MBEDTLS_RSA_PRIVATE. * be a writable buffer of length \p output_max_len Bytes.
* * \param output_max_len The length in Bytes of the output buffer \p output.
* \note Alternative implementations of RSA need not support *
* mode being set to #MBEDTLS_RSA_PUBLIC and might instead * \return \c 0 on success.
* return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*
* \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
* on failure.
*
* \note The output buffer length \c output_max_len should be
* as large as the size \p ctx->len of \p ctx->N, for
* example, 128 Bytes if RSA-1024 is used, to be able to
* hold an arbitrary decrypted message. If it is not
* large enough to hold the decryption of the particular
* ciphertext provided, the function returns
* #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
*
* \note The input buffer must be as large as the size
* of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
*/ */
int mbedtls_rsa_rsaes_oaep_decrypt( mbedtls_rsa_context *ctx, int mbedtls_rsa_rsaes_oaep_decrypt( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t), int (*f_rng)(void *, unsigned char *, size_t),
...@@ -794,16 +867,12 @@ int mbedtls_rsa_rsaes_oaep_decrypt( mbedtls_rsa_context *ctx, ...@@ -794,16 +867,12 @@ int mbedtls_rsa_rsaes_oaep_decrypt( mbedtls_rsa_context *ctx,
* It is the generic wrapper for performing a PKCS#1 * It is the generic wrapper for performing a PKCS#1
* signature using the \p mode from the context. * signature using the \p mode from the context.
* *
* \param ctx The RSA context. * \note The \p sig buffer must be as large as the size
* \param f_rng The RNG function. Needed for PKCS#1 v2.1 encoding and for * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
* #MBEDTLS_RSA_PRIVATE. *
* \param p_rng The RNG parameter. * \note For PKCS#1 v2.1 encoding, see comments on
* \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. * mbedtls_rsa_rsassa_pss_sign() for details on
* \param md_alg The message-digest algorithm used to hash the original data. * \p md_alg and \p hash_id.
* Use #MBEDTLS_MD_NONE for signing raw data.
* \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
* \param hash The buffer holding the message digest.
* \param sig The buffer to hold the ciphertext.
* *
* \deprecated It is deprecated and discouraged to call this function * \deprecated It is deprecated and discouraged to call this function
* in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
...@@ -812,17 +881,34 @@ int mbedtls_rsa_rsaes_oaep_decrypt( mbedtls_rsa_context *ctx, ...@@ -812,17 +881,34 @@ int mbedtls_rsa_rsaes_oaep_decrypt( mbedtls_rsa_context *ctx,
* *
* \note Alternative implementations of RSA need not support * \note Alternative implementations of RSA need not support
* mode being set to #MBEDTLS_RSA_PUBLIC and might instead * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
* return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
* *
* \return \c 0 if the signing operation was successful, * \param ctx The initialized RSA context to use.
* or an \c MBEDTLS_ERR_RSA_XXX error code on failure. * \param f_rng The RNG function to use. If the padding mode is PKCS#1 v2.1,
* * this must be provided. If the padding mode is PKCS#1 v1.5 and
* \note The \p sig buffer must be as large as the size * \p mode is #MBEDTLS_RSA_PRIVATE, it is used for blinding
* of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. * and should be provided; see mbedtls_rsa_private() for more
* * more. It is ignored otherwise.
* \note For PKCS#1 v2.1 encoding, see comments on * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL
* mbedtls_rsa_rsassa_pss_sign() for details on * if \p f_rng is \c NULL or doesn't need a context argument.
* \p md_alg and \p hash_id. * \param mode The mode of operation. This must be either
* #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).
* \param md_alg The message-digest algorithm used to hash the original data.
* Use #MBEDTLS_MD_NONE for signing raw data.
* \param hashlen The length of the message digest.
* Ths is only used if \p md_alg is #MBEDTLS_MD_NONE.
* \param hash The buffer holding the message digest or raw data.
* If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
* buffer of length \p hashlen Bytes. If \p md_alg is not
* #MBEDTLS_MD_NONE, it must be a readable buffer of length
* the size of the hash corresponding to \p md_alg.
* \param sig The buffer to hold the signature. This must be a writable
* buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
* for an 2048-bit RSA modulus. A buffer length of
* #MBEDTLS_MPI_MAX_SIZE is always safe.
*
* \return \c 0 if the signing operation was successful.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/ */
int mbedtls_rsa_pkcs1_sign( mbedtls_rsa_context *ctx, int mbedtls_rsa_pkcs1_sign( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t), int (*f_rng)(void *, unsigned char *, size_t),
...@@ -837,16 +923,6 @@ int mbedtls_rsa_pkcs1_sign( mbedtls_rsa_context *ctx, ...@@ -837,16 +923,6 @@ int mbedtls_rsa_pkcs1_sign( mbedtls_rsa_context *ctx,
* \brief This function performs a PKCS#1 v1.5 signature * \brief This function performs a PKCS#1 v1.5 signature
* operation (RSASSA-PKCS1-v1_5-SIGN). * operation (RSASSA-PKCS1-v1_5-SIGN).
* *
* \param ctx The RSA context.
* \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
* \param p_rng The RNG parameter.
* \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
* \param md_alg The message-digest algorithm used to hash the original data.
* Use #MBEDTLS_MD_NONE for signing raw data.
* \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
* \param hash The buffer holding the message digest.
* \param sig The buffer to hold the ciphertext.
*
* \deprecated It is deprecated and discouraged to call this function * \deprecated It is deprecated and discouraged to call this function
* in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
* are likely to remove the \p mode argument and have it * are likely to remove the \p mode argument and have it
...@@ -854,14 +930,33 @@ int mbedtls_rsa_pkcs1_sign( mbedtls_rsa_context *ctx, ...@@ -854,14 +930,33 @@ int mbedtls_rsa_pkcs1_sign( mbedtls_rsa_context *ctx,
* *
* \note Alternative implementations of RSA need not support * \note Alternative implementations of RSA need not support
* mode being set to #MBEDTLS_RSA_PUBLIC and might instead * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
* return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
* *
* \return \c 0 if the signing operation was successful, * \param ctx The initialized RSA context to use.
* or an \c MBEDTLS_ERR_RSA_XXX error code * \param f_rng The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE,
* on failure. * this is used for blinding and should be provided; see
* * mbedtls_rsa_private() for more. If \p mode is
* \note The \p sig buffer must be as large as the size * #MBEDTLS_RSA_PUBLIC, it is ignored.
* of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL
* if \p f_rng is \c NULL or doesn't need a context argument.
* \param mode The mode of operation. This must be either
* #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).
* \param md_alg The message-digest algorithm used to hash the original data.
* Use #MBEDTLS_MD_NONE for signing raw data.
* \param hashlen The length of the message digest.
* Ths is only used if \p md_alg is #MBEDTLS_MD_NONE.
* \param hash The buffer holding the message digest or raw data.
* If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
* buffer of length \p hashlen Bytes. If \p md_alg is not
* #MBEDTLS_MD_NONE, it must be a readable buffer of length
* the size of the hash corresponding to \p md_alg.
* \param sig The buffer to hold the signature. This must be a writable
* buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
* for an 2048-bit RSA modulus. A buffer length of
* #MBEDTLS_MPI_MAX_SIZE is always safe.
*
* \return \c 0 if the signing operation was successful.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/ */
int mbedtls_rsa_rsassa_pkcs1_v15_sign( mbedtls_rsa_context *ctx, int mbedtls_rsa_rsassa_pkcs1_v15_sign( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t), int (*f_rng)(void *, unsigned char *, size_t),
...@@ -876,16 +971,22 @@ int mbedtls_rsa_rsassa_pkcs1_v15_sign( mbedtls_rsa_context *ctx, ...@@ -876,16 +971,22 @@ int mbedtls_rsa_rsassa_pkcs1_v15_sign( mbedtls_rsa_context *ctx,
* \brief This function performs a PKCS#1 v2.1 PSS signature * \brief This function performs a PKCS#1 v2.1 PSS signature
* operation (RSASSA-PSS-SIGN). * operation (RSASSA-PSS-SIGN).
* *
* \param ctx The RSA context. * \note The \p hash_id in the RSA context is the one used for the
* \param f_rng The RNG function. Needed for PKCS#1 v2.1 encoding and for * encoding. \p md_alg in the function call is the type of hash
* #MBEDTLS_RSA_PRIVATE. * that is encoded. According to <em>RFC-3447: Public-Key
* \param p_rng The RNG parameter. * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography
* \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. * Specifications</em> it is advised to keep both hashes the
* \param md_alg The message-digest algorithm used to hash the original data. * same.
* Use #MBEDTLS_MD_NONE for signing raw data. *
* \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE. * \note This function always uses the maximum possible salt size,
* \param hash The buffer holding the message digest. * up to the length of the payload hash. This choice of salt
* \param sig The buffer to hold the ciphertext. * size complies with FIPS 186-4 §5.5 (e) and RFC 8017 (PKCS#1
* v2.2) §9.1.1 step 3. Furthermore this function enforces a
* minimum salt size which is the hash size minus 2 bytes. If
* this minimum size is too large given the key size (the salt
* size, plus the hash size, plus 2 bytes must be no more than
* the key size in bytes), this function returns
* #MBEDTLS_ERR_RSA_BAD_INPUT_DATA.
* *
* \deprecated It is deprecated and discouraged to call this function * \deprecated It is deprecated and discouraged to call this function
* in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
...@@ -894,21 +995,30 @@ int mbedtls_rsa_rsassa_pkcs1_v15_sign( mbedtls_rsa_context *ctx, ...@@ -894,21 +995,30 @@ int mbedtls_rsa_rsassa_pkcs1_v15_sign( mbedtls_rsa_context *ctx,
* *
* \note Alternative implementations of RSA need not support * \note Alternative implementations of RSA need not support
* mode being set to #MBEDTLS_RSA_PUBLIC and might instead * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
* return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
* *
* \return \c 0 if the signing operation was successful, * \param ctx The initialized RSA context to use.
* or an \c MBEDTLS_ERR_RSA_XXX error code * \param f_rng The RNG function. It must not be \c NULL.
* on failure. * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL
* * if \p f_rng doesn't need a context argument.
* \note The \p sig buffer must be as large as the size * \param mode The mode of operation. This must be either
* of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. * #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).
* * \param md_alg The message-digest algorithm used to hash the original data.
* \note The \p hash_id in the RSA context is the one used for the * Use #MBEDTLS_MD_NONE for signing raw data.
* encoding. \p md_alg in the function call is the type of hash * \param hashlen The length of the message digest.
* that is encoded. According to <em>RFC-3447: Public-Key * Ths is only used if \p md_alg is #MBEDTLS_MD_NONE.
* Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography * \param hash The buffer holding the message digest or raw data.
* Specifications</em> it is advised to keep both hashes the * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
* same. * buffer of length \p hashlen Bytes. If \p md_alg is not
* #MBEDTLS_MD_NONE, it must be a readable buffer of length
* the size of the hash corresponding to \p md_alg.
* \param sig The buffer to hold the signature. This must be a writable
* buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
* for an 2048-bit RSA modulus. A buffer length of
* #MBEDTLS_MPI_MAX_SIZE is always safe.
*
* \return \c 0 if the signing operation was successful.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/ */
int mbedtls_rsa_rsassa_pss_sign( mbedtls_rsa_context *ctx, int mbedtls_rsa_rsassa_pss_sign( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t), int (*f_rng)(void *, unsigned char *, size_t),
...@@ -926,15 +1036,9 @@ int mbedtls_rsa_rsassa_pss_sign( mbedtls_rsa_context *ctx, ...@@ -926,15 +1036,9 @@ int mbedtls_rsa_rsassa_pss_sign( mbedtls_rsa_context *ctx,
* This is the generic wrapper for performing a PKCS#1 * This is the generic wrapper for performing a PKCS#1
* verification using the mode from the context. * verification using the mode from the context.
* *
* \param ctx The RSA public key context. * \note For PKCS#1 v2.1 encoding, see comments on
* \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. * mbedtls_rsa_rsassa_pss_verify() about \p md_alg and
* \param p_rng The RNG parameter. * \p hash_id.
* \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
* \param md_alg The message-digest algorithm used to hash the original data.
* Use #MBEDTLS_MD_NONE for signing raw data.
* \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
* \param hash The buffer holding the message digest.
* \param sig The buffer holding the ciphertext.
* *
* \deprecated It is deprecated and discouraged to call this function * \deprecated It is deprecated and discouraged to call this function
* in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
...@@ -943,18 +1047,31 @@ int mbedtls_rsa_rsassa_pss_sign( mbedtls_rsa_context *ctx, ...@@ -943,18 +1047,31 @@ int mbedtls_rsa_rsassa_pss_sign( mbedtls_rsa_context *ctx,
* *
* \note Alternative implementations of RSA need not support * \note Alternative implementations of RSA need not support
* mode being set to #MBEDTLS_RSA_PRIVATE and might instead * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
* return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
* *
* \return \c 0 if the verify operation was successful, * \param ctx The initialized RSA public key context to use.
* or an \c MBEDTLS_ERR_RSA_XXX error code * \param f_rng The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE,
* on failure. * this is used for blinding and should be provided; see
* * mbedtls_rsa_private() for more. Otherwise, it is ignored.
* \note The \p sig buffer must be as large as the size * \param p_rng The RNG context to be passed to \p f_rng. This may be
* of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. * \c NULL if \p f_rng is \c NULL or doesn't need a context.
* * \param mode The mode of operation. This must be either
* \note For PKCS#1 v2.1 encoding, see comments on * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).
* mbedtls_rsa_rsassa_pss_verify() about \p md_alg and * \param md_alg The message-digest algorithm used to hash the original data.
* \p hash_id. * Use #MBEDTLS_MD_NONE for signing raw data.
* \param hashlen The length of the message digest.
* This is only used if \p md_alg is #MBEDTLS_MD_NONE.
* \param hash The buffer holding the message digest or raw data.
* If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
* buffer of length \p hashlen Bytes. If \p md_alg is not
* #MBEDTLS_MD_NONE, it must be a readable buffer of length
* the size of the hash corresponding to \p md_alg.
* \param sig The buffer holding the signature. This must be a readable
* buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
* for an 2048-bit RSA modulus.
*
* \return \c 0 if the verify operation was successful.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/ */
int mbedtls_rsa_pkcs1_verify( mbedtls_rsa_context *ctx, int mbedtls_rsa_pkcs1_verify( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t), int (*f_rng)(void *, unsigned char *, size_t),
...@@ -969,16 +1086,6 @@ int mbedtls_rsa_pkcs1_verify( mbedtls_rsa_context *ctx, ...@@ -969,16 +1086,6 @@ int mbedtls_rsa_pkcs1_verify( mbedtls_rsa_context *ctx,
* \brief This function performs a PKCS#1 v1.5 verification * \brief This function performs a PKCS#1 v1.5 verification
* operation (RSASSA-PKCS1-v1_5-VERIFY). * operation (RSASSA-PKCS1-v1_5-VERIFY).
* *
* \param ctx The RSA public key context.
* \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
* \param p_rng The RNG parameter.
* \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
* \param md_alg The message-digest algorithm used to hash the original data.
* Use #MBEDTLS_MD_NONE for signing raw data.
* \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
* \param hash The buffer holding the message digest.
* \param sig The buffer holding the ciphertext.
*
* \deprecated It is deprecated and discouraged to call this function * \deprecated It is deprecated and discouraged to call this function
* in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
* are likely to remove the \p mode argument and have it * are likely to remove the \p mode argument and have it
...@@ -986,14 +1093,31 @@ int mbedtls_rsa_pkcs1_verify( mbedtls_rsa_context *ctx, ...@@ -986,14 +1093,31 @@ int mbedtls_rsa_pkcs1_verify( mbedtls_rsa_context *ctx,
* *
* \note Alternative implementations of RSA need not support * \note Alternative implementations of RSA need not support
* mode being set to #MBEDTLS_RSA_PRIVATE and might instead * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
* return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
* *
* \return \c 0 if the verify operation was successful, * \param ctx The initialized RSA public key context to use.
* or an \c MBEDTLS_ERR_RSA_XXX error code * \param f_rng The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE,
* on failure. * this is used for blinding and should be provided; see
* * mbedtls_rsa_private() for more. Otherwise, it is ignored.
* \note The \p sig buffer must be as large as the size * \param p_rng The RNG context to be passed to \p f_rng. This may be
* of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. * \c NULL if \p f_rng is \c NULL or doesn't need a context.
* \param mode The mode of operation. This must be either
* #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).
* \param md_alg The message-digest algorithm used to hash the original data.
* Use #MBEDTLS_MD_NONE for signing raw data.
* \param hashlen The length of the message digest.
* This is only used if \p md_alg is #MBEDTLS_MD_NONE.
* \param hash The buffer holding the message digest or raw data.
* If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
* buffer of length \p hashlen Bytes. If \p md_alg is not
* #MBEDTLS_MD_NONE, it must be a readable buffer of length
* the size of the hash corresponding to \p md_alg.
* \param sig The buffer holding the signature. This must be a readable
* buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
* for an 2048-bit RSA modulus.
*
* \return \c 0 if the verify operation was successful.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/ */
int mbedtls_rsa_rsassa_pkcs1_v15_verify( mbedtls_rsa_context *ctx, int mbedtls_rsa_rsassa_pkcs1_v15_verify( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t), int (*f_rng)(void *, unsigned char *, size_t),
...@@ -1011,15 +1135,13 @@ int mbedtls_rsa_rsassa_pkcs1_v15_verify( mbedtls_rsa_context *ctx, ...@@ -1011,15 +1135,13 @@ int mbedtls_rsa_rsassa_pkcs1_v15_verify( mbedtls_rsa_context *ctx,
* The hash function for the MGF mask generating function * The hash function for the MGF mask generating function
* is that specified in the RSA context. * is that specified in the RSA context.
* *
* \param ctx The RSA public key context. * \note The \p hash_id in the RSA context is the one used for the
* \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. * verification. \p md_alg in the function call is the type of
* \param p_rng The RNG parameter. * hash that is verified. According to <em>RFC-3447: Public-Key
* \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography
* \param md_alg The message-digest algorithm used to hash the original data. * Specifications</em> it is advised to keep both hashes the
* Use #MBEDTLS_MD_NONE for signing raw data. * same. If \p hash_id in the RSA context is unset,
* \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE. * the \p md_alg from the function call is used.
* \param hash The buffer holding the message digest.
* \param sig The buffer holding the ciphertext.
* *
* \deprecated It is deprecated and discouraged to call this function * \deprecated It is deprecated and discouraged to call this function
* in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
...@@ -1028,22 +1150,31 @@ int mbedtls_rsa_rsassa_pkcs1_v15_verify( mbedtls_rsa_context *ctx, ...@@ -1028,22 +1150,31 @@ int mbedtls_rsa_rsassa_pkcs1_v15_verify( mbedtls_rsa_context *ctx,
* *
* \note Alternative implementations of RSA need not support * \note Alternative implementations of RSA need not support
* mode being set to #MBEDTLS_RSA_PRIVATE and might instead * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
* return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
* *
* \return \c 0 if the verify operation was successful, * \param ctx The initialized RSA public key context to use.
* or an \c MBEDTLS_ERR_RSA_XXX error code * \param f_rng The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE,
* on failure. * this is used for blinding and should be provided; see
* * mbedtls_rsa_private() for more. Otherwise, it is ignored.
* \note The \p sig buffer must be as large as the size * \param p_rng The RNG context to be passed to \p f_rng. This may be
* of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. * \c NULL if \p f_rng is \c NULL or doesn't need a context.
* * \param mode The mode of operation. This must be either
* \note The \p hash_id in the RSA context is the one used for the * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).
* verification. \p md_alg in the function call is the type of * \param md_alg The message-digest algorithm used to hash the original data.
* hash that is verified. According to <em>RFC-3447: Public-Key * Use #MBEDTLS_MD_NONE for signing raw data.
* Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography * \param hashlen The length of the message digest.
* Specifications</em> it is advised to keep both hashes the * This is only used if \p md_alg is #MBEDTLS_MD_NONE.
* same. If \p hash_id in the RSA context is unset, * \param hash The buffer holding the message digest or raw data.
* the \p md_alg from the function call is used. * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
* buffer of length \p hashlen Bytes. If \p md_alg is not
* #MBEDTLS_MD_NONE, it must be a readable buffer of length
* the size of the hash corresponding to \p md_alg.
* \param sig The buffer holding the signature. This must be a readable
* buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
* for an 2048-bit RSA modulus.
*
* \return \c 0 if the verify operation was successful.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/ */
int mbedtls_rsa_rsassa_pss_verify( mbedtls_rsa_context *ctx, int mbedtls_rsa_rsassa_pss_verify( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t), int (*f_rng)(void *, unsigned char *, size_t),
...@@ -1061,27 +1192,37 @@ int mbedtls_rsa_rsassa_pss_verify( mbedtls_rsa_context *ctx, ...@@ -1061,27 +1192,37 @@ int mbedtls_rsa_rsassa_pss_verify( mbedtls_rsa_context *ctx,
* The hash function for the MGF mask generating function * The hash function for the MGF mask generating function
* is that specified in \p mgf1_hash_id. * is that specified in \p mgf1_hash_id.
* *
* \param ctx The RSA public key context.
* \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
* \param p_rng The RNG parameter.
* \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
* \param md_alg The message-digest algorithm used to hash the original data.
* Use #MBEDTLS_MD_NONE for signing raw data.
* \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
* \param hash The buffer holding the message digest.
* \param mgf1_hash_id The message digest used for mask generation.
* \param expected_salt_len The length of the salt used in padding. Use
* #MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length.
* \param sig The buffer holding the ciphertext.
*
* \return \c 0 if the verify operation was successful,
* or an \c MBEDTLS_ERR_RSA_XXX error code
* on failure.
*
* \note The \p sig buffer must be as large as the size * \note The \p sig buffer must be as large as the size
* of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
* *
* \note The \p hash_id in the RSA context is ignored. * \note The \p hash_id in the RSA context is ignored.
*
* \param ctx The initialized RSA public key context to use.
* \param f_rng The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE,
* this is used for blinding and should be provided; see
* mbedtls_rsa_private() for more. Otherwise, it is ignored.
* \param p_rng The RNG context to be passed to \p f_rng. This may be
* \c NULL if \p f_rng is \c NULL or doesn't need a context.
* \param mode The mode of operation. This must be either
* #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
* \param md_alg The message-digest algorithm used to hash the original data.
* Use #MBEDTLS_MD_NONE for signing raw data.
* \param hashlen The length of the message digest.
* This is only used if \p md_alg is #MBEDTLS_MD_NONE.
* \param hash The buffer holding the message digest or raw data.
* If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
* buffer of length \p hashlen Bytes. If \p md_alg is not
* #MBEDTLS_MD_NONE, it must be a readable buffer of length
* the size of the hash corresponding to \p md_alg.
* \param mgf1_hash_id The message digest used for mask generation.
* \param expected_salt_len The length of the salt used in padding. Use
* #MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length.
* \param sig The buffer holding the signature. This must be a readable
* buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
* for an 2048-bit RSA modulus.
*
* \return \c 0 if the verify operation was successful.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/ */
int mbedtls_rsa_rsassa_pss_verify_ext( mbedtls_rsa_context *ctx, int mbedtls_rsa_rsassa_pss_verify_ext( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t), int (*f_rng)(void *, unsigned char *, size_t),
...@@ -1097,40 +1238,35 @@ int mbedtls_rsa_rsassa_pss_verify_ext( mbedtls_rsa_context *ctx, ...@@ -1097,40 +1238,35 @@ int mbedtls_rsa_rsassa_pss_verify_ext( mbedtls_rsa_context *ctx,
/** /**
* \brief This function copies the components of an RSA context. * \brief This function copies the components of an RSA context.
* *
* \param dst The destination context. * \param dst The destination context. This must be initialized.
* \param src The source context. * \param src The source context. This must be initialized.
* *
* \return \c 0 on success, * \return \c 0 on success.
* #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure.
*/ */
int mbedtls_rsa_copy( mbedtls_rsa_context *dst, const mbedtls_rsa_context *src ); int mbedtls_rsa_copy( mbedtls_rsa_context *dst, const mbedtls_rsa_context *src );
/** /**
* \brief This function frees the components of an RSA key. * \brief This function frees the components of an RSA key.
* *
* \param ctx The RSA Context to free. * \param ctx The RSA context to free. May be \c NULL, in which case
* this function is a no-op. If it is not \c NULL, it must
* point to an initialized RSA context.
*/ */
void mbedtls_rsa_free( mbedtls_rsa_context *ctx ); void mbedtls_rsa_free( mbedtls_rsa_context *ctx );
#ifdef __cplusplus #if defined(MBEDTLS_SELF_TEST)
}
#endif
#else /* MBEDTLS_RSA_ALT */
#include "rsa_alt.h"
#endif /* MBEDTLS_RSA_ALT */
#ifdef __cplusplus
extern "C" {
#endif
/** /**
* \brief The RSA checkup routine. * \brief The RSA checkup routine.
* *
* \return \c 0 on success, or \c 1 on failure. * \return \c 0 on success.
* \return \c 1 on failure.
*/ */
int mbedtls_rsa_self_test( int verbose ); int mbedtls_rsa_self_test( int verbose );
#endif /* MBEDTLS_SELF_TEST */
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif
......
/** /**
* \file sha1.h * \file sha1.h
* *
* \brief The SHA-1 cryptographic hash function. * \brief This file contains SHA-1 definitions and functions.
*
* The Secure Hash Algorithm 1 (SHA-1) cryptographic hash function is defined in
* <em>FIPS 180-4: Secure Hash Standard (SHS)</em>.
* *
* \warning SHA-1 is considered a weak message digest and its use constitutes * \warning SHA-1 is considered a weak message digest and its use constitutes
* a security risk. We recommend considering stronger message * a security risk. We recommend considering stronger message
...@@ -37,16 +40,18 @@ ...@@ -37,16 +40,18 @@
#include <stddef.h> #include <stddef.h>
#include <stdint.h> #include <stdint.h>
/* MBEDTLS_ERR_SHA1_HW_ACCEL_FAILED is deprecated and should not be used. */
#define MBEDTLS_ERR_SHA1_HW_ACCEL_FAILED -0x0035 /**< SHA-1 hardware accelerator failed */ #define MBEDTLS_ERR_SHA1_HW_ACCEL_FAILED -0x0035 /**< SHA-1 hardware accelerator failed */
#define MBEDTLS_ERR_SHA1_BAD_INPUT_DATA -0x0073 /**< SHA-1 input data was malformed. */
#if !defined(MBEDTLS_SHA1_ALT)
// Regular implementation
//
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
#endif #endif
#if !defined(MBEDTLS_SHA1_ALT)
// Regular implementation
//
/** /**
* \brief The SHA-1 context structure. * \brief The SHA-1 context structure.
* *
...@@ -55,7 +60,7 @@ extern "C" { ...@@ -55,7 +60,7 @@ extern "C" {
* stronger message digests instead. * stronger message digests instead.
* *
*/ */
typedef struct typedef struct mbedtls_sha1_context
{ {
uint32_t total[2]; /*!< The number of Bytes processed. */ uint32_t total[2]; /*!< The number of Bytes processed. */
uint32_t state[5]; /*!< The intermediate digest state. */ uint32_t state[5]; /*!< The intermediate digest state. */
...@@ -63,40 +68,48 @@ typedef struct ...@@ -63,40 +68,48 @@ typedef struct
} }
mbedtls_sha1_context; mbedtls_sha1_context;
#else /* MBEDTLS_SHA1_ALT */
#include "sha1_alt.h"
#endif /* MBEDTLS_SHA1_ALT */
/** /**
* \brief This function initializes a SHA-1 context. * \brief This function initializes a SHA-1 context.
* *
* \param ctx The SHA-1 context to initialize.
*
* \warning SHA-1 is considered a weak message digest and its use * \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering * constitutes a security risk. We recommend considering
* stronger message digests instead. * stronger message digests instead.
* *
* \param ctx The SHA-1 context to initialize.
* This must not be \c NULL.
*
*/ */
void mbedtls_sha1_init( mbedtls_sha1_context *ctx ); void mbedtls_sha1_init( mbedtls_sha1_context *ctx );
/** /**
* \brief This function clears a SHA-1 context. * \brief This function clears a SHA-1 context.
* *
* \param ctx The SHA-1 context to clear.
*
* \warning SHA-1 is considered a weak message digest and its use * \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering * constitutes a security risk. We recommend considering
* stronger message digests instead. * stronger message digests instead.
* *
* \param ctx The SHA-1 context to clear. This may be \c NULL,
* in which case this function does nothing. If it is
* not \c NULL, it must point to an initialized
* SHA-1 context.
*
*/ */
void mbedtls_sha1_free( mbedtls_sha1_context *ctx ); void mbedtls_sha1_free( mbedtls_sha1_context *ctx );
/** /**
* \brief This function clones the state of a SHA-1 context. * \brief This function clones the state of a SHA-1 context.
* *
* \param dst The destination context.
* \param src The context to clone.
*
* \warning SHA-1 is considered a weak message digest and its use * \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering * constitutes a security risk. We recommend considering
* stronger message digests instead. * stronger message digests instead.
* *
* \param dst The SHA-1 context to clone to. This must be initialized.
* \param src The SHA-1 context to clone from. This must be initialized.
*
*/ */
void mbedtls_sha1_clone( mbedtls_sha1_context *dst, void mbedtls_sha1_clone( mbedtls_sha1_context *dst,
const mbedtls_sha1_context *src ); const mbedtls_sha1_context *src );
...@@ -104,14 +117,15 @@ void mbedtls_sha1_clone( mbedtls_sha1_context *dst, ...@@ -104,14 +117,15 @@ void mbedtls_sha1_clone( mbedtls_sha1_context *dst,
/** /**
* \brief This function starts a SHA-1 checksum calculation. * \brief This function starts a SHA-1 checksum calculation.
* *
* \param ctx The context to initialize.
*
* \return \c 0 if successful
*
* \warning SHA-1 is considered a weak message digest and its use * \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering * constitutes a security risk. We recommend considering
* stronger message digests instead. * stronger message digests instead.
* *
* \param ctx The SHA-1 context to initialize. This must be initialized.
*
* \return \c 0 on success.
* \return A negative error code on failure.
*
*/ */
int mbedtls_sha1_starts_ret( mbedtls_sha1_context *ctx ); int mbedtls_sha1_starts_ret( mbedtls_sha1_context *ctx );
...@@ -119,16 +133,18 @@ int mbedtls_sha1_starts_ret( mbedtls_sha1_context *ctx ); ...@@ -119,16 +133,18 @@ int mbedtls_sha1_starts_ret( mbedtls_sha1_context *ctx );
* \brief This function feeds an input buffer into an ongoing SHA-1 * \brief This function feeds an input buffer into an ongoing SHA-1
* checksum calculation. * checksum calculation.
* *
* \param ctx The SHA-1 context.
* \param input The buffer holding the input data.
* \param ilen The length of the input data.
*
* \return \c 0 if successful
*
* \warning SHA-1 is considered a weak message digest and its use * \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering * constitutes a security risk. We recommend considering
* stronger message digests instead. * stronger message digests instead.
* *
* \param ctx The SHA-1 context. This must be initialized
* and have a hash operation started.
* \param input The buffer holding the input data.
* This must be a readable buffer of length \p ilen Bytes.
* \param ilen The length of the input data \p input in Bytes.
*
* \return \c 0 on success.
* \return A negative error code on failure.
*/ */
int mbedtls_sha1_update_ret( mbedtls_sha1_context *ctx, int mbedtls_sha1_update_ret( mbedtls_sha1_context *ctx,
const unsigned char *input, const unsigned char *input,
...@@ -138,31 +154,35 @@ int mbedtls_sha1_update_ret( mbedtls_sha1_context *ctx, ...@@ -138,31 +154,35 @@ int mbedtls_sha1_update_ret( mbedtls_sha1_context *ctx,
* \brief This function finishes the SHA-1 operation, and writes * \brief This function finishes the SHA-1 operation, and writes
* the result to the output buffer. * the result to the output buffer.
* *
* \param ctx The SHA-1 context.
* \param output The SHA-1 checksum result.
*
* \return \c 0 if successful
*
* \warning SHA-1 is considered a weak message digest and its use * \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering * constitutes a security risk. We recommend considering
* stronger message digests instead. * stronger message digests instead.
* *
* \param ctx The SHA-1 context to use. This must be initialized and
* have a hash operation started.
* \param output The SHA-1 checksum result. This must be a writable
* buffer of length \c 20 Bytes.
*
* \return \c 0 on success.
* \return A negative error code on failure.
*/ */
int mbedtls_sha1_finish_ret( mbedtls_sha1_context *ctx, int mbedtls_sha1_finish_ret( mbedtls_sha1_context *ctx,
unsigned char output[20] ); unsigned char output[20] );
/** /**
* \brief SHA-1 process data block (internal use only) * \brief SHA-1 process data block (internal use only).
*
* \param ctx SHA-1 context
* \param data The data block being processed.
*
* \return \c 0 if successful
* *
* \warning SHA-1 is considered a weak message digest and its use * \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering * constitutes a security risk. We recommend considering
* stronger message digests instead. * stronger message digests instead.
* *
* \param ctx The SHA-1 context to use. This must be initialized.
* \param data The data block being processed. This must be a
* readable buffer of length \c 64 Bytes.
*
* \return \c 0 on success.
* \return A negative error code on failure.
*
*/ */
int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx, int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx,
const unsigned char data[64] ); const unsigned char data[64] );
...@@ -174,65 +194,71 @@ int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx, ...@@ -174,65 +194,71 @@ int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx,
#define MBEDTLS_DEPRECATED #define MBEDTLS_DEPRECATED
#endif #endif
/** /**
* \brief SHA-1 context setup * \brief This function starts a SHA-1 checksum calculation.
*
* \deprecated Superseded by mbedtls_sha1_starts_ret() in 2.7.0
*
* \param ctx The SHA-1 context to be initialized.
* *
* \warning SHA-1 is considered a weak message digest and its use * \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering * constitutes a security risk. We recommend considering
* stronger message digests instead. * stronger message digests instead.
* *
* \deprecated Superseded by mbedtls_sha1_starts_ret() in 2.7.0.
*
* \param ctx The SHA-1 context to initialize. This must be initialized.
*
*/ */
MBEDTLS_DEPRECATED void mbedtls_sha1_starts( mbedtls_sha1_context *ctx ); MBEDTLS_DEPRECATED void mbedtls_sha1_starts( mbedtls_sha1_context *ctx );
/** /**
* \brief SHA-1 process buffer * \brief This function feeds an input buffer into an ongoing SHA-1
* * checksum calculation.
* \deprecated Superseded by mbedtls_sha1_update_ret() in 2.7.0
*
* \param ctx The SHA-1 context.
* \param input The buffer holding the input data.
* \param ilen The length of the input data.
* *
* \warning SHA-1 is considered a weak message digest and its use * \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering * constitutes a security risk. We recommend considering
* stronger message digests instead. * stronger message digests instead.
* *
* \deprecated Superseded by mbedtls_sha1_update_ret() in 2.7.0.
*
* \param ctx The SHA-1 context. This must be initialized and
* have a hash operation started.
* \param input The buffer holding the input data.
* This must be a readable buffer of length \p ilen Bytes.
* \param ilen The length of the input data \p input in Bytes.
*
*/ */
MBEDTLS_DEPRECATED void mbedtls_sha1_update( mbedtls_sha1_context *ctx, MBEDTLS_DEPRECATED void mbedtls_sha1_update( mbedtls_sha1_context *ctx,
const unsigned char *input, const unsigned char *input,
size_t ilen ); size_t ilen );
/** /**
* \brief SHA-1 final digest * \brief This function finishes the SHA-1 operation, and writes
* * the result to the output buffer.
* \deprecated Superseded by mbedtls_sha1_finish_ret() in 2.7.0
*
* \param ctx The SHA-1 context.
* \param output The SHA-1 checksum result.
* *
* \warning SHA-1 is considered a weak message digest and its use * \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering * constitutes a security risk. We recommend considering
* stronger message digests instead. * stronger message digests instead.
* *
* \deprecated Superseded by mbedtls_sha1_finish_ret() in 2.7.0.
*
* \param ctx The SHA-1 context. This must be initialized and
* have a hash operation started.
* \param output The SHA-1 checksum result.
* This must be a writable buffer of length \c 20 Bytes.
*/ */
MBEDTLS_DEPRECATED void mbedtls_sha1_finish( mbedtls_sha1_context *ctx, MBEDTLS_DEPRECATED void mbedtls_sha1_finish( mbedtls_sha1_context *ctx,
unsigned char output[20] ); unsigned char output[20] );
/** /**
* \brief SHA-1 process data block (internal use only) * \brief SHA-1 process data block (internal use only).
*
* \deprecated Superseded by mbedtls_internal_sha1_process() in 2.7.0
*
* \param ctx The SHA-1 context.
* \param data The data block being processed.
* *
* \warning SHA-1 is considered a weak message digest and its use * \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering * constitutes a security risk. We recommend considering
* stronger message digests instead. * stronger message digests instead.
* *
* \deprecated Superseded by mbedtls_internal_sha1_process() in 2.7.0.
*
* \param ctx The SHA-1 context. This must be initialized.
* \param data The data block being processed.
* This must be a readable buffer of length \c 64 bytes.
*
*/ */
MBEDTLS_DEPRECATED void mbedtls_sha1_process( mbedtls_sha1_context *ctx, MBEDTLS_DEPRECATED void mbedtls_sha1_process( mbedtls_sha1_context *ctx,
const unsigned char data[64] ); const unsigned char data[64] );
...@@ -240,18 +266,6 @@ MBEDTLS_DEPRECATED void mbedtls_sha1_process( mbedtls_sha1_context *ctx, ...@@ -240,18 +266,6 @@ MBEDTLS_DEPRECATED void mbedtls_sha1_process( mbedtls_sha1_context *ctx,
#undef MBEDTLS_DEPRECATED #undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */ #endif /* !MBEDTLS_DEPRECATED_REMOVED */
#ifdef __cplusplus
}
#endif
#else /* MBEDTLS_SHA1_ALT */
#include "sha1_alt.h"
#endif /* MBEDTLS_SHA1_ALT */
#ifdef __cplusplus
extern "C" {
#endif
/** /**
* \brief This function calculates the SHA-1 checksum of a buffer. * \brief This function calculates the SHA-1 checksum of a buffer.
* *
...@@ -261,16 +275,19 @@ extern "C" { ...@@ -261,16 +275,19 @@ extern "C" {
* The SHA-1 result is calculated as * The SHA-1 result is calculated as
* output = SHA-1(input buffer). * output = SHA-1(input buffer).
* *
* \param input The buffer holding the input data.
* \param ilen The length of the input data.
* \param output The SHA-1 checksum result.
*
* \return \c 0 if successful
*
* \warning SHA-1 is considered a weak message digest and its use * \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering * constitutes a security risk. We recommend considering
* stronger message digests instead. * stronger message digests instead.
* *
* \param input The buffer holding the input data.
* This must be a readable buffer of length \p ilen Bytes.
* \param ilen The length of the input data \p input in Bytes.
* \param output The SHA-1 checksum result.
* This must be a writable buffer of length \c 20 Bytes.
*
* \return \c 0 on success.
* \return A negative error code on failure.
*
*/ */
int mbedtls_sha1_ret( const unsigned char *input, int mbedtls_sha1_ret( const unsigned char *input,
size_t ilen, size_t ilen,
...@@ -283,18 +300,26 @@ int mbedtls_sha1_ret( const unsigned char *input, ...@@ -283,18 +300,26 @@ int mbedtls_sha1_ret( const unsigned char *input,
#define MBEDTLS_DEPRECATED #define MBEDTLS_DEPRECATED
#endif #endif
/** /**
* \brief Output = SHA-1( input buffer ) * \brief This function calculates the SHA-1 checksum of a buffer.
* *
* \deprecated Superseded by mbedtls_sha1_ret() in 2.7.0 * The function allocates the context, performs the
* calculation, and frees the context.
* *
* \param input The buffer holding the input data. * The SHA-1 result is calculated as
* \param ilen The length of the input data. * output = SHA-1(input buffer).
* \param output The SHA-1 checksum result.
* *
* \warning SHA-1 is considered a weak message digest and its use * \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering * constitutes a security risk. We recommend considering
* stronger message digests instead. * stronger message digests instead.
* *
* \deprecated Superseded by mbedtls_sha1_ret() in 2.7.0
*
* \param input The buffer holding the input data.
* This must be a readable buffer of length \p ilen Bytes.
* \param ilen The length of the input data \p input in Bytes.
* \param output The SHA-1 checksum result. This must be a writable
* buffer of size \c 20 Bytes.
*
*/ */
MBEDTLS_DEPRECATED void mbedtls_sha1( const unsigned char *input, MBEDTLS_DEPRECATED void mbedtls_sha1( const unsigned char *input,
size_t ilen, size_t ilen,
...@@ -303,18 +328,23 @@ MBEDTLS_DEPRECATED void mbedtls_sha1( const unsigned char *input, ...@@ -303,18 +328,23 @@ MBEDTLS_DEPRECATED void mbedtls_sha1( const unsigned char *input,
#undef MBEDTLS_DEPRECATED #undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */ #endif /* !MBEDTLS_DEPRECATED_REMOVED */
#if defined(MBEDTLS_SELF_TEST)
/** /**
* \brief The SHA-1 checkup routine. * \brief The SHA-1 checkup routine.
* *
* \return \c 0 on success, or \c 1 on failure.
*
* \warning SHA-1 is considered a weak message digest and its use * \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering * constitutes a security risk. We recommend considering
* stronger message digests instead. * stronger message digests instead.
* *
* \return \c 0 on success.
* \return \c 1 on failure.
*
*/ */
int mbedtls_sha1_self_test( int verbose ); int mbedtls_sha1_self_test( int verbose );
#endif /* MBEDTLS_SELF_TEST */
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif
......
/** /**
* \file sha256.h * \file sha256.h
* *
* \brief The SHA-224 and SHA-256 cryptographic hash function. * \brief This file contains SHA-224 and SHA-256 definitions and functions.
*
* The Secure Hash Algorithms 224 and 256 (SHA-224 and SHA-256) cryptographic
* hash functions are defined in <em>FIPS 180-4: Secure Hash Standard (SHS)</em>.
*/ */
/* /*
* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
...@@ -33,16 +36,18 @@ ...@@ -33,16 +36,18 @@
#include <stddef.h> #include <stddef.h>
#include <stdint.h> #include <stdint.h>
/* MBEDTLS_ERR_SHA256_HW_ACCEL_FAILED is deprecated and should not be used. */
#define MBEDTLS_ERR_SHA256_HW_ACCEL_FAILED -0x0037 /**< SHA-256 hardware accelerator failed */ #define MBEDTLS_ERR_SHA256_HW_ACCEL_FAILED -0x0037 /**< SHA-256 hardware accelerator failed */
#define MBEDTLS_ERR_SHA256_BAD_INPUT_DATA -0x0074 /**< SHA-256 input data was malformed. */
#if !defined(MBEDTLS_SHA256_ALT)
// Regular implementation
//
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
#endif #endif
#if !defined(MBEDTLS_SHA256_ALT)
// Regular implementation
//
/** /**
* \brief The SHA-256 context structure. * \brief The SHA-256 context structure.
* *
...@@ -50,36 +55,41 @@ extern "C" { ...@@ -50,36 +55,41 @@ extern "C" {
* checksum calculations. The choice between these two is * checksum calculations. The choice between these two is
* made in the call to mbedtls_sha256_starts_ret(). * made in the call to mbedtls_sha256_starts_ret().
*/ */
typedef struct typedef struct mbedtls_sha256_context
{ {
uint32_t total[2]; /*!< The number of Bytes processed. */ uint32_t total[2]; /*!< The number of Bytes processed. */
uint32_t state[8]; /*!< The intermediate digest state. */ uint32_t state[8]; /*!< The intermediate digest state. */
unsigned char buffer[64]; /*!< The data block being processed. */ unsigned char buffer[64]; /*!< The data block being processed. */
int is224; /*!< Determines which function to use. int is224; /*!< Determines which function to use:
<ul><li>0: Use SHA-256.</li> 0: Use SHA-256, or 1: Use SHA-224. */
<li>1: Use SHA-224.</li></ul> */
} }
mbedtls_sha256_context; mbedtls_sha256_context;
#else /* MBEDTLS_SHA256_ALT */
#include "sha256_alt.h"
#endif /* MBEDTLS_SHA256_ALT */
/** /**
* \brief This function initializes a SHA-256 context. * \brief This function initializes a SHA-256 context.
* *
* \param ctx The SHA-256 context to initialize. * \param ctx The SHA-256 context to initialize. This must not be \c NULL.
*/ */
void mbedtls_sha256_init( mbedtls_sha256_context *ctx ); void mbedtls_sha256_init( mbedtls_sha256_context *ctx );
/** /**
* \brief This function clears a SHA-256 context. * \brief This function clears a SHA-256 context.
* *
* \param ctx The SHA-256 context to clear. * \param ctx The SHA-256 context to clear. This may be \c NULL, in which
* case this function returns immediately. If it is not \c NULL,
* it must point to an initialized SHA-256 context.
*/ */
void mbedtls_sha256_free( mbedtls_sha256_context *ctx ); void mbedtls_sha256_free( mbedtls_sha256_context *ctx );
/** /**
* \brief This function clones the state of a SHA-256 context. * \brief This function clones the state of a SHA-256 context.
* *
* \param dst The destination context. * \param dst The destination context. This must be initialized.
* \param src The context to clone. * \param src The context to clone. This must be initialized.
*/ */
void mbedtls_sha256_clone( mbedtls_sha256_context *dst, void mbedtls_sha256_clone( mbedtls_sha256_context *dst,
const mbedtls_sha256_context *src ); const mbedtls_sha256_context *src );
...@@ -88,12 +98,12 @@ void mbedtls_sha256_clone( mbedtls_sha256_context *dst, ...@@ -88,12 +98,12 @@ void mbedtls_sha256_clone( mbedtls_sha256_context *dst,
* \brief This function starts a SHA-224 or SHA-256 checksum * \brief This function starts a SHA-224 or SHA-256 checksum
* calculation. * calculation.
* *
* \param ctx The context to initialize. * \param ctx The context to use. This must be initialized.
* \param is224 Determines which function to use. * \param is224 This determines which function to use. This must be
* <ul><li>0: Use SHA-256.</li> * either \c 0 for SHA-256, or \c 1 for SHA-224.
* <li>1: Use SHA-224.</li></ul>
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return A negative error code on failure.
*/ */
int mbedtls_sha256_starts_ret( mbedtls_sha256_context *ctx, int is224 ); int mbedtls_sha256_starts_ret( mbedtls_sha256_context *ctx, int is224 );
...@@ -101,11 +111,14 @@ int mbedtls_sha256_starts_ret( mbedtls_sha256_context *ctx, int is224 ); ...@@ -101,11 +111,14 @@ int mbedtls_sha256_starts_ret( mbedtls_sha256_context *ctx, int is224 );
* \brief This function feeds an input buffer into an ongoing * \brief This function feeds an input buffer into an ongoing
* SHA-256 checksum calculation. * SHA-256 checksum calculation.
* *
* \param ctx SHA-256 context * \param ctx The SHA-256 context. This must be initialized
* \param input buffer holding the data * and have a hash operation started.
* \param ilen length of the input data * \param input The buffer holding the data. This must be a readable
* buffer of length \p ilen Bytes.
* \param ilen The length of the input data in Bytes.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return A negative error code on failure.
*/ */
int mbedtls_sha256_update_ret( mbedtls_sha256_context *ctx, int mbedtls_sha256_update_ret( mbedtls_sha256_context *ctx,
const unsigned char *input, const unsigned char *input,
...@@ -115,10 +128,13 @@ int mbedtls_sha256_update_ret( mbedtls_sha256_context *ctx, ...@@ -115,10 +128,13 @@ int mbedtls_sha256_update_ret( mbedtls_sha256_context *ctx,
* \brief This function finishes the SHA-256 operation, and writes * \brief This function finishes the SHA-256 operation, and writes
* the result to the output buffer. * the result to the output buffer.
* *
* \param ctx The SHA-256 context. * \param ctx The SHA-256 context. This must be initialized
* and have a hash operation started.
* \param output The SHA-224 or SHA-256 checksum result. * \param output The SHA-224 or SHA-256 checksum result.
* This must be a writable buffer of length \c 32 Bytes.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return A negative error code on failure.
*/ */
int mbedtls_sha256_finish_ret( mbedtls_sha256_context *ctx, int mbedtls_sha256_finish_ret( mbedtls_sha256_context *ctx,
unsigned char output[32] ); unsigned char output[32] );
...@@ -128,10 +144,12 @@ int mbedtls_sha256_finish_ret( mbedtls_sha256_context *ctx, ...@@ -128,10 +144,12 @@ int mbedtls_sha256_finish_ret( mbedtls_sha256_context *ctx,
* the ongoing SHA-256 computation. This function is for * the ongoing SHA-256 computation. This function is for
* internal use only. * internal use only.
* *
* \param ctx The SHA-256 context. * \param ctx The SHA-256 context. This must be initialized.
* \param data The buffer holding one block of data. * \param data The buffer holding one block of data. This must
* be a readable buffer of length \c 64 Bytes.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return A negative error code on failure.
*/ */
int mbedtls_internal_sha256_process( mbedtls_sha256_context *ctx, int mbedtls_internal_sha256_process( mbedtls_sha256_context *ctx,
const unsigned char data[64] ); const unsigned char data[64] );
...@@ -143,14 +161,14 @@ int mbedtls_internal_sha256_process( mbedtls_sha256_context *ctx, ...@@ -143,14 +161,14 @@ int mbedtls_internal_sha256_process( mbedtls_sha256_context *ctx,
#define MBEDTLS_DEPRECATED #define MBEDTLS_DEPRECATED
#endif #endif
/** /**
* \brief This function starts a SHA-256 checksum calculation. * \brief This function starts a SHA-224 or SHA-256 checksum
* calculation.
* *
* \deprecated Superseded by mbedtls_sha256_starts_ret() in 2.7.0. * \deprecated Superseded by mbedtls_sha256_starts_ret() in 2.7.0.
* *
* \param ctx The SHA-256 context to initialize. * \param ctx The context to use. This must be initialized.
* \param is224 Determines which function to use. * \param is224 Determines which function to use. This must be
* <ul><li>0: Use SHA-256.</li> * either \c 0 for SHA-256, or \c 1 for SHA-224.
* <li>1: Use SHA-224.</li></ul>
*/ */
MBEDTLS_DEPRECATED void mbedtls_sha256_starts( mbedtls_sha256_context *ctx, MBEDTLS_DEPRECATED void mbedtls_sha256_starts( mbedtls_sha256_context *ctx,
int is224 ); int is224 );
...@@ -161,9 +179,11 @@ MBEDTLS_DEPRECATED void mbedtls_sha256_starts( mbedtls_sha256_context *ctx, ...@@ -161,9 +179,11 @@ MBEDTLS_DEPRECATED void mbedtls_sha256_starts( mbedtls_sha256_context *ctx,
* *
* \deprecated Superseded by mbedtls_sha256_update_ret() in 2.7.0. * \deprecated Superseded by mbedtls_sha256_update_ret() in 2.7.0.
* *
* \param ctx The SHA-256 context to initialize. * \param ctx The SHA-256 context to use. This must be
* \param input The buffer holding the data. * initialized and have a hash operation started.
* \param ilen The length of the input data. * \param input The buffer holding the data. This must be a readable
* buffer of length \p ilen Bytes.
* \param ilen The length of the input data in Bytes.
*/ */
MBEDTLS_DEPRECATED void mbedtls_sha256_update( mbedtls_sha256_context *ctx, MBEDTLS_DEPRECATED void mbedtls_sha256_update( mbedtls_sha256_context *ctx,
const unsigned char *input, const unsigned char *input,
...@@ -175,8 +195,10 @@ MBEDTLS_DEPRECATED void mbedtls_sha256_update( mbedtls_sha256_context *ctx, ...@@ -175,8 +195,10 @@ MBEDTLS_DEPRECATED void mbedtls_sha256_update( mbedtls_sha256_context *ctx,
* *
* \deprecated Superseded by mbedtls_sha256_finish_ret() in 2.7.0. * \deprecated Superseded by mbedtls_sha256_finish_ret() in 2.7.0.
* *
* \param ctx The SHA-256 context. * \param ctx The SHA-256 context. This must be initialized and
* \param output The SHA-224or SHA-256 checksum result. * have a hash operation started.
* \param output The SHA-224 or SHA-256 checksum result. This must be
* a writable buffer of length \c 32 Bytes.
*/ */
MBEDTLS_DEPRECATED void mbedtls_sha256_finish( mbedtls_sha256_context *ctx, MBEDTLS_DEPRECATED void mbedtls_sha256_finish( mbedtls_sha256_context *ctx,
unsigned char output[32] ); unsigned char output[32] );
...@@ -188,25 +210,15 @@ MBEDTLS_DEPRECATED void mbedtls_sha256_finish( mbedtls_sha256_context *ctx, ...@@ -188,25 +210,15 @@ MBEDTLS_DEPRECATED void mbedtls_sha256_finish( mbedtls_sha256_context *ctx,
* *
* \deprecated Superseded by mbedtls_internal_sha256_process() in 2.7.0. * \deprecated Superseded by mbedtls_internal_sha256_process() in 2.7.0.
* *
* \param ctx The SHA-256 context. * \param ctx The SHA-256 context. This must be initialized.
* \param data The buffer holding one block of data. * \param data The buffer holding one block of data. This must be
* a readable buffer of size \c 64 Bytes.
*/ */
MBEDTLS_DEPRECATED void mbedtls_sha256_process( mbedtls_sha256_context *ctx, MBEDTLS_DEPRECATED void mbedtls_sha256_process( mbedtls_sha256_context *ctx,
const unsigned char data[64] ); const unsigned char data[64] );
#undef MBEDTLS_DEPRECATED #undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */ #endif /* !MBEDTLS_DEPRECATED_REMOVED */
#ifdef __cplusplus
}
#endif
#else /* MBEDTLS_SHA256_ALT */
#include "sha256_alt.h"
#endif /* MBEDTLS_SHA256_ALT */
#ifdef __cplusplus
extern "C" {
#endif
/** /**
* \brief This function calculates the SHA-224 or SHA-256 * \brief This function calculates the SHA-224 or SHA-256
...@@ -218,12 +230,13 @@ extern "C" { ...@@ -218,12 +230,13 @@ extern "C" {
* The SHA-256 result is calculated as * The SHA-256 result is calculated as
* output = SHA-256(input buffer). * output = SHA-256(input buffer).
* *
* \param input The buffer holding the input data. * \param input The buffer holding the data. This must be a readable
* \param ilen The length of the input data. * buffer of length \p ilen Bytes.
* \param output The SHA-224 or SHA-256 checksum result. * \param ilen The length of the input data in Bytes.
* \param is224 Determines which function to use. * \param output The SHA-224 or SHA-256 checksum result. This must
* <ul><li>0: Use SHA-256.</li> * be a writable buffer of length \c 32 Bytes.
* <li>1: Use SHA-224.</li></ul> * \param is224 Determines which function to use. This must be
* either \c 0 for SHA-256, or \c 1 for SHA-224.
*/ */
int mbedtls_sha256_ret( const unsigned char *input, int mbedtls_sha256_ret( const unsigned char *input,
size_t ilen, size_t ilen,
...@@ -249,12 +262,13 @@ int mbedtls_sha256_ret( const unsigned char *input, ...@@ -249,12 +262,13 @@ int mbedtls_sha256_ret( const unsigned char *input,
* *
* \deprecated Superseded by mbedtls_sha256_ret() in 2.7.0. * \deprecated Superseded by mbedtls_sha256_ret() in 2.7.0.
* *
* \param input The buffer holding the data. * \param input The buffer holding the data. This must be a readable
* \param ilen The length of the input data. * buffer of length \p ilen Bytes.
* \param output The SHA-224 or SHA-256 checksum result. * \param ilen The length of the input data in Bytes.
* \param is224 Determines which function to use. * \param output The SHA-224 or SHA-256 checksum result. This must be
* <ul><li>0: Use SHA-256.</li> * a writable buffer of length \c 32 Bytes.
* <li>1: Use SHA-224.</li></ul> * \param is224 Determines which function to use. This must be either
* \c 0 for SHA-256, or \c 1 for SHA-224.
*/ */
MBEDTLS_DEPRECATED void mbedtls_sha256( const unsigned char *input, MBEDTLS_DEPRECATED void mbedtls_sha256( const unsigned char *input,
size_t ilen, size_t ilen,
...@@ -264,13 +278,18 @@ MBEDTLS_DEPRECATED void mbedtls_sha256( const unsigned char *input, ...@@ -264,13 +278,18 @@ MBEDTLS_DEPRECATED void mbedtls_sha256( const unsigned char *input,
#undef MBEDTLS_DEPRECATED #undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */ #endif /* !MBEDTLS_DEPRECATED_REMOVED */
#if defined(MBEDTLS_SELF_TEST)
/** /**
* \brief The SHA-224 and SHA-256 checkup routine. * \brief The SHA-224 and SHA-256 checkup routine.
* *
* \return \c 0 on success, or \c 1 on failure. * \return \c 0 on success.
* \return \c 1 on failure.
*/ */
int mbedtls_sha256_self_test( int verbose ); int mbedtls_sha256_self_test( int verbose );
#endif /* MBEDTLS_SELF_TEST */
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif
......
/** /**
* \file sha512.h * \file sha512.h
* \brief This file contains SHA-384 and SHA-512 definitions and functions.
* *
* \brief The SHA-384 and SHA-512 cryptographic hash function. * The Secure Hash Algorithms 384 and 512 (SHA-384 and SHA-512) cryptographic
* hash functions are defined in <em>FIPS 180-4: Secure Hash Standard (SHS)</em>.
*/ */
/* /*
* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
...@@ -33,16 +35,18 @@ ...@@ -33,16 +35,18 @@
#include <stddef.h> #include <stddef.h>
#include <stdint.h> #include <stdint.h>
/* MBEDTLS_ERR_SHA512_HW_ACCEL_FAILED is deprecated and should not be used. */
#define MBEDTLS_ERR_SHA512_HW_ACCEL_FAILED -0x0039 /**< SHA-512 hardware accelerator failed */ #define MBEDTLS_ERR_SHA512_HW_ACCEL_FAILED -0x0039 /**< SHA-512 hardware accelerator failed */
#define MBEDTLS_ERR_SHA512_BAD_INPUT_DATA -0x0075 /**< SHA-512 input data was malformed. */
#if !defined(MBEDTLS_SHA512_ALT)
// Regular implementation
//
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
#endif #endif
#if !defined(MBEDTLS_SHA512_ALT)
// Regular implementation
//
/** /**
* \brief The SHA-512 context structure. * \brief The SHA-512 context structure.
* *
...@@ -50,36 +54,43 @@ extern "C" { ...@@ -50,36 +54,43 @@ extern "C" {
* checksum calculations. The choice between these two is * checksum calculations. The choice between these two is
* made in the call to mbedtls_sha512_starts_ret(). * made in the call to mbedtls_sha512_starts_ret().
*/ */
typedef struct typedef struct mbedtls_sha512_context
{ {
uint64_t total[2]; /*!< The number of Bytes processed. */ uint64_t total[2]; /*!< The number of Bytes processed. */
uint64_t state[8]; /*!< The intermediate digest state. */ uint64_t state[8]; /*!< The intermediate digest state. */
unsigned char buffer[128]; /*!< The data block being processed. */ unsigned char buffer[128]; /*!< The data block being processed. */
int is384; /*!< Determines which function to use. int is384; /*!< Determines which function to use:
* <ul><li>0: Use SHA-512.</li> 0: Use SHA-512, or 1: Use SHA-384. */
* <li>1: Use SHA-384.</li></ul> */
} }
mbedtls_sha512_context; mbedtls_sha512_context;
#else /* MBEDTLS_SHA512_ALT */
#include "sha512_alt.h"
#endif /* MBEDTLS_SHA512_ALT */
/** /**
* \brief This function initializes a SHA-512 context. * \brief This function initializes a SHA-512 context.
* *
* \param ctx The SHA-512 context to initialize. * \param ctx The SHA-512 context to initialize. This must
* not be \c NULL.
*/ */
void mbedtls_sha512_init( mbedtls_sha512_context *ctx ); void mbedtls_sha512_init( mbedtls_sha512_context *ctx );
/** /**
* \brief This function clears a SHA-512 context. * \brief This function clears a SHA-512 context.
* *
* \param ctx The SHA-512 context to clear. * \param ctx The SHA-512 context to clear. This may be \c NULL,
* in which case this function does nothing. If it
* is not \c NULL, it must point to an initialized
* SHA-512 context.
*/ */
void mbedtls_sha512_free( mbedtls_sha512_context *ctx ); void mbedtls_sha512_free( mbedtls_sha512_context *ctx );
/** /**
* \brief This function clones the state of a SHA-512 context. * \brief This function clones the state of a SHA-512 context.
* *
* \param dst The destination context. * \param dst The destination context. This must be initialized.
* \param src The context to clone. * \param src The context to clone. This must be initialized.
*/ */
void mbedtls_sha512_clone( mbedtls_sha512_context *dst, void mbedtls_sha512_clone( mbedtls_sha512_context *dst,
const mbedtls_sha512_context *src ); const mbedtls_sha512_context *src );
...@@ -88,12 +99,12 @@ void mbedtls_sha512_clone( mbedtls_sha512_context *dst, ...@@ -88,12 +99,12 @@ void mbedtls_sha512_clone( mbedtls_sha512_context *dst,
* \brief This function starts a SHA-384 or SHA-512 checksum * \brief This function starts a SHA-384 or SHA-512 checksum
* calculation. * calculation.
* *
* \param ctx The SHA-512 context to initialize. * \param ctx The SHA-512 context to use. This must be initialized.
* \param is384 Determines which function to use. * \param is384 Determines which function to use. This must be
* <ul><li>0: Use SHA-512.</li> * either \c for SHA-512, or \c 1 for SHA-384.
* <li>1: Use SHA-384.</li></ul>
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return A negative error code on failure.
*/ */
int mbedtls_sha512_starts_ret( mbedtls_sha512_context *ctx, int is384 ); int mbedtls_sha512_starts_ret( mbedtls_sha512_context *ctx, int is384 );
...@@ -101,11 +112,14 @@ int mbedtls_sha512_starts_ret( mbedtls_sha512_context *ctx, int is384 ); ...@@ -101,11 +112,14 @@ int mbedtls_sha512_starts_ret( mbedtls_sha512_context *ctx, int is384 );
* \brief This function feeds an input buffer into an ongoing * \brief This function feeds an input buffer into an ongoing
* SHA-512 checksum calculation. * SHA-512 checksum calculation.
* *
* \param ctx The SHA-512 context. * \param ctx The SHA-512 context. This must be initialized
* \param input The buffer holding the input data. * and have a hash operation started.
* \param ilen The length of the input data. * \param input The buffer holding the input data. This must
* be a readable buffer of length \p ilen Bytes.
* \param ilen The length of the input data in Bytes.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return A negative error code on failure.
*/ */
int mbedtls_sha512_update_ret( mbedtls_sha512_context *ctx, int mbedtls_sha512_update_ret( mbedtls_sha512_context *ctx,
const unsigned char *input, const unsigned char *input,
...@@ -116,10 +130,13 @@ int mbedtls_sha512_update_ret( mbedtls_sha512_context *ctx, ...@@ -116,10 +130,13 @@ int mbedtls_sha512_update_ret( mbedtls_sha512_context *ctx,
* the result to the output buffer. This function is for * the result to the output buffer. This function is for
* internal use only. * internal use only.
* *
* \param ctx The SHA-512 context. * \param ctx The SHA-512 context. This must be initialized
* and have a hash operation started.
* \param output The SHA-384 or SHA-512 checksum result. * \param output The SHA-384 or SHA-512 checksum result.
* This must be a writable buffer of length \c 64 Bytes.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return A negative error code on failure.
*/ */
int mbedtls_sha512_finish_ret( mbedtls_sha512_context *ctx, int mbedtls_sha512_finish_ret( mbedtls_sha512_context *ctx,
unsigned char output[64] ); unsigned char output[64] );
...@@ -128,10 +145,12 @@ int mbedtls_sha512_finish_ret( mbedtls_sha512_context *ctx, ...@@ -128,10 +145,12 @@ int mbedtls_sha512_finish_ret( mbedtls_sha512_context *ctx,
* \brief This function processes a single data block within * \brief This function processes a single data block within
* the ongoing SHA-512 computation. * the ongoing SHA-512 computation.
* *
* \param ctx The SHA-512 context. * \param ctx The SHA-512 context. This must be initialized.
* \param data The buffer holding one block of data. * \param data The buffer holding one block of data. This
* must be a readable buffer of length \c 128 Bytes.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return A negative error code on failure.
*/ */
int mbedtls_internal_sha512_process( mbedtls_sha512_context *ctx, int mbedtls_internal_sha512_process( mbedtls_sha512_context *ctx,
const unsigned char data[128] ); const unsigned char data[128] );
...@@ -147,10 +166,9 @@ int mbedtls_internal_sha512_process( mbedtls_sha512_context *ctx, ...@@ -147,10 +166,9 @@ int mbedtls_internal_sha512_process( mbedtls_sha512_context *ctx,
* *
* \deprecated Superseded by mbedtls_sha512_starts_ret() in 2.7.0 * \deprecated Superseded by mbedtls_sha512_starts_ret() in 2.7.0
* *
* \param ctx The SHA-512 context to initialize. * \param ctx The SHA-512 context to use. This must be initialized.
* \param is384 Determines which function to use. * \param is384 Determines which function to use. This must be either
* <ul><li>0: Use SHA-512.</li> * \c 0 for SHA-512 or \c 1 for SHA-384.
* <li>1: Use SHA-384.</li></ul>
*/ */
MBEDTLS_DEPRECATED void mbedtls_sha512_starts( mbedtls_sha512_context *ctx, MBEDTLS_DEPRECATED void mbedtls_sha512_starts( mbedtls_sha512_context *ctx,
int is384 ); int is384 );
...@@ -159,11 +177,13 @@ MBEDTLS_DEPRECATED void mbedtls_sha512_starts( mbedtls_sha512_context *ctx, ...@@ -159,11 +177,13 @@ MBEDTLS_DEPRECATED void mbedtls_sha512_starts( mbedtls_sha512_context *ctx,
* \brief This function feeds an input buffer into an ongoing * \brief This function feeds an input buffer into an ongoing
* SHA-512 checksum calculation. * SHA-512 checksum calculation.
* *
* \deprecated Superseded by mbedtls_sha512_update_ret() in 2.7.0 * \deprecated Superseded by mbedtls_sha512_update_ret() in 2.7.0.
* *
* \param ctx The SHA-512 context. * \param ctx The SHA-512 context. This must be initialized
* \param input The buffer holding the data. * and have a hash operation started.
* \param ilen The length of the input data. * \param input The buffer holding the data. This must be a readable
* buffer of length \p ilen Bytes.
* \param ilen The length of the input data in Bytes.
*/ */
MBEDTLS_DEPRECATED void mbedtls_sha512_update( mbedtls_sha512_context *ctx, MBEDTLS_DEPRECATED void mbedtls_sha512_update( mbedtls_sha512_context *ctx,
const unsigned char *input, const unsigned char *input,
...@@ -173,10 +193,12 @@ MBEDTLS_DEPRECATED void mbedtls_sha512_update( mbedtls_sha512_context *ctx, ...@@ -173,10 +193,12 @@ MBEDTLS_DEPRECATED void mbedtls_sha512_update( mbedtls_sha512_context *ctx,
* \brief This function finishes the SHA-512 operation, and writes * \brief This function finishes the SHA-512 operation, and writes
* the result to the output buffer. * the result to the output buffer.
* *
* \deprecated Superseded by mbedtls_sha512_finish_ret() in 2.7.0 * \deprecated Superseded by mbedtls_sha512_finish_ret() in 2.7.0.
* *
* \param ctx The SHA-512 context. * \param ctx The SHA-512 context. This must be initialized
* \param output The SHA-384 or SHA-512 checksum result. * and have a hash operation started.
* \param output The SHA-384 or SHA-512 checksum result. This must
* be a writable buffer of size \c 64 Bytes.
*/ */
MBEDTLS_DEPRECATED void mbedtls_sha512_finish( mbedtls_sha512_context *ctx, MBEDTLS_DEPRECATED void mbedtls_sha512_finish( mbedtls_sha512_context *ctx,
unsigned char output[64] ); unsigned char output[64] );
...@@ -186,10 +208,11 @@ MBEDTLS_DEPRECATED void mbedtls_sha512_finish( mbedtls_sha512_context *ctx, ...@@ -186,10 +208,11 @@ MBEDTLS_DEPRECATED void mbedtls_sha512_finish( mbedtls_sha512_context *ctx,
* the ongoing SHA-512 computation. This function is for * the ongoing SHA-512 computation. This function is for
* internal use only. * internal use only.
* *
* \deprecated Superseded by mbedtls_internal_sha512_process() in 2.7.0 * \deprecated Superseded by mbedtls_internal_sha512_process() in 2.7.0.
* *
* \param ctx The SHA-512 context. * \param ctx The SHA-512 context. This must be initialized.
* \param data The buffer holding one block of data. * \param data The buffer holding one block of data. This must be
* a readable buffer of length \c 128 Bytes.
*/ */
MBEDTLS_DEPRECATED void mbedtls_sha512_process( MBEDTLS_DEPRECATED void mbedtls_sha512_process(
mbedtls_sha512_context *ctx, mbedtls_sha512_context *ctx,
...@@ -198,18 +221,6 @@ MBEDTLS_DEPRECATED void mbedtls_sha512_process( ...@@ -198,18 +221,6 @@ MBEDTLS_DEPRECATED void mbedtls_sha512_process(
#undef MBEDTLS_DEPRECATED #undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */ #endif /* !MBEDTLS_DEPRECATED_REMOVED */
#ifdef __cplusplus
}
#endif
#else /* MBEDTLS_SHA512_ALT */
#include "sha512_alt.h"
#endif /* MBEDTLS_SHA512_ALT */
#ifdef __cplusplus
extern "C" {
#endif
/** /**
* \brief This function calculates the SHA-512 or SHA-384 * \brief This function calculates the SHA-512 or SHA-384
* checksum of a buffer. * checksum of a buffer.
...@@ -220,14 +231,16 @@ extern "C" { ...@@ -220,14 +231,16 @@ extern "C" {
* The SHA-512 result is calculated as * The SHA-512 result is calculated as
* output = SHA-512(input buffer). * output = SHA-512(input buffer).
* *
* \param input The buffer holding the input data. * \param input The buffer holding the input data. This must be
* \param ilen The length of the input data. * a readable buffer of length \p ilen Bytes.
* \param ilen The length of the input data in Bytes.
* \param output The SHA-384 or SHA-512 checksum result. * \param output The SHA-384 or SHA-512 checksum result.
* \param is384 Determines which function to use. * This must be a writable buffer of length \c 64 Bytes.
* <ul><li>0: Use SHA-512.</li> * \param is384 Determines which function to use. This must be either
* <li>1: Use SHA-384.</li></ul> * \c 0 for SHA-512, or \c 1 for SHA-384.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return A negative error code on failure.
*/ */
int mbedtls_sha512_ret( const unsigned char *input, int mbedtls_sha512_ret( const unsigned char *input,
size_t ilen, size_t ilen,
...@@ -240,6 +253,7 @@ int mbedtls_sha512_ret( const unsigned char *input, ...@@ -240,6 +253,7 @@ int mbedtls_sha512_ret( const unsigned char *input,
#else #else
#define MBEDTLS_DEPRECATED #define MBEDTLS_DEPRECATED
#endif #endif
/** /**
* \brief This function calculates the SHA-512 or SHA-384 * \brief This function calculates the SHA-512 or SHA-384
* checksum of a buffer. * checksum of a buffer.
...@@ -252,12 +266,13 @@ int mbedtls_sha512_ret( const unsigned char *input, ...@@ -252,12 +266,13 @@ int mbedtls_sha512_ret( const unsigned char *input,
* *
* \deprecated Superseded by mbedtls_sha512_ret() in 2.7.0 * \deprecated Superseded by mbedtls_sha512_ret() in 2.7.0
* *
* \param input The buffer holding the data. * \param input The buffer holding the data. This must be a
* \param ilen The length of the input data. * readable buffer of length \p ilen Bytes.
* \param output The SHA-384 or SHA-512 checksum result. * \param ilen The length of the input data in Bytes.
* \param is384 Determines which function to use. * \param output The SHA-384 or SHA-512 checksum result. This must
* <ul><li>0: Use SHA-512.</li> * be a writable buffer of length \c 64 Bytes.
* <li>1: Use SHA-384.</li></ul> * \param is384 Determines which function to use. This must be either
* \c 0 for SHA-512, or \c 1 for SHA-384.
*/ */
MBEDTLS_DEPRECATED void mbedtls_sha512( const unsigned char *input, MBEDTLS_DEPRECATED void mbedtls_sha512( const unsigned char *input,
size_t ilen, size_t ilen,
...@@ -266,12 +281,17 @@ MBEDTLS_DEPRECATED void mbedtls_sha512( const unsigned char *input, ...@@ -266,12 +281,17 @@ MBEDTLS_DEPRECATED void mbedtls_sha512( const unsigned char *input,
#undef MBEDTLS_DEPRECATED #undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */ #endif /* !MBEDTLS_DEPRECATED_REMOVED */
#if defined(MBEDTLS_SELF_TEST)
/** /**
* \brief The SHA-384 or SHA-512 checkup routine. * \brief The SHA-384 or SHA-512 checkup routine.
* *
* \return \c 0 on success, or \c 1 on failure. * \return \c 0 on success.
* \return \c 1 on failure.
*/ */
int mbedtls_sha512_self_test( int verbose ); int mbedtls_sha512_self_test( int verbose );
#endif /* MBEDTLS_SELF_TEST */
#ifdef __cplusplus #ifdef __cplusplus
} }
......
...@@ -49,6 +49,15 @@ ...@@ -49,6 +49,15 @@
#endif #endif
#if defined(MBEDTLS_ZLIB_SUPPORT) #if defined(MBEDTLS_ZLIB_SUPPORT)
#if defined(MBEDTLS_DEPRECATED_WARNING)
#warning "Record compression support via MBEDTLS_ZLIB_SUPPORT is deprecated and will be removed in the next major revision of the library"
#endif
#if defined(MBEDTLS_DEPRECATED_REMOVED)
#error "Record compression support via MBEDTLS_ZLIB_SUPPORT is deprecated and cannot be used if MBEDTLS_DEPRECATED_REMOVED is set"
#endif
#include "zlib.h" #include "zlib.h"
#endif #endif
...@@ -103,13 +112,17 @@ ...@@ -103,13 +112,17 @@
#define MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED -0x6A80 /**< DTLS client must retry for hello verification */ #define MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED -0x6A80 /**< DTLS client must retry for hello verification */
#define MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL -0x6A00 /**< A buffer is too small to receive or write a message */ #define MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL -0x6A00 /**< A buffer is too small to receive or write a message */
#define MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE -0x6980 /**< None of the common ciphersuites is usable (eg, no suitable certificate, see debug messages). */ #define MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE -0x6980 /**< None of the common ciphersuites is usable (eg, no suitable certificate, see debug messages). */
#define MBEDTLS_ERR_SSL_WANT_READ -0x6900 /**< Connection requires a read call. */ #define MBEDTLS_ERR_SSL_WANT_READ -0x6900 /**< No data of requested type currently available on underlying transport. */
#define MBEDTLS_ERR_SSL_WANT_WRITE -0x6880 /**< Connection requires a write call. */ #define MBEDTLS_ERR_SSL_WANT_WRITE -0x6880 /**< Connection requires a write call. */
#define MBEDTLS_ERR_SSL_TIMEOUT -0x6800 /**< The operation timed out. */ #define MBEDTLS_ERR_SSL_TIMEOUT -0x6800 /**< The operation timed out. */
#define MBEDTLS_ERR_SSL_CLIENT_RECONNECT -0x6780 /**< The client initiated a reconnect from the same port. */ #define MBEDTLS_ERR_SSL_CLIENT_RECONNECT -0x6780 /**< The client initiated a reconnect from the same port. */
#define MBEDTLS_ERR_SSL_UNEXPECTED_RECORD -0x6700 /**< Record header looks valid but is not expected. */ #define MBEDTLS_ERR_SSL_UNEXPECTED_RECORD -0x6700 /**< Record header looks valid but is not expected. */
#define MBEDTLS_ERR_SSL_NON_FATAL -0x6680 /**< The alert message received indicates a non-fatal error. */ #define MBEDTLS_ERR_SSL_NON_FATAL -0x6680 /**< The alert message received indicates a non-fatal error. */
#define MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH -0x6600 /**< Couldn't set the hash for verifying CertificateVerify */ #define MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH -0x6600 /**< Couldn't set the hash for verifying CertificateVerify */
#define MBEDTLS_ERR_SSL_CONTINUE_PROCESSING -0x6580 /**< Internal-only message signaling that further message-processing should be done */
#define MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS -0x6500 /**< The asynchronous operation is not completed yet. */
#define MBEDTLS_ERR_SSL_EARLY_MESSAGE -0x6480 /**< Internal-only message signaling that a message arrived early. */
#define MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS -0x7000 /**< A cryptographic operation is in progress. Try again later. */
/* /*
* Various constants * Various constants
...@@ -209,7 +222,7 @@ ...@@ -209,7 +222,7 @@
#endif #endif
/* /*
* Maxium fragment length in bytes, * Maximum fragment length in bytes,
* determines the size of each of the two internal I/O buffers. * determines the size of each of the two internal I/O buffers.
* *
* Note: the RFC defines the default size of SSL / TLS messages. If you * Note: the RFC defines the default size of SSL / TLS messages. If you
...@@ -223,6 +236,22 @@ ...@@ -223,6 +236,22 @@
#define MBEDTLS_SSL_MAX_CONTENT_LEN 16384 /**< Size of the input / output buffer */ #define MBEDTLS_SSL_MAX_CONTENT_LEN 16384 /**< Size of the input / output buffer */
#endif #endif
#if !defined(MBEDTLS_SSL_IN_CONTENT_LEN)
#define MBEDTLS_SSL_IN_CONTENT_LEN MBEDTLS_SSL_MAX_CONTENT_LEN
#endif
#if !defined(MBEDTLS_SSL_OUT_CONTENT_LEN)
#define MBEDTLS_SSL_OUT_CONTENT_LEN MBEDTLS_SSL_MAX_CONTENT_LEN
#endif
/*
* Maximum number of heap-allocated bytes for the purpose of
* DTLS handshake message reassembly and future message buffering.
*/
#if !defined(MBEDTLS_SSL_DTLS_MAX_BUFFERING)
#define MBEDTLS_SSL_DTLS_MAX_BUFFERING 32768
#endif
/* \} name SECTION: Module settings */ /* \} name SECTION: Module settings */
/* /*
...@@ -526,7 +555,6 @@ typedef void mbedtls_ssl_set_timer_t( void * ctx, ...@@ -526,7 +555,6 @@ typedef void mbedtls_ssl_set_timer_t( void * ctx,
*/ */
typedef int mbedtls_ssl_get_timer_t( void * ctx ); typedef int mbedtls_ssl_get_timer_t( void * ctx );
/* Defined below */ /* Defined below */
typedef struct mbedtls_ssl_session mbedtls_ssl_session; typedef struct mbedtls_ssl_session mbedtls_ssl_session;
typedef struct mbedtls_ssl_context mbedtls_ssl_context; typedef struct mbedtls_ssl_context mbedtls_ssl_context;
...@@ -543,6 +571,218 @@ typedef struct mbedtls_ssl_key_cert mbedtls_ssl_key_cert; ...@@ -543,6 +571,218 @@ typedef struct mbedtls_ssl_key_cert mbedtls_ssl_key_cert;
typedef struct mbedtls_ssl_flight_item mbedtls_ssl_flight_item; typedef struct mbedtls_ssl_flight_item mbedtls_ssl_flight_item;
#endif #endif
#if defined(MBEDTLS_SSL_ASYNC_PRIVATE)
#if defined(MBEDTLS_X509_CRT_PARSE_C)
/**
* \brief Callback type: start external signature operation.
*
* This callback is called during an SSL handshake to start
* a signature decryption operation using an
* external processor. The parameter \p cert contains
* the public key; it is up to the callback function to
* determine how to access the associated private key.
*
* This function typically sends or enqueues a request, and
* does not wait for the operation to complete. This allows
* the handshake step to be non-blocking.
*
* The parameters \p ssl and \p cert are guaranteed to remain
* valid throughout the handshake. On the other hand, this
* function must save the contents of \p hash if the value
* is needed for later processing, because the \p hash buffer
* is no longer valid after this function returns.
*
* This function may call mbedtls_ssl_set_async_operation_data()
* to store an operation context for later retrieval
* by the resume or cancel callback.
*
* \note For RSA signatures, this function must produce output
* that is consistent with PKCS#1 v1.5 in the same way as
* mbedtls_rsa_pkcs1_sign(). Before the private key operation,
* apply the padding steps described in RFC 8017, section 9.2
* "EMSA-PKCS1-v1_5" as follows.
* - If \p md_alg is #MBEDTLS_MD_NONE, apply the PKCS#1 v1.5
* encoding, treating \p hash as the DigestInfo to be
* padded. In other words, apply EMSA-PKCS1-v1_5 starting
* from step 3, with `T = hash` and `tLen = hash_len`.
* - If `md_alg != MBEDTLS_MD_NONE`, apply the PKCS#1 v1.5
* encoding, treating \p hash as the hash to be encoded and
* padded. In other words, apply EMSA-PKCS1-v1_5 starting
* from step 2, with `digestAlgorithm` obtained by calling
* mbedtls_oid_get_oid_by_md() on \p md_alg.
*
* \note For ECDSA signatures, the output format is the DER encoding
* `Ecdsa-Sig-Value` defined in
* [RFC 4492 section 5.4](https://tools.ietf.org/html/rfc4492#section-5.4).
*
* \param ssl The SSL connection instance. It should not be
* modified other than via
* mbedtls_ssl_set_async_operation_data().
* \param cert Certificate containing the public key.
* In simple cases, this is one of the pointers passed to
* mbedtls_ssl_conf_own_cert() when configuring the SSL
* connection. However, if other callbacks are used, this
* property may not hold. For example, if an SNI callback
* is registered with mbedtls_ssl_conf_sni(), then
* this callback determines what certificate is used.
* \param md_alg Hash algorithm.
* \param hash Buffer containing the hash. This buffer is
* no longer valid when the function returns.
* \param hash_len Size of the \c hash buffer in bytes.
*
* \return 0 if the operation was started successfully and the SSL
* stack should call the resume callback immediately.
* \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if the operation
* was started successfully and the SSL stack should return
* immediately without calling the resume callback yet.
* \return #MBEDTLS_ERR_SSL_HW_ACCEL_FALLTHROUGH if the external
* processor does not support this key. The SSL stack will
* use the private key object instead.
* \return Any other error indicates a fatal failure and is
* propagated up the call chain. The callback should
* use \c MBEDTLS_ERR_PK_xxx error codes, and <b>must not</b>
* use \c MBEDTLS_ERR_SSL_xxx error codes except as
* directed in the documentation of this callback.
*/
typedef int mbedtls_ssl_async_sign_t( mbedtls_ssl_context *ssl,
mbedtls_x509_crt *cert,
mbedtls_md_type_t md_alg,
const unsigned char *hash,
size_t hash_len );
/**
* \brief Callback type: start external decryption operation.
*
* This callback is called during an SSL handshake to start
* an RSA decryption operation using an
* external processor. The parameter \p cert contains
* the public key; it is up to the callback function to
* determine how to access the associated private key.
*
* This function typically sends or enqueues a request, and
* does not wait for the operation to complete. This allows
* the handshake step to be non-blocking.
*
* The parameters \p ssl and \p cert are guaranteed to remain
* valid throughout the handshake. On the other hand, this
* function must save the contents of \p input if the value
* is needed for later processing, because the \p input buffer
* is no longer valid after this function returns.
*
* This function may call mbedtls_ssl_set_async_operation_data()
* to store an operation context for later retrieval
* by the resume or cancel callback.
*
* \warning RSA decryption as used in TLS is subject to a potential
* timing side channel attack first discovered by Bleichenbacher
* in 1998. This attack can be remotely exploitable
* in practice. To avoid this attack, you must ensure that
* if the callback performs an RSA decryption, the time it
* takes to execute and return the result does not depend
* on whether the RSA decryption succeeded or reported
* invalid padding.
*
* \param ssl The SSL connection instance. It should not be
* modified other than via
* mbedtls_ssl_set_async_operation_data().
* \param cert Certificate containing the public key.
* In simple cases, this is one of the pointers passed to
* mbedtls_ssl_conf_own_cert() when configuring the SSL
* connection. However, if other callbacks are used, this
* property may not hold. For example, if an SNI callback
* is registered with mbedtls_ssl_conf_sni(), then
* this callback determines what certificate is used.
* \param input Buffer containing the input ciphertext. This buffer
* is no longer valid when the function returns.
* \param input_len Size of the \p input buffer in bytes.
*
* \return 0 if the operation was started successfully and the SSL
* stack should call the resume callback immediately.
* \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if the operation
* was started successfully and the SSL stack should return
* immediately without calling the resume callback yet.
* \return #MBEDTLS_ERR_SSL_HW_ACCEL_FALLTHROUGH if the external
* processor does not support this key. The SSL stack will
* use the private key object instead.
* \return Any other error indicates a fatal failure and is
* propagated up the call chain. The callback should
* use \c MBEDTLS_ERR_PK_xxx error codes, and <b>must not</b>
* use \c MBEDTLS_ERR_SSL_xxx error codes except as
* directed in the documentation of this callback.
*/
typedef int mbedtls_ssl_async_decrypt_t( mbedtls_ssl_context *ssl,
mbedtls_x509_crt *cert,
const unsigned char *input,
size_t input_len );
#endif /* MBEDTLS_X509_CRT_PARSE_C */
/**
* \brief Callback type: resume external operation.
*
* This callback is called during an SSL handshake to resume
* an external operation started by the
* ::mbedtls_ssl_async_sign_t or
* ::mbedtls_ssl_async_decrypt_t callback.
*
* This function typically checks the status of a pending
* request or causes the request queue to make progress, and
* does not wait for the operation to complete. This allows
* the handshake step to be non-blocking.
*
* This function may call mbedtls_ssl_get_async_operation_data()
* to retrieve an operation context set by the start callback.
* It may call mbedtls_ssl_set_async_operation_data() to modify
* this context.
*
* Note that when this function returns a status other than
* #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS, it must free any
* resources associated with the operation.
*
* \param ssl The SSL connection instance. It should not be
* modified other than via
* mbedtls_ssl_set_async_operation_data().
* \param output Buffer containing the output (signature or decrypted
* data) on success.
* \param output_len On success, number of bytes written to \p output.
* \param output_size Size of the \p output buffer in bytes.
*
* \return 0 if output of the operation is available in the
* \p output buffer.
* \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if the operation
* is still in progress. Subsequent requests for progress
* on the SSL connection will call the resume callback
* again.
* \return Any other error means that the operation is aborted.
* The SSL handshake is aborted. The callback should
* use \c MBEDTLS_ERR_PK_xxx error codes, and <b>must not</b>
* use \c MBEDTLS_ERR_SSL_xxx error codes except as
* directed in the documentation of this callback.
*/
typedef int mbedtls_ssl_async_resume_t( mbedtls_ssl_context *ssl,
unsigned char *output,
size_t *output_len,
size_t output_size );
/**
* \brief Callback type: cancel external operation.
*
* This callback is called if an SSL connection is closed
* while an asynchronous operation is in progress. Note that
* this callback is not called if the
* ::mbedtls_ssl_async_resume_t callback has run and has
* returned a value other than
* #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS, since in that case
* the asynchronous operation has already completed.
*
* This function may call mbedtls_ssl_get_async_operation_data()
* to retrieve an operation context set by the start callback.
*
* \param ssl The SSL connection instance. It should not be
* modified.
*/
typedef void mbedtls_ssl_async_cancel_t( mbedtls_ssl_context *ssl );
#endif /* MBEDTLS_SSL_ASYNC_PRIVATE */
/* /*
* This structure is used for storing current session data. * This structure is used for storing current session data.
*/ */
...@@ -659,6 +899,16 @@ struct mbedtls_ssl_config ...@@ -659,6 +899,16 @@ struct mbedtls_ssl_config
mbedtls_x509_crl *ca_crl; /*!< trusted CAs CRLs */ mbedtls_x509_crl *ca_crl; /*!< trusted CAs CRLs */
#endif /* MBEDTLS_X509_CRT_PARSE_C */ #endif /* MBEDTLS_X509_CRT_PARSE_C */
#if defined(MBEDTLS_SSL_ASYNC_PRIVATE)
#if defined(MBEDTLS_X509_CRT_PARSE_C)
mbedtls_ssl_async_sign_t *f_async_sign_start; /*!< start asynchronous signature operation */
mbedtls_ssl_async_decrypt_t *f_async_decrypt_start; /*!< start asynchronous decryption operation */
#endif /* MBEDTLS_X509_CRT_PARSE_C */
mbedtls_ssl_async_resume_t *f_async_resume; /*!< resume asynchronous operation */
mbedtls_ssl_async_cancel_t *f_async_cancel; /*!< cancel asynchronous operation */
void *p_async_config_data; /*!< Configuration data set by mbedtls_ssl_conf_async_private_cb(). */
#endif /* MBEDTLS_SSL_ASYNC_PRIVATE */
#if defined(MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED) #if defined(MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED)
const int *sig_hashes; /*!< allowed signature hashes */ const int *sig_hashes; /*!< allowed signature hashes */
#endif #endif
...@@ -673,10 +923,18 @@ struct mbedtls_ssl_config ...@@ -673,10 +923,18 @@ struct mbedtls_ssl_config
#endif #endif
#if defined(MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED) #if defined(MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED)
unsigned char *psk; /*!< pre-shared key */ unsigned char *psk; /*!< pre-shared key. This field should
size_t psk_len; /*!< length of the pre-shared key */ only be set via
unsigned char *psk_identity; /*!< identity for PSK negotiation */ mbedtls_ssl_conf_psk() */
size_t psk_identity_len;/*!< length of identity */ size_t psk_len; /*!< length of the pre-shared key. This
field should only be set via
mbedtls_ssl_conf_psk() */
unsigned char *psk_identity; /*!< identity for PSK negotiation. This
field should only be set via
mbedtls_ssl_conf_psk() */
size_t psk_identity_len;/*!< length of identity. This field should
only be set via
mbedtls_ssl_conf_psk() */
#endif #endif
#if defined(MBEDTLS_SSL_ALPN) #if defined(MBEDTLS_SSL_ALPN)
...@@ -774,14 +1032,14 @@ struct mbedtls_ssl_context ...@@ -774,14 +1032,14 @@ struct mbedtls_ssl_context
int renego_records_seen; /*!< Records since renego request, or with DTLS, int renego_records_seen; /*!< Records since renego request, or with DTLS,
number of retransmissions of request if number of retransmissions of request if
renego_max_records is < 0 */ renego_max_records is < 0 */
#endif #endif /* MBEDTLS_SSL_RENEGOTIATION */
int major_ver; /*!< equal to MBEDTLS_SSL_MAJOR_VERSION_3 */ int major_ver; /*!< equal to MBEDTLS_SSL_MAJOR_VERSION_3 */
int minor_ver; /*!< either 0 (SSL3) or 1 (TLS1.0) */ int minor_ver; /*!< either 0 (SSL3) or 1 (TLS1.0) */
#if defined(MBEDTLS_SSL_DTLS_BADMAC_LIMIT) #if defined(MBEDTLS_SSL_DTLS_BADMAC_LIMIT)
unsigned badmac_seen; /*!< records with a bad MAC received */ unsigned badmac_seen; /*!< records with a bad MAC received */
#endif #endif /* MBEDTLS_SSL_DTLS_BADMAC_LIMIT */
mbedtls_ssl_send_t *f_send; /*!< Callback for network send */ mbedtls_ssl_send_t *f_send; /*!< Callback for network send */
mbedtls_ssl_recv_t *f_recv; /*!< Callback for network receive */ mbedtls_ssl_recv_t *f_recv; /*!< Callback for network receive */
...@@ -837,11 +1095,11 @@ struct mbedtls_ssl_context ...@@ -837,11 +1095,11 @@ struct mbedtls_ssl_context
uint16_t in_epoch; /*!< DTLS epoch for incoming records */ uint16_t in_epoch; /*!< DTLS epoch for incoming records */
size_t next_record_offset; /*!< offset of the next record in datagram size_t next_record_offset; /*!< offset of the next record in datagram
(equal to in_left if none) */ (equal to in_left if none) */
#endif #endif /* MBEDTLS_SSL_PROTO_DTLS */
#if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY) #if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY)
uint64_t in_window_top; /*!< last validated record seq_num */ uint64_t in_window_top; /*!< last validated record seq_num */
uint64_t in_window; /*!< bitmask for replay detection */ uint64_t in_window; /*!< bitmask for replay detection */
#endif #endif /* MBEDTLS_SSL_DTLS_ANTI_REPLAY */
size_t in_hslen; /*!< current handshake message length, size_t in_hslen; /*!< current handshake message length,
including the handshake header */ including the handshake header */
...@@ -850,6 +1108,11 @@ struct mbedtls_ssl_context ...@@ -850,6 +1108,11 @@ struct mbedtls_ssl_context
int keep_current_message; /*!< drop or reuse current message int keep_current_message; /*!< drop or reuse current message
on next call to record layer? */ on next call to record layer? */
#if defined(MBEDTLS_SSL_PROTO_DTLS)
uint8_t disable_datagram_packing; /*!< Disable packing multiple records
* within a single datagram. */
#endif /* MBEDTLS_SSL_PROTO_DTLS */
/* /*
* Record layer (outgoing data) * Record layer (outgoing data)
*/ */
...@@ -864,12 +1127,18 @@ struct mbedtls_ssl_context ...@@ -864,12 +1127,18 @@ struct mbedtls_ssl_context
size_t out_msglen; /*!< record header: message length */ size_t out_msglen; /*!< record header: message length */
size_t out_left; /*!< amount of data not yet written */ size_t out_left; /*!< amount of data not yet written */
unsigned char cur_out_ctr[8]; /*!< Outgoing record sequence number. */
#if defined(MBEDTLS_SSL_PROTO_DTLS)
uint16_t mtu; /*!< path mtu, used to fragment outgoing messages */
#endif /* MBEDTLS_SSL_PROTO_DTLS */
#if defined(MBEDTLS_ZLIB_SUPPORT) #if defined(MBEDTLS_ZLIB_SUPPORT)
unsigned char *compress_buf; /*!< zlib data buffer */ unsigned char *compress_buf; /*!< zlib data buffer */
#endif #endif /* MBEDTLS_ZLIB_SUPPORT */
#if defined(MBEDTLS_SSL_CBC_RECORD_SPLITTING) #if defined(MBEDTLS_SSL_CBC_RECORD_SPLITTING)
signed char split_done; /*!< current record already splitted? */ signed char split_done; /*!< current record already splitted? */
#endif #endif /* MBEDTLS_SSL_CBC_RECORD_SPLITTING */
/* /*
* PKI layer * PKI layer
...@@ -882,11 +1151,11 @@ struct mbedtls_ssl_context ...@@ -882,11 +1151,11 @@ struct mbedtls_ssl_context
#if defined(MBEDTLS_X509_CRT_PARSE_C) #if defined(MBEDTLS_X509_CRT_PARSE_C)
char *hostname; /*!< expected peer CN for verification char *hostname; /*!< expected peer CN for verification
(and SNI if available) */ (and SNI if available) */
#endif #endif /* MBEDTLS_X509_CRT_PARSE_C */
#if defined(MBEDTLS_SSL_ALPN) #if defined(MBEDTLS_SSL_ALPN)
const char *alpn_chosen; /*!< negotiated protocol */ const char *alpn_chosen; /*!< negotiated protocol */
#endif #endif /* MBEDTLS_SSL_ALPN */
/* /*
* Information for DTLS hello verify * Information for DTLS hello verify
...@@ -894,7 +1163,7 @@ struct mbedtls_ssl_context ...@@ -894,7 +1163,7 @@ struct mbedtls_ssl_context
#if defined(MBEDTLS_SSL_DTLS_HELLO_VERIFY) && defined(MBEDTLS_SSL_SRV_C) #if defined(MBEDTLS_SSL_DTLS_HELLO_VERIFY) && defined(MBEDTLS_SSL_SRV_C)
unsigned char *cli_id; /*!< transport-level ID of the client */ unsigned char *cli_id; /*!< transport-level ID of the client */
size_t cli_id_len; /*!< length of cli_id */ size_t cli_id_len; /*!< length of cli_id */
#endif #endif /* MBEDTLS_SSL_DTLS_HELLO_VERIFY && MBEDTLS_SSL_SRV_C */
/* /*
* Secure renegotiation * Secure renegotiation
...@@ -906,7 +1175,7 @@ struct mbedtls_ssl_context ...@@ -906,7 +1175,7 @@ struct mbedtls_ssl_context
size_t verify_data_len; /*!< length of verify data stored */ size_t verify_data_len; /*!< length of verify data stored */
char own_verify_data[MBEDTLS_SSL_VERIFY_DATA_MAX_LEN]; /*!< previous handshake verify data */ char own_verify_data[MBEDTLS_SSL_VERIFY_DATA_MAX_LEN]; /*!< previous handshake verify data */
char peer_verify_data[MBEDTLS_SSL_VERIFY_DATA_MAX_LEN]; /*!< previous handshake verify data */ char peer_verify_data[MBEDTLS_SSL_VERIFY_DATA_MAX_LEN]; /*!< previous handshake verify data */
#endif #endif /* MBEDTLS_SSL_RENEGOTIATION */
}; };
#if defined(MBEDTLS_SSL_HW_RECORD_ACCEL) #if defined(MBEDTLS_SSL_HW_RECORD_ACCEL)
...@@ -1126,6 +1395,52 @@ void mbedtls_ssl_set_bio( mbedtls_ssl_context *ssl, ...@@ -1126,6 +1395,52 @@ void mbedtls_ssl_set_bio( mbedtls_ssl_context *ssl,
mbedtls_ssl_recv_t *f_recv, mbedtls_ssl_recv_t *f_recv,
mbedtls_ssl_recv_timeout_t *f_recv_timeout ); mbedtls_ssl_recv_timeout_t *f_recv_timeout );
#if defined(MBEDTLS_SSL_PROTO_DTLS)
/**
* \brief Set the Maximum Tranport Unit (MTU).
* Special value: 0 means unset (no limit).
* This represents the maximum size of a datagram payload
* handled by the transport layer (usually UDP) as determined
* by the network link and stack. In practice, this controls
* the maximum size datagram the DTLS layer will pass to the
* \c f_send() callback set using \c mbedtls_ssl_set_bio().
*
* \note The limit on datagram size is converted to a limit on
* record payload by subtracting the current overhead of
* encapsulation and encryption/authentication if any.
*
* \note This can be called at any point during the connection, for
* example when a Path Maximum Transfer Unit (PMTU)
* estimate becomes available from other sources,
* such as lower (or higher) protocol layers.
*
* \note This setting only controls the size of the packets we send,
* and does not restrict the size of the datagrams we're
* willing to receive. Client-side, you can request the
* server to use smaller records with \c
* mbedtls_ssl_conf_max_frag_len().
*
* \note If both a MTU and a maximum fragment length have been
* configured (or negotiated with the peer), the resulting
* lower limit on record payload (see first note) is used.
*
* \note This can only be used to decrease the maximum size
* of datagrams (hence records, see first note) sent. It
* cannot be used to increase the maximum size of records over
* the limit set by #MBEDTLS_SSL_OUT_CONTENT_LEN.
*
* \note Values lower than the current record layer expansion will
* result in an error when trying to send data.
*
* \note Using record compression together with a non-zero MTU value
* will result in an error when trying to send data.
*
* \param ssl SSL context
* \param mtu Value of the path MTU in bytes
*/
void mbedtls_ssl_set_mtu( mbedtls_ssl_context *ssl, uint16_t mtu );
#endif /* MBEDTLS_SSL_PROTO_DTLS */
/** /**
* \brief Set the timeout period for mbedtls_ssl_read() * \brief Set the timeout period for mbedtls_ssl_read()
* (Default: no timeout.) * (Default: no timeout.)
...@@ -1289,6 +1604,85 @@ void mbedtls_ssl_conf_export_keys_cb( mbedtls_ssl_config *conf, ...@@ -1289,6 +1604,85 @@ void mbedtls_ssl_conf_export_keys_cb( mbedtls_ssl_config *conf,
void *p_export_keys ); void *p_export_keys );
#endif /* MBEDTLS_SSL_EXPORT_KEYS */ #endif /* MBEDTLS_SSL_EXPORT_KEYS */
#if defined(MBEDTLS_SSL_ASYNC_PRIVATE)
/**
* \brief Configure asynchronous private key operation callbacks.
*
* \param conf SSL configuration context
* \param f_async_sign Callback to start a signature operation. See
* the description of ::mbedtls_ssl_async_sign_t
* for more information. This may be \c NULL if the
* external processor does not support any signature
* operation; in this case the private key object
* associated with the certificate will be used.
* \param f_async_decrypt Callback to start a decryption operation. See
* the description of ::mbedtls_ssl_async_decrypt_t
* for more information. This may be \c NULL if the
* external processor does not support any decryption
* operation; in this case the private key object
* associated with the certificate will be used.
* \param f_async_resume Callback to resume an asynchronous operation. See
* the description of ::mbedtls_ssl_async_resume_t
* for more information. This may not be \c NULL unless
* \p f_async_sign and \p f_async_decrypt are both
* \c NULL.
* \param f_async_cancel Callback to cancel an asynchronous operation. See
* the description of ::mbedtls_ssl_async_cancel_t
* for more information. This may be \c NULL if
* no cleanup is needed.
* \param config_data A pointer to configuration data which can be
* retrieved with
* mbedtls_ssl_conf_get_async_config_data(). The
* library stores this value without dereferencing it.
*/
void mbedtls_ssl_conf_async_private_cb( mbedtls_ssl_config *conf,
mbedtls_ssl_async_sign_t *f_async_sign,
mbedtls_ssl_async_decrypt_t *f_async_decrypt,
mbedtls_ssl_async_resume_t *f_async_resume,
mbedtls_ssl_async_cancel_t *f_async_cancel,
void *config_data );
/**
* \brief Retrieve the configuration data set by
* mbedtls_ssl_conf_async_private_cb().
*
* \param conf SSL configuration context
* \return The configuration data set by
* mbedtls_ssl_conf_async_private_cb().
*/
void *mbedtls_ssl_conf_get_async_config_data( const mbedtls_ssl_config *conf );
/**
* \brief Retrieve the asynchronous operation user context.
*
* \note This function may only be called while a handshake
* is in progress.
*
* \param ssl The SSL context to access.
*
* \return The asynchronous operation user context that was last
* set during the current handshake. If
* mbedtls_ssl_set_async_operation_data() has not yet been
* called during the current handshake, this function returns
* \c NULL.
*/
void *mbedtls_ssl_get_async_operation_data( const mbedtls_ssl_context *ssl );
/**
* \brief Retrieve the asynchronous operation user context.
*
* \note This function may only be called while a handshake
* is in progress.
*
* \param ssl The SSL context to access.
* \param ctx The new value of the asynchronous operation user context.
* Call mbedtls_ssl_get_async_operation_data() later during the
* same handshake to retrieve this value.
*/
void mbedtls_ssl_set_async_operation_data( mbedtls_ssl_context *ssl,
void *ctx );
#endif /* MBEDTLS_SSL_ASYNC_PRIVATE */
/** /**
* \brief Callback type: generate a cookie * \brief Callback type: generate a cookie
* *
...@@ -1430,6 +1824,38 @@ void mbedtls_ssl_conf_dtls_badmac_limit( mbedtls_ssl_config *conf, unsigned limi ...@@ -1430,6 +1824,38 @@ void mbedtls_ssl_conf_dtls_badmac_limit( mbedtls_ssl_config *conf, unsigned limi
#endif /* MBEDTLS_SSL_DTLS_BADMAC_LIMIT */ #endif /* MBEDTLS_SSL_DTLS_BADMAC_LIMIT */
#if defined(MBEDTLS_SSL_PROTO_DTLS) #if defined(MBEDTLS_SSL_PROTO_DTLS)
/**
* \brief Allow or disallow packing of multiple handshake records
* within a single datagram.
*
* \param ssl The SSL context to configure.
* \param allow_packing This determines whether datagram packing may
* be used or not. A value of \c 0 means that every
* record will be sent in a separate datagram; a
* value of \c 1 means that, if space permits,
* multiple handshake messages (including CCS) belonging to
* a single flight may be packed within a single datagram.
*
* \note This is enabled by default and should only be disabled
* for test purposes, or if datagram packing causes
* interoperability issues with peers that don't support it.
*
* \note Allowing datagram packing reduces the network load since
* there's less overhead if multiple messages share the same
* datagram. Also, it increases the handshake efficiency
* since messages belonging to a single datagram will not
* be reordered in transit, and so future message buffering
* or flight retransmission (if no buffering is used) as
* means to deal with reordering are needed less frequently.
*
* \note Application records are not affected by this option and
* are currently always sent in separate datagrams.
*
*/
void mbedtls_ssl_set_datagram_packing( mbedtls_ssl_context *ssl,
unsigned allow_packing );
/** /**
* \brief Set retransmit timeout values for the DTLS handshake. * \brief Set retransmit timeout values for the DTLS handshake.
* (DTLS only, no effect on TLS.) * (DTLS only, no effect on TLS.)
...@@ -1607,7 +2033,7 @@ void mbedtls_ssl_conf_ca_chain( mbedtls_ssl_config *conf, ...@@ -1607,7 +2033,7 @@ void mbedtls_ssl_conf_ca_chain( mbedtls_ssl_config *conf,
* provision more than one cert/key pair (eg one ECDSA, one * provision more than one cert/key pair (eg one ECDSA, one
* RSA with SHA-256, one RSA with SHA-1). An adequate * RSA with SHA-256, one RSA with SHA-1). An adequate
* certificate will be selected according to the client's * certificate will be selected according to the client's
* advertised capabilities. In case mutliple certificates are * advertised capabilities. In case multiple certificates are
* adequate, preference is given to the one set by the first * adequate, preference is given to the one set by the first
* call to this function, then second, etc. * call to this function, then second, etc.
* *
...@@ -1842,7 +2268,7 @@ void mbedtls_ssl_conf_sig_hashes( mbedtls_ssl_config *conf, ...@@ -1842,7 +2268,7 @@ void mbedtls_ssl_conf_sig_hashes( mbedtls_ssl_config *conf,
* *
* \param ssl SSL context * \param ssl SSL context
* \param hostname the server hostname, may be NULL to clear hostname * \param hostname the server hostname, may be NULL to clear hostname
*
* \note Maximum hostname length MBEDTLS_SSL_MAX_HOST_NAME_LEN. * \note Maximum hostname length MBEDTLS_SSL_MAX_HOST_NAME_LEN.
* *
* \return 0 if successful, MBEDTLS_ERR_SSL_ALLOC_FAILED on * \return 0 if successful, MBEDTLS_ERR_SSL_ALLOC_FAILED on
...@@ -2106,12 +2532,31 @@ void mbedtls_ssl_conf_cert_req_ca_list( mbedtls_ssl_config *conf, ...@@ -2106,12 +2532,31 @@ void mbedtls_ssl_conf_cert_req_ca_list( mbedtls_ssl_config *conf,
#if defined(MBEDTLS_SSL_MAX_FRAGMENT_LENGTH) #if defined(MBEDTLS_SSL_MAX_FRAGMENT_LENGTH)
/** /**
* \brief Set the maximum fragment length to emit and/or negotiate * \brief Set the maximum fragment length to emit and/or negotiate.
* (Default: MBEDTLS_SSL_MAX_CONTENT_LEN, usually 2^14 bytes) * (Typical: the smaller of #MBEDTLS_SSL_IN_CONTENT_LEN and
* #MBEDTLS_SSL_OUT_CONTENT_LEN, usually `2^14` bytes)
* (Server: set maximum fragment length to emit, * (Server: set maximum fragment length to emit,
* usually negotiated by the client during handshake * usually negotiated by the client during handshake)
* (Client: set maximum fragment length to emit *and* * (Client: set maximum fragment length to emit *and*
* negotiate with the server during handshake) * negotiate with the server during handshake)
* (Default: #MBEDTLS_SSL_MAX_FRAG_LEN_NONE)
*
* \note On the client side, the maximum fragment length extension
* *will not* be used, unless the maximum fragment length has
* been set via this function to a value different than
* #MBEDTLS_SSL_MAX_FRAG_LEN_NONE.
*
* \note This sets the maximum length for a record's payload,
* excluding record overhead that will be added to it, see
* \c mbedtls_ssl_get_record_expansion().
*
* \note With TLS, this currently only affects ApplicationData (sent
* with \c mbedtls_ssl_read()), not handshake messages.
* With DTLS, this affects both ApplicationData and handshake.
*
* \note For DTLS, it is also possible to set a limit for the total
* size of daragrams passed to the transport layer, including
* record overhead, see \c mbedtls_ssl_set_mtu().
* *
* \param conf SSL configuration * \param conf SSL configuration
* \param mfl_code Code for maximum fragment length (allowed values: * \param mfl_code Code for maximum fragment length (allowed values:
...@@ -2284,11 +2729,59 @@ void mbedtls_ssl_conf_renegotiation_period( mbedtls_ssl_config *conf, ...@@ -2284,11 +2729,59 @@ void mbedtls_ssl_conf_renegotiation_period( mbedtls_ssl_config *conf,
#endif /* MBEDTLS_SSL_RENEGOTIATION */ #endif /* MBEDTLS_SSL_RENEGOTIATION */
/** /**
* \brief Return the number of data bytes available to read * \brief Check if there is data already read from the
* underlying transport but not yet processed.
*
* \param ssl SSL context
*
* \return 0 if nothing's pending, 1 otherwise.
*
* \note This is different in purpose and behaviour from
* \c mbedtls_ssl_get_bytes_avail in that it considers
* any kind of unprocessed data, not only unread
* application data. If \c mbedtls_ssl_get_bytes
* returns a non-zero value, this function will
* also signal pending data, but the converse does
* not hold. For example, in DTLS there might be
* further records waiting to be processed from
* the current underlying transport's datagram.
*
* \note If this function returns 1 (data pending), this
* does not imply that a subsequent call to
* \c mbedtls_ssl_read will provide any data;
* e.g., the unprocessed data might turn out
* to be an alert or a handshake message.
*
* \note This function is useful in the following situation:
* If the SSL/TLS module successfully returns from an
* operation - e.g. a handshake or an application record
* read - and you're awaiting incoming data next, you
* must not immediately idle on the underlying transport
* to have data ready, but you need to check the value
* of this function first. The reason is that the desired
* data might already be read but not yet processed.
* If, in contrast, a previous call to the SSL/TLS module
* returned MBEDTLS_ERR_SSL_WANT_READ, it is not necessary
* to call this function, as the latter error code entails
* that all internal data has been processed.
*
*/
int mbedtls_ssl_check_pending( const mbedtls_ssl_context *ssl );
/**
* \brief Return the number of application data bytes
* remaining to be read from the current record.
* *
* \param ssl SSL context * \param ssl SSL context
* *
* \return how many bytes are available in the read buffer * \return How many bytes are available in the application
* data record read buffer.
*
* \note When working over a datagram transport, this is
* useful to detect the current datagram's boundary
* in case \c mbedtls_ssl_read has written the maximal
* amount of data fitting into the input buffer.
*
*/ */
size_t mbedtls_ssl_get_bytes_avail( const mbedtls_ssl_context *ssl ); size_t mbedtls_ssl_get_bytes_avail( const mbedtls_ssl_context *ssl );
...@@ -2328,6 +2821,9 @@ const char *mbedtls_ssl_get_version( const mbedtls_ssl_context *ssl ); ...@@ -2328,6 +2821,9 @@ const char *mbedtls_ssl_get_version( const mbedtls_ssl_context *ssl );
* \brief Return the (maximum) number of bytes added by the record * \brief Return the (maximum) number of bytes added by the record
* layer: header + encryption/MAC overhead (inc. padding) * layer: header + encryption/MAC overhead (inc. padding)
* *
* \note This function is not available (always returns an error)
* when record compression is enabled.
*
* \param ssl SSL context * \param ssl SSL context
* *
* \return Current maximum record expansion in bytes, or * \return Current maximum record expansion in bytes, or
...@@ -2342,6 +2838,23 @@ int mbedtls_ssl_get_record_expansion( const mbedtls_ssl_context *ssl ); ...@@ -2342,6 +2838,23 @@ int mbedtls_ssl_get_record_expansion( const mbedtls_ssl_context *ssl );
* This is the value negotiated with peer if any, * This is the value negotiated with peer if any,
* or the locally configured value. * or the locally configured value.
* *
* \sa mbedtls_ssl_conf_max_frag_len()
* \sa mbedtls_ssl_get_max_record_payload()
*
* \param ssl SSL context
*
* \return Current maximum fragment length.
*/
size_t mbedtls_ssl_get_max_frag_len( const mbedtls_ssl_context *ssl );
#endif /* MBEDTLS_SSL_MAX_FRAGMENT_LENGTH */
/**
* \brief Return the current maximum outgoing record payload in bytes.
* This takes into account the config.h setting \c
* MBEDTLS_SSL_OUT_CONTENT_LEN, the configured and negotiated
* max fragment length extension if used, and for DTLS the
* path MTU as configured and current record expansion.
*
* \note With DTLS, \c mbedtls_ssl_write() will return an error if * \note With DTLS, \c mbedtls_ssl_write() will return an error if
* called with a larger length value. * called with a larger length value.
* With TLS, \c mbedtls_ssl_write() will fragment the input if * With TLS, \c mbedtls_ssl_write() will fragment the input if
...@@ -2349,12 +2862,19 @@ int mbedtls_ssl_get_record_expansion( const mbedtls_ssl_context *ssl ); ...@@ -2349,12 +2862,19 @@ int mbedtls_ssl_get_record_expansion( const mbedtls_ssl_context *ssl );
* to the caller to call \c mbedtls_ssl_write() again in * to the caller to call \c mbedtls_ssl_write() again in
* order to send the remaining bytes if any. * order to send the remaining bytes if any.
* *
* \note This function is not available (always returns an error)
* when record compression is enabled.
*
* \sa mbedtls_ssl_set_mtu()
* \sa mbedtls_ssl_get_max_frag_len()
* \sa mbedtls_ssl_get_record_expansion()
*
* \param ssl SSL context * \param ssl SSL context
* *
* \return Current maximum fragment length. * \return Current maximum payload for an outgoing record,
* or a negative error code.
*/ */
size_t mbedtls_ssl_get_max_frag_len( const mbedtls_ssl_context *ssl ); int mbedtls_ssl_get_max_out_record_payload( const mbedtls_ssl_context *ssl );
#endif /* MBEDTLS_SSL_MAX_FRAGMENT_LENGTH */
#if defined(MBEDTLS_X509_CRT_PARSE_C) #if defined(MBEDTLS_X509_CRT_PARSE_C)
/** /**
...@@ -2409,21 +2929,50 @@ int mbedtls_ssl_get_session( const mbedtls_ssl_context *ssl, mbedtls_ssl_session ...@@ -2409,21 +2929,50 @@ int mbedtls_ssl_get_session( const mbedtls_ssl_context *ssl, mbedtls_ssl_session
* *
* \param ssl SSL context * \param ssl SSL context
* *
* \return 0 if successful, or * \return \c 0 if successful.
* MBEDTLS_ERR_SSL_WANT_READ or MBEDTLS_ERR_SSL_WANT_WRITE, or * \return #MBEDTLS_ERR_SSL_WANT_READ or #MBEDTLS_ERR_SSL_WANT_WRITE
* MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED (see below), or * if the handshake is incomplete and waiting for data to
* a specific SSL error code. * be available for reading from or writing to the underlying
* * transport - in this case you must call this function again
* \note If this function returns something other than 0 or * when the underlying transport is ready for the operation.
* MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context * \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if an asynchronous
* becomes unusable, and you should either free it or call * operation is in progress (see
* \c mbedtls_ssl_session_reset() on it before re-using it for * mbedtls_ssl_conf_async_private_cb()) - in this case you
* a new connection; the current connection must be closed. * must call this function again when the operation is ready.
* \return #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS if a cryptographic
* operation is in progress (see mbedtls_ecp_set_max_ops()) -
* in this case you must call this function again to complete
* the handshake when you're done attending other tasks.
* \return #MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED if DTLS is in use
* and the client did not demonstrate reachability yet - in
* this case you must stop using the context (see below).
* \return Another SSL error code - in this case you must stop using
* the context (see below).
*
* \warning If this function returns something other than
* \c 0,
* #MBEDTLS_ERR_SSL_WANT_READ,
* #MBEDTLS_ERR_SSL_WANT_WRITE,
* #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or
* #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS,
* you must stop using the SSL context for reading or writing,
* and either free it or call \c mbedtls_ssl_session_reset()
* on it before re-using it for a new connection; the current
* connection must be closed.
* *
* \note If DTLS is in use, then you may choose to handle * \note If DTLS is in use, then you may choose to handle
* MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED specially for logging * #MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED specially for logging
* purposes, as it is an expected return value rather than an * purposes, as it is an expected return value rather than an
* actual error, but you still need to reset/free the context. * actual error, but you still need to reset/free the context.
*
* \note Remarks regarding event-driven DTLS:
* If the function returns #MBEDTLS_ERR_SSL_WANT_READ, no datagram
* from the underlying transport layer is currently being processed,
* and it is safe to idle until the timer or the underlying transport
* signal a new event. This is not true for a successful handshake,
* in which case the datagram of the underlying transport that is
* currently being processed might or might not contain further
* DTLS records.
*/ */
int mbedtls_ssl_handshake( mbedtls_ssl_context *ssl ); int mbedtls_ssl_handshake( mbedtls_ssl_context *ssl );
...@@ -2431,20 +2980,21 @@ int mbedtls_ssl_handshake( mbedtls_ssl_context *ssl ); ...@@ -2431,20 +2980,21 @@ int mbedtls_ssl_handshake( mbedtls_ssl_context *ssl );
* \brief Perform a single step of the SSL handshake * \brief Perform a single step of the SSL handshake
* *
* \note The state of the context (ssl->state) will be at * \note The state of the context (ssl->state) will be at
* the next state after execution of this function. Do not * the next state after this function returns \c 0. Do not
* call this function if state is MBEDTLS_SSL_HANDSHAKE_OVER. * call this function if state is MBEDTLS_SSL_HANDSHAKE_OVER.
* *
* \note If this function returns something other than 0 or
* MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context
* becomes unusable, and you should either free it or call
* \c mbedtls_ssl_session_reset() on it before re-using it for
* a new connection; the current connection must be closed.
*
* \param ssl SSL context * \param ssl SSL context
* *
* \return 0 if successful, or * \return See mbedtls_ssl_handshake().
* MBEDTLS_ERR_SSL_WANT_READ or MBEDTLS_ERR_SSL_WANT_WRITE, or *
* a specific SSL error code. * \warning If this function returns something other than \c 0,
* #MBEDTLS_ERR_SSL_WANT_READ, #MBEDTLS_ERR_SSL_WANT_WRITE,
* #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or
* #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS, you must stop using
* the SSL context for reading or writing, and either free it
* or call \c mbedtls_ssl_session_reset() on it before
* re-using it for a new connection; the current connection
* must be closed.
*/ */
int mbedtls_ssl_handshake_step( mbedtls_ssl_context *ssl ); int mbedtls_ssl_handshake_step( mbedtls_ssl_context *ssl );
...@@ -2459,13 +3009,18 @@ int mbedtls_ssl_handshake_step( mbedtls_ssl_context *ssl ); ...@@ -2459,13 +3009,18 @@ int mbedtls_ssl_handshake_step( mbedtls_ssl_context *ssl );
* \param ssl SSL context * \param ssl SSL context
* *
* \return 0 if successful, or any mbedtls_ssl_handshake() return * \return 0 if successful, or any mbedtls_ssl_handshake() return
* value. * value except #MBEDTLS_ERR_SSL_CLIENT_RECONNECT that can't
* happen during a renegotiation.
*
* \warning If this function returns something other than \c 0,
* #MBEDTLS_ERR_SSL_WANT_READ, #MBEDTLS_ERR_SSL_WANT_WRITE,
* #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or
* #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS, you must stop using
* the SSL context for reading or writing, and either free it
* or call \c mbedtls_ssl_session_reset() on it before
* re-using it for a new connection; the current connection
* must be closed.
* *
* \note If this function returns something other than 0 or
* MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context
* becomes unusable, and you should either free it or call
* \c mbedtls_ssl_session_reset() on it before re-using it for
* a new connection; the current connection must be closed.
*/ */
int mbedtls_ssl_renegotiate( mbedtls_ssl_context *ssl ); int mbedtls_ssl_renegotiate( mbedtls_ssl_context *ssl );
#endif /* MBEDTLS_SSL_RENEGOTIATION */ #endif /* MBEDTLS_SSL_RENEGOTIATION */
...@@ -2477,32 +3032,68 @@ int mbedtls_ssl_renegotiate( mbedtls_ssl_context *ssl ); ...@@ -2477,32 +3032,68 @@ int mbedtls_ssl_renegotiate( mbedtls_ssl_context *ssl );
* \param buf buffer that will hold the data * \param buf buffer that will hold the data
* \param len maximum number of bytes to read * \param len maximum number of bytes to read
* *
* \return the number of bytes read, or * \return The (positive) number of bytes read if successful.
* 0 for EOF, or * \return \c 0 if the read end of the underlying transport was closed
* MBEDTLS_ERR_SSL_WANT_READ or MBEDTLS_ERR_SSL_WANT_WRITE, or * - in this case you must stop using the context (see below).
* MBEDTLS_ERR_SSL_CLIENT_RECONNECT (see below), or * \return #MBEDTLS_ERR_SSL_WANT_READ or #MBEDTLS_ERR_SSL_WANT_WRITE
* another negative error code. * if the handshake is incomplete and waiting for data to
* * be available for reading from or writing to the underlying
* \note If this function returns something other than a positive * transport - in this case you must call this function again
* value or MBEDTLS_ERR_SSL_WANT_READ/WRITE or * when the underlying transport is ready for the operation.
* MBEDTLS_ERR_SSL_CLIENT_RECONNECT, then the ssl context * \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if an asynchronous
* becomes unusable, and you should either free it or call * operation is in progress (see
* \c mbedtls_ssl_session_reset() on it before re-using it for * mbedtls_ssl_conf_async_private_cb()) - in this case you
* a new connection; the current connection must be closed. * must call this function again when the operation is ready.
* * \return #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS if a cryptographic
* \note When this function return MBEDTLS_ERR_SSL_CLIENT_RECONNECT * operation is in progress (see mbedtls_ecp_set_max_ops()) -
* in this case you must call this function again to complete
* the handshake when you're done attending other tasks.
* \return #MBEDTLS_ERR_SSL_CLIENT_RECONNECT if we're at the server
* side of a DTLS connection and the client is initiating a
* new connection using the same source port. See below.
* \return Another SSL error code - in this case you must stop using
* the context (see below).
*
* \warning If this function returns something other than
* a positive value,
* #MBEDTLS_ERR_SSL_WANT_READ,
* #MBEDTLS_ERR_SSL_WANT_WRITE,
* #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS,
* #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS or
* #MBEDTLS_ERR_SSL_CLIENT_RECONNECT,
* you must stop using the SSL context for reading or writing,
* and either free it or call \c mbedtls_ssl_session_reset()
* on it before re-using it for a new connection; the current
* connection must be closed.
*
* \note When this function returns #MBEDTLS_ERR_SSL_CLIENT_RECONNECT
* (which can only happen server-side), it means that a client * (which can only happen server-side), it means that a client
* is initiating a new connection using the same source port. * is initiating a new connection using the same source port.
* You can either treat that as a connection close and wait * You can either treat that as a connection close and wait
* for the client to resend a ClientHello, or directly * for the client to resend a ClientHello, or directly
* continue with \c mbedtls_ssl_handshake() with the same * continue with \c mbedtls_ssl_handshake() with the same
* context (as it has beeen reset internally). Either way, you * context (as it has been reset internally). Either way, you
* should make sure this is seen by the application as a new * must make sure this is seen by the application as a new
* connection: application state, if any, should be reset, and * connection: application state, if any, should be reset, and
* most importantly the identity of the client must be checked * most importantly the identity of the client must be checked
* again. WARNING: not validating the identity of the client * again. WARNING: not validating the identity of the client
* again, or not transmitting the new identity to the * again, or not transmitting the new identity to the
* application layer, would allow authentication bypass! * application layer, would allow authentication bypass!
*
* \note Remarks regarding event-driven DTLS:
* - If the function returns #MBEDTLS_ERR_SSL_WANT_READ, no datagram
* from the underlying transport layer is currently being processed,
* and it is safe to idle until the timer or the underlying transport
* signal a new event.
* - This function may return MBEDTLS_ERR_SSL_WANT_READ even if data was
* initially available on the underlying transport, as this data may have
* been only e.g. duplicated messages or a renegotiation request.
* Therefore, you must be prepared to receive MBEDTLS_ERR_SSL_WANT_READ even
* when reacting to an incoming-data event from the underlying transport.
* - On success, the datagram of the underlying transport that is currently
* being processed may contain further DTLS records. You should call
* \c mbedtls_ssl_check_pending to check for remaining records.
*
*/ */
int mbedtls_ssl_read( mbedtls_ssl_context *ssl, unsigned char *buf, size_t len ); int mbedtls_ssl_read( mbedtls_ssl_context *ssl, unsigned char *buf, size_t len );
...@@ -2519,21 +3110,39 @@ int mbedtls_ssl_read( mbedtls_ssl_context *ssl, unsigned char *buf, size_t len ) ...@@ -2519,21 +3110,39 @@ int mbedtls_ssl_read( mbedtls_ssl_context *ssl, unsigned char *buf, size_t len )
* \param buf buffer holding the data * \param buf buffer holding the data
* \param len how many bytes must be written * \param len how many bytes must be written
* *
* \return the number of bytes actually written (may be less than len), * \return The (non-negative) number of bytes actually written if
* or MBEDTLS_ERR_SSL_WANT_WRITE or MBEDTLS_ERR_SSL_WANT_READ, * successful (may be less than \p len).
* or another negative error code. * \return #MBEDTLS_ERR_SSL_WANT_READ or #MBEDTLS_ERR_SSL_WANT_WRITE
* * if the handshake is incomplete and waiting for data to
* \note If this function returns something other than 0, a positive * be available for reading from or writing to the underlying
* value or MBEDTLS_ERR_SSL_WANT_READ/WRITE, you must stop * transport - in this case you must call this function again
* using the SSL context for reading or writing, and either * when the underlying transport is ready for the operation.
* free it or call \c mbedtls_ssl_session_reset() on it before * \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if an asynchronous
* re-using it for a new connection; the current connection * operation is in progress (see
* must be closed. * mbedtls_ssl_conf_async_private_cb()) - in this case you
* * must call this function again when the operation is ready.
* \note When this function returns MBEDTLS_ERR_SSL_WANT_WRITE/READ, * \return #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS if a cryptographic
* operation is in progress (see mbedtls_ecp_set_max_ops()) -
* in this case you must call this function again to complete
* the handshake when you're done attending other tasks.
* \return Another SSL error code - in this case you must stop using
* the context (see below).
*
* \warning If this function returns something other than
* a non-negative value,
* #MBEDTLS_ERR_SSL_WANT_READ,
* #MBEDTLS_ERR_SSL_WANT_WRITE,
* #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or
* #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS,
* you must stop using the SSL context for reading or writing,
* and either free it or call \c mbedtls_ssl_session_reset()
* on it before re-using it for a new connection; the current
* connection must be closed.
*
* \note When this function returns #MBEDTLS_ERR_SSL_WANT_WRITE/READ,
* it must be called later with the *same* arguments, * it must be called later with the *same* arguments,
* until it returns a value greater that or equal to 0. When * until it returns a value greater that or equal to 0. When
* the function returns MBEDTLS_ERR_SSL_WANT_WRITE there may be * the function returns #MBEDTLS_ERR_SSL_WANT_WRITE there may be
* some partial data in the output buffer, however this is not * some partial data in the output buffer, however this is not
* yet sent. * yet sent.
* *
...@@ -2561,10 +3170,10 @@ int mbedtls_ssl_write( mbedtls_ssl_context *ssl, const unsigned char *buf, size_ ...@@ -2561,10 +3170,10 @@ int mbedtls_ssl_write( mbedtls_ssl_context *ssl, const unsigned char *buf, size_
* \return 0 if successful, or a specific SSL error code. * \return 0 if successful, or a specific SSL error code.
* *
* \note If this function returns something other than 0 or * \note If this function returns something other than 0 or
* MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context * MBEDTLS_ERR_SSL_WANT_READ/WRITE, you must stop using
* becomes unusable, and you should either free it or call * the SSL context for reading or writing, and either free it or
* \c mbedtls_ssl_session_reset() on it before re-using it for * call \c mbedtls_ssl_session_reset() on it before re-using it
* a new connection; the current connection must be closed. * for a new connection; the current connection must be closed.
*/ */
int mbedtls_ssl_send_alert_message( mbedtls_ssl_context *ssl, int mbedtls_ssl_send_alert_message( mbedtls_ssl_context *ssl,
unsigned char level, unsigned char level,
...@@ -2577,10 +3186,10 @@ int mbedtls_ssl_send_alert_message( mbedtls_ssl_context *ssl, ...@@ -2577,10 +3186,10 @@ int mbedtls_ssl_send_alert_message( mbedtls_ssl_context *ssl,
* \return 0 if successful, or a specific SSL error code. * \return 0 if successful, or a specific SSL error code.
* *
* \note If this function returns something other than 0 or * \note If this function returns something other than 0 or
* MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context * MBEDTLS_ERR_SSL_WANT_READ/WRITE, you must stop using
* becomes unusable, and you should either free it or call * the SSL context for reading or writing, and either free it or
* \c mbedtls_ssl_session_reset() on it before re-using it for * call \c mbedtls_ssl_session_reset() on it before re-using it
* a new connection; the current connection must be closed. * for a new connection; the current connection must be closed.
*/ */
int mbedtls_ssl_close_notify( mbedtls_ssl_context *ssl ); int mbedtls_ssl_close_notify( mbedtls_ssl_context *ssl );
...@@ -2597,7 +3206,7 @@ void mbedtls_ssl_free( mbedtls_ssl_context *ssl ); ...@@ -2597,7 +3206,7 @@ void mbedtls_ssl_free( mbedtls_ssl_context *ssl );
* mbedtls_ssl_config_defaults() or mbedtls_ssl_config_free(). * mbedtls_ssl_config_defaults() or mbedtls_ssl_config_free().
* *
* \note You need to call mbedtls_ssl_config_defaults() unless you * \note You need to call mbedtls_ssl_config_defaults() unless you
* manually set all of the relevent fields yourself. * manually set all of the relevant fields yourself.
* *
* \param conf SSL configuration context * \param conf SSL configuration context
*/ */
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment