git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/mbedtls/include/mbedtls/pem.h

   1 /**\r
   2  * \file pem.h\r
   3  *\r
   4  * \brief Privacy Enhanced Mail (PEM) decoding\r
   5  */\r
   6 /*\r
   7  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved\r
   8  *  SPDX-License-Identifier: Apache-2.0\r
   9  *\r
  10  *  Licensed under the Apache License, Version 2.0 (the "License"); you may\r
  11  *  not use this file except in compliance with the License.\r
  12  *  You may obtain a copy of the License at\r
  13  *\r
  14  *  http://www.apache.org/licenses/LICENSE-2.0\r
  15  *\r
  16  *  Unless required by applicable law or agreed to in writing, software\r
  17  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT\r
  18  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  19  *  See the License for the specific language governing permissions and\r
  20  *  limitations under the License.\r
  21  *\r
  22  *  This file is part of mbed TLS (https://tls.mbed.org)\r
  23  */\r
  24 #ifndef MBEDTLS_PEM_H\r
  25 #define MBEDTLS_PEM_H\r
  26 \r
  27 #if !defined(MBEDTLS_CONFIG_FILE)\r
  28 #include "config.h"\r
  29 #else\r
  30 #include MBEDTLS_CONFIG_FILE\r
  31 #endif\r
  32 \r
  33 #include <stddef.h>\r
  34 \r
  35 /**\r
  36  * \name PEM Error codes\r
  37  * These error codes are returned in case of errors reading the\r
  38  * PEM data.\r
  39  * \{\r
  40  */\r
  41 #define MBEDTLS_ERR_PEM_NO_HEADER_FOOTER_PRESENT          -0x1080  /**< No PEM header or footer found. */\r
  42 #define MBEDTLS_ERR_PEM_INVALID_DATA                      -0x1100  /**< PEM string is not as expected. */\r
  43 #define MBEDTLS_ERR_PEM_ALLOC_FAILED                      -0x1180  /**< Failed to allocate memory. */\r
  44 #define MBEDTLS_ERR_PEM_INVALID_ENC_IV                    -0x1200  /**< RSA IV is not in hex-format. */\r
  45 #define MBEDTLS_ERR_PEM_UNKNOWN_ENC_ALG                   -0x1280  /**< Unsupported key encryption algorithm. */\r
  46 #define MBEDTLS_ERR_PEM_PASSWORD_REQUIRED                 -0x1300  /**< Private key password can't be empty. */\r
  47 #define MBEDTLS_ERR_PEM_PASSWORD_MISMATCH                 -0x1380  /**< Given private key password does not allow for correct decryption. */\r
  48 #define MBEDTLS_ERR_PEM_FEATURE_UNAVAILABLE               -0x1400  /**< Unavailable feature, e.g. hashing/encryption combination. */\r
  49 #define MBEDTLS_ERR_PEM_BAD_INPUT_DATA                    -0x1480  /**< Bad input parameters to function. */\r
  50 /* \} name */\r
  51 \r
  52 #ifdef __cplusplus\r
  53 extern "C" {\r
  54 #endif\r
  55 \r
  56 #if defined(MBEDTLS_PEM_PARSE_C)\r
  57 /**\r
  58  * \brief       PEM context structure\r
  59  */\r
  60 typedef struct mbedtls_pem_context\r
  61 {\r
  62     unsigned char *buf;     /*!< buffer for decoded data             */\r
  63     size_t buflen;          /*!< length of the buffer                */\r
  64     unsigned char *info;    /*!< buffer for extra header information */\r
  65 }\r
  66 mbedtls_pem_context;\r
  67 \r
  68 /**\r
  69  * \brief       PEM context setup\r
  70  *\r
  71  * \param ctx   context to be initialized\r
  72  */\r
  73 void mbedtls_pem_init( mbedtls_pem_context *ctx );\r
  74 \r
  75 /**\r
  76  * \brief       Read a buffer for PEM information and store the resulting\r
  77  *              data into the specified context buffers.\r
  78  *\r
  79  * \param ctx       context to use\r
  80  * \param header    header string to seek and expect\r
  81  * \param footer    footer string to seek and expect\r
  82  * \param data      source data to look in (must be nul-terminated)\r
  83  * \param pwd       password for decryption (can be NULL)\r
  84  * \param pwdlen    length of password\r
  85  * \param use_len   destination for total length used (set after header is\r
  86  *                  correctly read, so unless you get\r
  87  *                  MBEDTLS_ERR_PEM_BAD_INPUT_DATA or\r
  88  *                  MBEDTLS_ERR_PEM_NO_HEADER_FOOTER_PRESENT, use_len is\r
  89  *                  the length to skip)\r
  90  *\r
  91  * \note            Attempts to check password correctness by verifying if\r
  92  *                  the decrypted text starts with an ASN.1 sequence of\r
  93  *                  appropriate length\r
  94  *\r
  95  * \return          0 on success, or a specific PEM error code\r
  96  */\r
  97 int mbedtls_pem_read_buffer( mbedtls_pem_context *ctx, const char *header, const char *footer,\r
  98                      const unsigned char *data,\r
  99                      const unsigned char *pwd,\r
 100                      size_t pwdlen, size_t *use_len );\r
 101 \r
 102 /**\r
 103  * \brief       PEM context memory freeing\r
 104  *\r
 105  * \param ctx   context to be freed\r
 106  */\r
 107 void mbedtls_pem_free( mbedtls_pem_context *ctx );\r
 108 #endif /* MBEDTLS_PEM_PARSE_C */\r
 109 \r
 110 #if defined(MBEDTLS_PEM_WRITE_C)\r
 111 /**\r
 112  * \brief           Write a buffer of PEM information from a DER encoded\r
 113  *                  buffer.\r
 114  *\r
 115  * \param header    header string to write\r
 116  * \param footer    footer string to write\r
 117  * \param der_data  DER data to write\r
 118  * \param der_len   length of the DER data\r
 119  * \param buf       buffer to write to\r
 120  * \param buf_len   length of output buffer\r
 121  * \param olen      total length written / required (if buf_len is not enough)\r
 122  *\r
 123  * \return          0 on success, or a specific PEM or BASE64 error code. On\r
 124  *                  MBEDTLS_ERR_BASE64_BUFFER_TOO_SMALL olen is the required\r
 125  *                  size.\r
 126  */\r
 127 int mbedtls_pem_write_buffer( const char *header, const char *footer,\r
 128                       const unsigned char *der_data, size_t der_len,\r
 129                       unsigned char *buf, size_t buf_len, size_t *olen );\r
 130 #endif /* MBEDTLS_PEM_WRITE_C */\r
 131 \r
 132 #ifdef __cplusplus\r
 133 }\r
 134 #endif\r
 135 \r
 136 #endif /* pem.h */\r