Loading...
Searching...
No Matches
pkcs12.h File Reference

PKCS#12 Personal Information Exchange Syntax. More...

`#include "mbedtls/config.h"`
`#include "mbedtls/md.h"`
`#include "mbedtls/cipher.h"`
`#include "mbedtls/asn1.h"`
`#include <stddef.h>`
Include dependency graph for pkcs12.h:

Go to the source code of this file.

## Macros

#define | MBEDTLS_ERR_PKCS12_BAD_INPUT_DATA -0x1F80
#define | MBEDTLS_ERR_PKCS12_FEATURE_UNAVAILABLE -0x1F00
#define | MBEDTLS_ERR_PKCS12_PBE_INVALID_FORMAT -0x1E80
#define | MBEDTLS_ERR_PKCS12_PASSWORD_MISMATCH -0x1E00
#define | MBEDTLS_PKCS12_DERIVE_KEY 1
#define | MBEDTLS_PKCS12_DERIVE_IV 2
#define | MBEDTLS_PKCS12_DERIVE_MAC_KEY 3
#define | MBEDTLS_PKCS12_PBE_DECRYPT 0
#define | MBEDTLS_PKCS12_PBE_ENCRYPT 1

## Functions

int | mbedtls_pkcs12_pbe_sha1_rc4_128 (mbedtls_asn1_buf *pbe_params, int mode, const unsigned char *pwd, size_t pwdlen, const unsigned char *input, size_t len, unsigned char *output)
| PKCS12 Password Based function (encryption / decryption) for pbeWithSHAAnd128BitRC4.
int | mbedtls_pkcs12_pbe (mbedtls_asn1_buf *pbe_params, int mode, mbedtls_cipher_type_t cipher_type, mbedtls_md_type_t md_type, const unsigned char *pwd, size_t pwdlen, const unsigned char *data, size_t len, unsigned char *output)
| PKCS12 Password Based function (encryption / decryption) for cipher-based and mbedtls_md-based PBE's.
int | mbedtls_pkcs12_pbe_ext (mbedtls_asn1_buf *pbe_params, int mode, mbedtls_cipher_type_t cipher_type, mbedtls_md_type_t md_type, const unsigned char *pwd, size_t pwdlen, const unsigned char *data, size_t len, unsigned char *output, size_t output_size, size_t *output_len)
| PKCS12 Password Based function (encryption / decryption) for cipher-based and mbedtls_md-based PBE's.
int | mbedtls_pkcs12_derivation (unsigned char *data, size_t datalen, const unsigned char *pwd, size_t pwdlen, const unsigned char *salt, size_t saltlen, mbedtls_md_type_t mbedtls_md, int id, int iterations)
| The PKCS#12 derivation function uses a password and a salt to produce pseudo-random bits for a particular "purpose".

## Detailed Description

PKCS#12 Personal Information Exchange Syntax.

Definition in file pkcs12.h.

## Macro Definition Documentation

## MBEDTLS_ERR_PKCS12_BAD_INPUT_DATA

#define MBEDTLS_ERR_PKCS12_BAD_INPUT_DATA -0x1F80

Bad input parameters to function.

Definition at line 26 of file pkcs12.h.

## MBEDTLS_ERR_PKCS12_FEATURE_UNAVAILABLE

#define MBEDTLS_ERR_PKCS12_FEATURE_UNAVAILABLE -0x1F00

Feature not available, e.g. unsupported encryption scheme.

Definition at line 28 of file pkcs12.h.

## MBEDTLS_ERR_PKCS12_PASSWORD_MISMATCH

#define MBEDTLS_ERR_PKCS12_PASSWORD_MISMATCH -0x1E00

Given private key password does not allow for correct decryption.

Definition at line 32 of file pkcs12.h.

## MBEDTLS_ERR_PKCS12_PBE_INVALID_FORMAT

#define MBEDTLS_ERR_PKCS12_PBE_INVALID_FORMAT -0x1E80

