diff --git a/ChangeLog b/ChangeLog index 2f6480ec8..51478d5db 100644 --- a/ChangeLog +++ b/ChangeLog @@ -6,6 +6,9 @@ New deprecations * Deprecate MBEDTLS_SSL_SRV_SUPPORT_SSLV2_CLIENT_HELLO that enables parsing SSLv2 ClientHello messages. * Deprecate MBEDTLS_SSL_PROTO_SSL3 that enables support for SSLv3. + * Deprecate for MBEDTLS_PKCS11_C, the wrapper around the pkcs11-helper + library which allows TLS authentication to use keys stored in a + PKCS#11 token such as a smartcard. Bugfix * Allow loading symlinked certificates. Fixes #3005. Reported and fixed diff --git a/include/mbedtls/check_config.h b/include/mbedtls/check_config.h index d95b71e53..ec1142668 100644 --- a/include/mbedtls/check_config.h +++ b/include/mbedtls/check_config.h @@ -342,6 +342,14 @@ #error "MBEDTLS_PKCS11_C defined, but not all prerequisites" #endif +#if defined(MBEDTLS_PKCS11_C) +#if defined(MBEDTLS_DEPRECATED_REMOVED) +#error "MBEDTLS_PKCS11_C is deprecated and will be removed in a future version of Mbed TLS" +#elif defined(MBEDTLS_DEPRECATED_WARNING) +#warning "MBEDTLS_PKCS11_C is deprecated and will be removed in a future version of Mbed TLS" +#endif +#endif /* MBEDTLS_PKCS11_C */ + #if defined(MBEDTLS_PLATFORM_EXIT_ALT) && !defined(MBEDTLS_PLATFORM_C) #error "MBEDTLS_PLATFORM_EXIT_ALT defined, but not all prerequisites" #endif diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h index a11a4f3b0..7abdaa5e7 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -2818,7 +2818,10 @@ /** * \def MBEDTLS_PKCS11_C * - * Enable wrapper for PKCS#11 smartcard support. + * Enable wrapper for PKCS#11 smartcard support via the pkcs11-helper library. + * + * \deprecated This option is deprecated and will be removed in a future + * version of Mbed TLS. * * Module: library/pkcs11.c * Caller: library/pk.c diff --git a/include/mbedtls/pkcs11.h b/include/mbedtls/pkcs11.h index d9f45db67..cf8d8c429 100644 --- a/include/mbedtls/pkcs11.h +++ b/include/mbedtls/pkcs11.h @@ -47,6 +47,8 @@ extern "C" { #endif +#if defined(MBEDTLS_DEPRECATED_REMOVED) + /** * Context for PKCS #11 private keys. */ @@ -56,47 +58,71 @@ typedef struct mbedtls_pkcs11_context int len; } mbedtls_pkcs11_context; +#if defined(MBEDTLS_DEPRECATED_WARNING) +#define MBEDTLS_DEPRECATED __attribute__((deprecated)) +#else +#define MBEDTLS_DEPRECATED +#endif + /** * Initialize a mbedtls_pkcs11_context. * (Just making memory references valid.) + * + * \deprecated This function is deprecated and will be removed in a + * future version of the library. */ -void mbedtls_pkcs11_init( mbedtls_pkcs11_context *ctx ); +MBEDTLS_DEPRECATED void mbedtls_pkcs11_init( mbedtls_pkcs11_context *ctx ); /** * Fill in a mbed TLS certificate, based on the given PKCS11 helper certificate. * + * \deprecated This function is deprecated and will be removed in a + * future version of the library. + * * \param cert X.509 certificate to fill * \param pkcs11h_cert PKCS #11 helper certificate * * \return 0 on success. */ -int mbedtls_pkcs11_x509_cert_bind( mbedtls_x509_crt *cert, pkcs11h_certificate_t pkcs11h_cert ); +MBEDTLS_DEPRECATED int mbedtls_pkcs11_x509_cert_bind( mbedtls_x509_crt *cert, + pkcs11h_certificate_t pkcs11h_cert ); /** * Set up a mbedtls_pkcs11_context storing the given certificate. Note that the * mbedtls_pkcs11_context will take over control of the certificate, freeing it when * done. * + * \deprecated This function is deprecated and will be removed in a + * future version of the library. + * * \param priv_key Private key structure to fill. * \param pkcs11_cert PKCS #11 helper certificate * * \return 0 on success */ -int mbedtls_pkcs11_priv_key_bind( mbedtls_pkcs11_context *priv_key, - pkcs11h_certificate_t pkcs11_cert ); +MBEDTLS_DEPRECATED int mbedtls_pkcs11_priv_key_bind( + mbedtls_pkcs11_context *priv_key, + pkcs11h_certificate_t pkcs11_cert ); /** * Free the contents of the given private key context. Note that the structure * itself is not freed. * + * \deprecated This function is deprecated and will be removed in a + * future version of the library. + * * \param priv_key Private key structure to cleanup */ -void mbedtls_pkcs11_priv_key_free( mbedtls_pkcs11_context *priv_key ); +MBEDTLS_DEPRECATED void mbedtls_pkcs11_priv_key_free( + mbedtls_pkcs11_context *priv_key ); /** * \brief Do an RSA private key decrypt, then remove the message * padding * + * \deprecated This function is deprecated and will be removed in a future + * version of the library. + * * \param ctx PKCS #11 context * \param mode must be MBEDTLS_RSA_PRIVATE, for compatibility with rsa.c's signature * \param input buffer holding the encrypted data @@ -110,15 +136,18 @@ void mbedtls_pkcs11_priv_key_free( mbedtls_pkcs11_context *priv_key ); * of ctx->N (eg. 128 bytes if RSA-1024 is used) otherwise * an error is thrown. */ -int mbedtls_pkcs11_decrypt( mbedtls_pkcs11_context *ctx, - int mode, size_t *olen, - const unsigned char *input, - unsigned char *output, - size_t output_max_len ); +MBEDTLS_DEPRECATED int mbedtls_pkcs11_decrypt( mbedtls_pkcs11_context *ctx, + int mode, size_t *olen, + const unsigned char *input, + unsigned char *output, + size_t output_max_len ); /** * \brief Do a private RSA to sign a message digest * + * \deprecated This function is deprecated and will be removed in a future + * version of the library. + * * \param ctx PKCS #11 context * \param mode must be MBEDTLS_RSA_PRIVATE, for compatibility with rsa.c's signature * \param md_alg a MBEDTLS_MD_XXX (use MBEDTLS_MD_NONE for signing raw data) @@ -132,28 +161,58 @@ int mbedtls_pkcs11_decrypt( mbedtls_pkcs11_context *ctx, * \note The "sig" buffer must be as large as the size * of ctx->N (eg. 128 bytes if RSA-1024 is used). */ -int mbedtls_pkcs11_sign( mbedtls_pkcs11_context *ctx, - int mode, - mbedtls_md_type_t md_alg, - unsigned int hashlen, - const unsigned char *hash, - unsigned char *sig ); +MBEDTLS_DEPRECATED int mbedtls_pkcs11_sign( mbedtls_pkcs11_context *ctx, + int mode, + mbedtls_md_type_t md_alg, + unsigned int hashlen, + const unsigned char *hash, + unsigned char *sig ); /** * SSL/TLS wrappers for PKCS#11 functions + * + * \deprecated This function is deprecated and will be removed in a future + * version of the library. */ -static inline int mbedtls_ssl_pkcs11_decrypt( void *ctx, int mode, size_t *olen, - const unsigned char *input, unsigned char *output, - size_t output_max_len ) +MBEDTLS_DEPRECATED static inline int mbedtls_ssl_pkcs11_decrypt( void *ctx, + int mode, size_t *olen, + const unsigned char *input, unsigned char *output, + size_t output_max_len ) { return mbedtls_pkcs11_decrypt( (mbedtls_pkcs11_context *) ctx, mode, olen, input, output, output_max_len ); } -static inline int mbedtls_ssl_pkcs11_sign( void *ctx, - int (*f_rng)(void *, unsigned char *, size_t), void *p_rng, - int mode, mbedtls_md_type_t md_alg, unsigned int hashlen, - const unsigned char *hash, unsigned char *sig ) +/** + * \brief This function signs a message digest using RSA. + * + * \deprecated This function is deprecated and will be removed in a future + * version of the library. + * + * \param ctx The PKCS #11 context. + * \param f_rng The RNG function. This parameter is unused. + * \param p_rng The RNG context. This parameter is unused. + * \param mode The operation to run. This must be set to + * MBEDTLS_RSA_PRIVATE, for compatibility with rsa.c's + * signature. + * \param md_alg The message digest algorithm. One of the MBEDTLS_MD_XXX + * must be passed to this function and MBEDTLS_MD_NONE can be + * used for signing raw data. + * \param hashlen The message digest length (for MBEDTLS_MD_NONE only). + * \param hash The buffer holding the message digest. + * \param sig The buffer that will hold the ciphertext. + * + * \return \c 0 if the signing operation was successful. + * \return A non-zero error code on failure. + * + * \note The \p sig buffer must be as large as the size of + * ctx->N. For example, 128 bytes if RSA-1024 is + * used. + */ +MBEDTLS_DEPRECATED static inline int mbedtls_ssl_pkcs11_sign( void *ctx, + int (*f_rng)(void *, unsigned char *, size_t), void *p_rng, + int mode, mbedtls_md_type_t md_alg, unsigned int hashlen, + const unsigned char *hash, unsigned char *sig ) { ((void) f_rng); ((void) p_rng); @@ -161,11 +220,25 @@ static inline int mbedtls_ssl_pkcs11_sign( void *ctx, hashlen, hash, sig ); } -static inline size_t mbedtls_ssl_pkcs11_key_len( void *ctx ) +/** + * This function gets the length of the private key. + * + * \deprecated This function is deprecated and will be removed in a future + * version of the library. + * + * \param ctx The PKCS #11 context. + * + * \return The length of the private key. + */ +MBEDTLS_DEPRECATED static inline size_t mbedtls_ssl_pkcs11_key_len( void *ctx ) { return ( (mbedtls_pkcs11_context *) ctx )->len; } +#undef MBEDTLS_DEPRECATED + +#endif /* MBEDTLS_DEPRECATED_REMOVED */ + #ifdef __cplusplus } #endif