File pem.h

Privacy Enhanced Mail (PEM) decoding.

PEM Error codes

These error codes are returned in case of errors reading the PEM data.

No PEM header or footer found.

MBEDTLS_ERR_PEM_INVALID_DATA

PEM string is not as expected.

MBEDTLS_ERR_PEM_ALLOC_FAILED

Failed to allocate memory.

MBEDTLS_ERR_PEM_INVALID_ENC_IV

RSA IV is not in hex-format.

MBEDTLS_ERR_PEM_UNKNOWN_ENC_ALG

Unsupported key encryption algorithm.

MBEDTLS_ERR_PEM_PASSWORD_REQUIRED

Private key password can’t be empty.

MBEDTLS_ERR_PEM_PASSWORD_MISMATCH

Given private key password does not allow for correct decryption.

MBEDTLS_ERR_PEM_FEATURE_UNAVAILABLE

Unavailable feature, e.g. hashing/encryption combination.

MBEDTLS_ERR_PEM_BAD_INPUT_DATA

Bad input parameters to function.

Typedefs

typedef struct mbedtls_pem_context mbedtls_pem_context

PEM context structure.

Functions

void mbedtls_pem_init(mbedtls_pem_context *ctx)

PEM context setup.

Parameters

ctx – context to be initialized

int mbedtls_pem_read_buffer(mbedtls_pem_context *ctx, const char *header, const char *footer, const unsigned char *data, const unsigned char *pwd, size_t pwdlen, size_t *use_len)

Read a buffer for PEM information and store the resulting data into the specified context buffers.

Note

Attempts to check password correctness by verifying if the decrypted text starts with an ASN.1 sequence of appropriate length

Note

mbedtls_pem_free must be called on PEM context before the PEM context can be reused in another call to mbedtls_pem_read_buffer

Parameters

  • ctx – context to use

  • header – header string to seek and expect

  • footer – footer string to seek and expect

  • data – source data to look in (must be nul-terminated)

  • pwd – password for decryption (can be NULL)

  • pwdlen – length of password

  • use_len – destination for total length used from data buffer. It is set after header is correctly read, so unless you get MBEDTLS_ERR_PEM_BAD_INPUT_DATA or MBEDTLS_ERR_PEM_NO_HEADER_FOOTER_PRESENT, use_len is the length to skip.

Returns

0 on success, or a specific PEM error code

static inline const unsigned char *mbedtls_pem_get_buffer(mbedtls_pem_context *ctx, size_t *buflen)

Get the pointer to the decoded binary data in a PEM context.

Note

The returned pointer remains valid only until ctx is modified or freed.

Parameters

  • ctx – PEM context to access.

  • buflen – On success, this will contain the length of the binary data. This must be a valid (non-null) pointer.

Returns

A pointer to the decoded binary data.

void mbedtls_pem_free(mbedtls_pem_context *ctx)

PEM context memory freeing.

Parameters

ctx – context to be freed

int mbedtls_pem_write_buffer(const char *header, const char *footer, const unsigned char *der_data, size_t der_len, unsigned char *buf, size_t buf_len, size_t *olen)

Write a buffer of PEM information from a DER encoded buffer.

Note

You may pass NULL for buf and 0 for buf_len to request the length of the resulting PEM buffer in *olen.

Note

This function may be called with overlapping der_data and buf buffers.

Parameters

  • header – The header string to write.

  • footer – The footer string to write.

  • der_data – The DER data to encode.

  • der_len – The length of the DER data der_data in Bytes.

  • buf – The buffer to write to.

  • buf_len – The length of the output buffer buf in Bytes.

  • olen – The address at which to store the total length written or required (if buf_len is not enough).

Returns

0 on success.

Returns

MBEDTLS_ERR_BASE64_BUFFER_TOO_SMALL if buf isn’t large enough to hold the PEM buffer. In this case, *olen holds the required minimum size of buf.

Returns

Another PEM or BASE64 error code on other kinds of failure.

struct mbedtls_pem_context
#include <pem.h>

PEM context structure.

Public Members

unsigned char *private_buf

buffer for decoded data

size_t private_buflen

length of the buffer

unsigned char *private_info

buffer for extra header information