PBE ASN.1 data not as expected.

Definition at line 30 of file pkcs12.h.

## MBEDTLS_PKCS12_DERIVE_IV

#define MBEDTLS_PKCS12_DERIVE_IV 2

initialization vector

Definition at line 35 of file pkcs12.h.

## MBEDTLS_PKCS12_DERIVE_KEY

#define MBEDTLS_PKCS12_DERIVE_KEY 1

encryption/decryption key

Definition at line 34 of file pkcs12.h.

## MBEDTLS_PKCS12_DERIVE_MAC_KEY

#define MBEDTLS_PKCS12_DERIVE_MAC_KEY 3

integrity / MAC key

Definition at line 36 of file pkcs12.h.

## MBEDTLS_PKCS12_PBE_DECRYPT

#define MBEDTLS_PKCS12_PBE_DECRYPT 0

Definition at line 38 of file pkcs12.h.

## MBEDTLS_PKCS12_PBE_ENCRYPT

#define MBEDTLS_PKCS12_PBE_ENCRYPT 1

Definition at line 39 of file pkcs12.h.

## Function Documentation

## mbedtls_pkcs12_derivation()

int mbedtls_pkcs12_derivation | ( | unsigned char * | data,
|  | size_t | datalen,
|  | const unsigned char * | pwd,
|  | size_t | pwdlen,
|  | const unsigned char * | salt,
|  | size_t | saltlen,
|  | mbedtls_md_type_t | mbedtls_md,
|  | int | id,
|  | int | iterations
| ) |  |

The PKCS#12 derivation function uses a password and a salt to produce pseudo-random bits for a particular "purpose".

Depending on the given id, this function can produce an encryption/decryption key, an initialization vector or an integrity key.

Parameters

  data | buffer to store the derived data in
  datalen | length of buffer to fill
  pwd | The password to use. For compliance with PKCS#12 §B.1, this should be a BMPString, i.e. a Unicode string where each character is encoded as 2 bytes in big-endian order, with no byte order mark and with a null terminator (i.e. the last two bytes should be 0x00 0x00).
  pwdlen | length of the password (may be 0).
  salt | Salt buffer to use This may only be `NULL` when `saltlen` is 0.
  saltlen | length of the salt (may be zero)
  mbedtls_md | mbedtls_md type to use during the derivation
  id | id that describes the purpose (can be MBEDTLS_PKCS12_DERIVE_KEY, MBEDTLS_PKCS12_DERIVE_IV or MBEDTLS_PKCS12_DERIVE_MAC_KEY)
  iterations | number of iterations

Returns
  0 if successful, or a MD, BIGNUM type error.

## mbedtls_pkcs12_pbe()

int mbedtls_pkcs12_pbe | ( | mbedtls_asn1_buf * | pbe_params,
|  | int | mode,
|  | mbedtls_cipher_type_t | cipher_type,
|  | mbedtls_md_type_t | md_type,
|  | const unsigned char * | pwd,
|  | size_t | pwdlen,
|  | const unsigned char * | data,
|  | size_t | len,
|  | unsigned char * | output
| ) |  |

PKCS12 Password Based function (encryption / decryption) for cipher-based and mbedtls_md-based PBE's.

Note
  When encrypting, MBEDTLS_CIPHER_PADDING_PKCS7 must be enabled at compile time.

Warning
  When decrypting:
  - if MBEDTLS_CIPHER_PADDING_PKCS7 is enabled at compile time, this function validates the CBC padding and returns MBEDTLS_ERR_PKCS12_PASSWORD_MISMATCH if the padding is invalid. Note that this can help active adversaries attempting to brute-forcing the password. Note also that there is no guarantee that an invalid password will be detected (the chances of a valid padding with a random password are about 1/255).
  - if MBEDTLS_CIPHER_PADDING_PKCS7 is disabled at compile time, this function does not validate the CBC padding.

