mbedtls 2.26.0

common/mbedtls/pem.h

@@ -4,28 +4,30 @@
  * \brief Privacy Enhanced Mail (PEM) decoding
  */
 /*
- *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
- *  SPDX-License-Identifier: GPL-2.0
+ *  Copyright The Mbed TLS Contributors
+ *  SPDX-License-Identifier: Apache-2.0
  *
- *  This program is free software; you can redistribute it and/or modify
- *  it under the terms of the GNU General Public License as published by
- *  the Free Software Foundation; either version 2 of the License, or
- *  (at your option) any later version.
+ *  Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *  not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
  *
- *  This program is distributed in the hope that it will be useful,
- *  but WITHOUT ANY WARRANTY; without even the implied warranty of
- *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- *  GNU General Public License for more details.
+ *  http://www.apache.org/licenses/LICENSE-2.0
  *
- *  You should have received a copy of the GNU General Public License along
- *  with this program; if not, write to the Free Software Foundation, Inc.,
- *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
- *
- *  This file is part of mbed TLS (https://tls.mbed.org)
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
  */
 #ifndef MBEDTLS_PEM_H
 #define MBEDTLS_PEM_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "mbedtls/config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #include <stddef.h>
 
 /**
@@ -53,7 +55,8 @@ extern "C" {
 /**
  * \brief       PEM context structure
  */
-typedef struct mbedtls_pem_context {
+typedef struct mbedtls_pem_context
+{
     unsigned char *buf;     /*!< buffer for decoded data             */
     size_t buflen;          /*!< length of the buffer                */
     unsigned char *info;    /*!< buffer for extra header information */
@@ -65,7 +68,7 @@ mbedtls_pem_context;
  *
  * \param ctx   context to be initialized
  */
-void mbedtls_pem_init(mbedtls_pem_context *ctx);
+void mbedtls_pem_init( mbedtls_pem_context *ctx );
 
 /**
  * \brief       Read a buffer for PEM information and store the resulting
@@ -89,17 +92,17 @@ void mbedtls_pem_init(mbedtls_pem_context *ctx);
  *
  * \return          0 on success, or a specific PEM error code
  */
-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);
+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 );
 
 /**
  * \brief       PEM context memory freeing
  *
  * \param ctx   context to be freed
  */
-void mbedtls_pem_free(mbedtls_pem_context *ctx);
+void mbedtls_pem_free( mbedtls_pem_context *ctx );
 #endif /* MBEDTLS_PEM_PARSE_C */
 
 #if defined(MBEDTLS_PEM_WRITE_C)
@@ -107,21 +110,31 @@ 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,
-                             unsigned char *buf, size_t buf_len, size_t *olen);
+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 );
 #endif /* MBEDTLS_PEM_WRITE_C */
 
 #ifdef __cplusplus