From cfc77d49bd7d6f5d3d11c8f6c10255e394af7f7a Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Sat, 4 May 2019 08:12:47 +0100 Subject: [PATCH] Improve documentation of mbedtls_pem_write_buffer() In particular, mention that it supports overlapping input and output buffers. --- include/mbedtls/pem.h | 30 ++++++++++++++++++++---------- 1 file changed, 20 insertions(+), 10 deletions(-) diff --git a/include/mbedtls/pem.h b/include/mbedtls/pem.h index 16b610141..1d4474110 100644 --- a/include/mbedtls/pem.h +++ b/include/mbedtls/pem.h @@ -139,17 +139,27 @@ void mbedtls_pem_free( mbedtls_pem_context *ctx ); * \brief Write a buffer of PEM information from a DER encoded * buffer. * - * \param header header string to write - * \param footer footer string to write - * \param der_data DER data to write - * \param der_len length of the DER data - * \param buf buffer to write to - * \param buf_len length of output buffer - * \param olen total length written / required (if buf_len is not enough) + * \param header The header string to write. + * \param footer The footer string to write. + * \param der_data The DER data to encode. + * \param der_len The length of the DER data \p der_data in Bytes. + * \param buf The buffer to write to. + * \param buf_len The length of the output buffer \p buf in Bytes. + * \param olen The address at which to store the total length written + * or required (if \p buf_len is not enough). * - * \return 0 on success, or a specific PEM or BASE64 error code. On - * MBEDTLS_ERR_BASE64_BUFFER_TOO_SMALL olen is the required - * size. + * \note You may pass \c NULL for \p buf and \c 0 for \p buf_len + * to request the length of the resulting PEM buffer in + * `*olen`. + * + * \note This function may be called with overlapping \p der_data + * and \p buf buffers. + * + * \return \c 0 on success. + * \return #MBEDTLS_ERR_BASE64_BUFFER_TOO_SMALL if \p buf isn't large + * enough to hold the PEM buffer. In this case, `*olen` holds + * the required minimum size of \p buf. + * \return Another PEM or BASE64 error code on other kinds of failure. */ int mbedtls_pem_write_buffer( const char *header, const char *footer, const unsigned char *der_data, size_t der_len,