File pkcs11.h

Wrapper for PKCS#11 library libpkcs11-helper.

Author

Adriaan de Jong dejong@fox-it.com

Defines

MBEDTLS_DEPRECATED

Typedefs

typedef struct mbedtls_pkcs11_context mbedtls_pkcs11_context

Context for PKCS #11 private keys.

Functions

MBEDTLS_DEPRECATED void mbedtls_pkcs11_init (mbedtls_pkcs11_context *ctx)

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.

MBEDTLS_DEPRECATED int mbedtls_pkcs11_x509_cert_bind (mbedtls_x509_crt *cert, pkcs11h_certificate_t pkcs11h_cert)

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.

Parameters

  • cert – X.509 certificate to fill

  • pkcs11h_cert – PKCS #11 helper certificate

Returns

0 on success.

MBEDTLS_DEPRECATED int mbedtls_pkcs11_priv_key_bind (mbedtls_pkcs11_context *priv_key, pkcs11h_certificate_t pkcs11_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.

Parameters

  • priv_key – Private key structure to fill.

  • pkcs11_cert – PKCS #11 helper certificate

Returns

0 on success

MBEDTLS_DEPRECATED void mbedtls_pkcs11_priv_key_free (mbedtls_pkcs11_context *priv_key)

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.

Parameters

priv_key – Private key structure to cleanup

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)

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.

Note

The output buffer must be as large as the size of ctx->N (eg. 128 bytes if RSA-1024 is used) otherwise an error is thrown.

Parameters

  • ctx – PKCS #11 context

  • mode – must be MBEDTLS_RSA_PRIVATE, for compatibility with rsa.c’s signature

  • input – buffer holding the encrypted data

  • output – buffer that will hold the plaintext

  • olen – will contain the plaintext length

  • output_max_len – maximum length of the output buffer

Returns

0 if successful, or an MBEDTLS_ERR_RSA_XXX error code

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)

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.

Note

The “sig” buffer must be as large as the size of ctx->N (eg. 128 bytes if RSA-1024 is used).

Parameters

  • ctx – PKCS #11 context

  • mode – must be MBEDTLS_RSA_PRIVATE, for compatibility with rsa.c’s signature

  • md_alg – a MBEDTLS_MD_XXX (use MBEDTLS_MD_NONE for signing raw data)

  • hashlen – message digest length (for MBEDTLS_MD_NONE only)

  • hash – buffer holding the message digest

  • sig – buffer that will hold the ciphertext

Returns

0 if the signing operation was successful, or an MBEDTLS_ERR_RSA_XXX error code

static inline MBEDTLS_DEPRECATED int mbedtls_ssl_pkcs11_decrypt (void *ctx, int mode, size_t *olen, const unsigned char *input, unsigned char *output, size_t output_max_len)

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 MBEDTLS_DEPRECATED 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)

This function signs a message digest using RSA.

Deprecated:

This function is deprecated and will be removed in a future version of the library.

Note

The sig buffer must be as large as the size of ctx->N. For example, 128 bytes if RSA-1024 is used.

Parameters

  • ctx – The PKCS #11 context.

  • f_rng – The RNG function. This parameter is unused.

  • p_rng – The RNG context. This parameter is unused.

  • mode – The operation to run. This must be set to MBEDTLS_RSA_PRIVATE, for compatibility with rsa.c’s signature.

  • 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.

  • hashlen – The message digest length (for MBEDTLS_MD_NONE only).

  • hash – The buffer holding the message digest.

  • sig – The buffer that will hold the ciphertext.

Returns

0 if the signing operation was successful.

Returns

A non-zero error code on failure.

static inline MBEDTLS_DEPRECATED 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.

Parameters

ctx – The PKCS #11 context.

Returns

The length of the private key.

struct mbedtls_pkcs11_context
#include <pkcs11.h>

Context for PKCS #11 private keys.

Public Members

pkcs11h_certificate_t pkcs11h_cert
int len