blob: ffe6e473dadacc6d63631be145bd9bb0aad1a20d [file] [log] [blame]
Paul Bakker96743fc2011-02-12 14:30:57 +00001/**
2 * \file pem.h
3 *
4 * \brief Privacy Enhanced Mail (PEM) decoding
Darryl Greena40a1012018-01-05 15:33:17 +00005 */
6/*
Bence Szépkúti1e148272020-08-07 13:07:28 +02007 * Copyright The Mbed TLS Contributors
Dave Rodgman7ff79652023-11-03 12:04:52 +00008 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
Paul Bakker96743fc2011-02-12 14:30:57 +00009 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020010#ifndef MBEDTLS_PEM_H
11#define MBEDTLS_PEM_H
Paul Bakker96743fc2011-02-12 14:30:57 +000012
Andrzej Kurekc470b6b2019-01-31 08:20:20 -050013#if !defined(MBEDTLS_CONFIG_FILE)
Jaeden Ameroc49fbbf2019-07-04 20:01:14 +010014#include "mbedtls/config.h"
Andrzej Kurekc470b6b2019-01-31 08:20:20 -050015#else
16#include MBEDTLS_CONFIG_FILE
17#endif
18
Rich Evans00ab4702015-02-06 13:43:58 +000019#include <stddef.h>
Paul Bakker23986e52011-04-24 08:57:21 +000020
Paul Bakker96743fc2011-02-12 14:30:57 +000021/**
22 * \name PEM Error codes
23 * These error codes are returned in case of errors reading the
24 * PEM data.
25 * \{
26 */
Gilles Peskinea3974432021-07-26 18:48:10 +020027/** No PEM header or footer found. */
28#define MBEDTLS_ERR_PEM_NO_HEADER_FOOTER_PRESENT -0x1080
29/** PEM string is not as expected. */
30#define MBEDTLS_ERR_PEM_INVALID_DATA -0x1100
31/** Failed to allocate memory. */
32#define MBEDTLS_ERR_PEM_ALLOC_FAILED -0x1180
33/** RSA IV is not in hex-format. */
34#define MBEDTLS_ERR_PEM_INVALID_ENC_IV -0x1200
35/** Unsupported key encryption algorithm. */
36#define MBEDTLS_ERR_PEM_UNKNOWN_ENC_ALG -0x1280
37/** Private key password can't be empty. */
38#define MBEDTLS_ERR_PEM_PASSWORD_REQUIRED -0x1300
39/** Given private key password does not allow for correct decryption. */
40#define MBEDTLS_ERR_PEM_PASSWORD_MISMATCH -0x1380
41/** Unavailable feature, e.g. hashing/encryption combination. */
42#define MBEDTLS_ERR_PEM_FEATURE_UNAVAILABLE -0x1400
43/** Bad input parameters to function. */
44#define MBEDTLS_ERR_PEM_BAD_INPUT_DATA -0x1480
Andrzej Kurek73afe272022-01-24 10:31:06 -050045/** \} name PEM Error codes */
Paul Bakker96743fc2011-02-12 14:30:57 +000046
Paul Bakker407a0da2013-06-27 14:29:21 +020047#ifdef __cplusplus
48extern "C" {
49#endif
50
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020051#if defined(MBEDTLS_PEM_PARSE_C)
Paul Bakker96743fc2011-02-12 14:30:57 +000052/**
53 * \brief PEM context structure
54 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010055typedef struct mbedtls_pem_context {
Paul Bakker96743fc2011-02-12 14:30:57 +000056 unsigned char *buf; /*!< buffer for decoded data */
Paul Bakker23986e52011-04-24 08:57:21 +000057 size_t buflen; /*!< length of the buffer */
Paul Bakker96743fc2011-02-12 14:30:57 +000058 unsigned char *info; /*!< buffer for extra header information */
59}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020060mbedtls_pem_context;
Paul Bakker96743fc2011-02-12 14:30:57 +000061
Paul Bakker96743fc2011-02-12 14:30:57 +000062/**
63 * \brief PEM context setup
64 *
65 * \param ctx context to be initialized
66 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010067void mbedtls_pem_init(mbedtls_pem_context *ctx);
Paul Bakker96743fc2011-02-12 14:30:57 +000068
69/**
70 * \brief Read a buffer for PEM information and store the resulting
71 * data into the specified context buffers.
72 *
73 * \param ctx context to use
74 * \param header header string to seek and expect
75 * \param footer footer string to seek and expect
Manuel Pégourié-Gonnard43b37cb2015-05-12 11:20:10 +020076 * \param data source data to look in (must be nul-terminated)
Paul Bakker96743fc2011-02-12 14:30:57 +000077 * \param pwd password for decryption (can be NULL)
78 * \param pwdlen length of password
Paul Bakker00b28602013-06-24 13:02:41 +020079 * \param use_len destination for total length used (set after header is
80 * correctly read, so unless you get
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020081 * MBEDTLS_ERR_PEM_BAD_INPUT_DATA or
82 * MBEDTLS_ERR_PEM_NO_HEADER_FOOTER_PRESENT, use_len is
Paul Bakker00b28602013-06-24 13:02:41 +020083 * the length to skip)
Paul Bakker96743fc2011-02-12 14:30:57 +000084 *
Manuel Pégourié-Gonnard7d4e5b72013-07-09 16:35:23 +020085 * \note Attempts to check password correctness by verifying if
86 * the decrypted text starts with an ASN.1 sequence of
87 * appropriate length
Manuel Pégourié-Gonnardf8648d52013-07-03 21:01:35 +020088 *
Paul Bakker77e23fb2013-09-15 20:03:26 +020089 * \return 0 on success, or a specific PEM error code
Paul Bakker96743fc2011-02-12 14:30:57 +000090 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010091int mbedtls_pem_read_buffer(mbedtls_pem_context *ctx, const char *header, const char *footer,
92 const unsigned char *data,
93 const unsigned char *pwd,
94 size_t pwdlen, size_t *use_len);
Paul Bakker96743fc2011-02-12 14:30:57 +000095
96/**
Paul Bakkercff68422013-09-15 20:43:33 +020097 * \brief PEM context memory freeing
98 *
99 * \param ctx context to be freed
100 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100101void mbedtls_pem_free(mbedtls_pem_context *ctx);
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200102#endif /* MBEDTLS_PEM_PARSE_C */
Paul Bakkercff68422013-09-15 20:43:33 +0200103
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200104#if defined(MBEDTLS_PEM_WRITE_C)
Paul Bakkercff68422013-09-15 20:43:33 +0200105/**
Paul Bakker77e23fb2013-09-15 20:03:26 +0200106 * \brief Write a buffer of PEM information from a DER encoded
107 * buffer.
108 *
Hanno Becker4063ad22019-05-04 08:12:47 +0100109 * \param header The header string to write.
110 * \param footer The footer string to write.
111 * \param der_data The DER data to encode.
112 * \param der_len The length of the DER data \p der_data in Bytes.
113 * \param buf The buffer to write to.
114 * \param buf_len The length of the output buffer \p buf in Bytes.
115 * \param olen The address at which to store the total length written
116 * or required (if \p buf_len is not enough).
Paul Bakker77e23fb2013-09-15 20:03:26 +0200117 *
Hanno Becker4063ad22019-05-04 08:12:47 +0100118 * \note You may pass \c NULL for \p buf and \c 0 for \p buf_len
119 * to request the length of the resulting PEM buffer in
120 * `*olen`.
121 *
122 * \note This function may be called with overlapping \p der_data
123 * and \p buf buffers.
124 *
125 * \return \c 0 on success.
126 * \return #MBEDTLS_ERR_BASE64_BUFFER_TOO_SMALL if \p buf isn't large
127 * enough to hold the PEM buffer. In this case, `*olen` holds
128 * the required minimum size of \p buf.
129 * \return Another PEM or BASE64 error code on other kinds of failure.
Paul Bakker77e23fb2013-09-15 20:03:26 +0200130 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100131int mbedtls_pem_write_buffer(const char *header, const char *footer,
132 const unsigned char *der_data, size_t der_len,
133 unsigned char *buf, size_t buf_len, size_t *olen);
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200134#endif /* MBEDTLS_PEM_WRITE_C */
Paul Bakker96743fc2011-02-12 14:30:57 +0000135
136#ifdef __cplusplus
137}
138#endif
139
140#endif /* pem.h */