Parameters

  pbe_params | an ASN1 buffer containing the pkcs-12 PbeParams structure
  mode | either MBEDTLS_PKCS12_PBE_ENCRYPT or MBEDTLS_PKCS12_PBE_DECRYPT
  cipher_type | the cipher used
  md_type | the mbedtls_md used
  pwd | Latin1-encoded password used. This may only be `NULL` when `pwdlen` is 0. No null terminator should be used.
  pwdlen | length of the password (may be 0)
  data | the input data
  len | data length
  output | Output buffer. On success, it contains the encrypted or decrypted data, possibly followed by the CBC padding. On failure, the content is indeterminate. For decryption, there must be enough room for `len` bytes. For encryption, there must be enough room for `len` + 1 bytes, rounded up to the block size of the block cipher identified by `pbe_params`.

Returns
  0 if successful, or a MBEDTLS_ERR_XXX code

## mbedtls_pkcs12_pbe_ext()

int mbedtls_pkcs12_pbe_ext | ( | mbedtls_asn1_buf * | pbe_params,
|  | int | mode,
|  | mbedtls_cipher_type_t | cipher_type,
|  | mbedtls_md_type_t | md_type,
|  | const unsigned char * | pwd,
|  | size_t | pwdlen,
|  | const unsigned char * | data,
|  | size_t | len,
|  | unsigned char * | output,
|  | size_t | output_size,
|  | size_t * | output_len
| ) |  |

PKCS12 Password Based function (encryption / decryption) for cipher-based and mbedtls_md-based PBE's.

Warning
  When decrypting:
  - This function validates the CBC padding and returns MBEDTLS_ERR_PKCS12_PASSWORD_MISMATCH if the padding is invalid. Note that this can help active adversaries attempting to brute-forcing the password. Note also that there is no guarantee that an invalid password will be detected (the chances of a valid padding with a random password are about 1/255).

Parameters

  pbe_params | an ASN1 buffer containing the pkcs-12 PbeParams structure
  mode | either MBEDTLS_PKCS12_PBE_ENCRYPT or MBEDTLS_PKCS12_PBE_DECRYPT
  cipher_type | the cipher used
  md_type | the mbedtls_md used
  pwd | Latin1-encoded password used. This may only be `NULL` when `pwdlen` is 0. No null terminator should be used.
  pwdlen | length of the password (may be 0)
  data | the input data
  len | data length
  output | Output buffer. On success, it contains the encrypted or decrypted data, possibly followed by the CBC padding. On failure, the content is indeterminate. For decryption, there must be enough room for `len` bytes. For encryption, there must be enough room for `len` + 1 bytes, rounded up to the block size of the block cipher identified by `pbe_params`.
  output_size | size of output buffer. This must be big enough to accommodate for output plus padding data.
  output_len | On success, length of actual data written to the output buffer.

Returns
  0 if successful, or a MBEDTLS_ERR_XXX code

## mbedtls_pkcs12_pbe_sha1_rc4_128()

int mbedtls_pkcs12_pbe_sha1_rc4_128 | ( | mbedtls_asn1_buf * | pbe_params,
|  | int | mode,
|  | const unsigned char * | pwd,
|  | size_t | pwdlen,
|  | const unsigned char * | input,
|  | size_t | len,
|  | unsigned char * | output
| ) |  |

PKCS12 Password Based function (encryption / decryption) for pbeWithSHAAnd128BitRC4.

Parameters

  pbe_params | an ASN1 buffer containing the pkcs-12PbeParams structure
  mode | either MBEDTLS_PKCS12_PBE_ENCRYPT or MBEDTLS_PKCS12_PBE_DECRYPT
  pwd | the password used (may be NULL if no password is used)
  pwdlen | length of the password (may be 0)
  input | the input data
  len | data length
  output | the output buffer

Returns
  0 if successful, or a MBEDTLS_ERR_XXX code