common/mbedtls/x509_crl.h

   1 /**
   2  * \file x509_crl.h
   3  *
   4  * \brief X.509 certificate revocation list parsing
   5  */
   6 /*
   7  *  Copyright The Mbed TLS Contributors
   8  *  SPDX-License-Identifier: Apache-2.0
   9  *
  10  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
  11  *  not use this file except in compliance with the License.
  12  *  You may obtain a copy of the License at
  13  *
  14  *  http://www.apache.org/licenses/LICENSE-2.0
  15  *
  16  *  Unless required by applicable law or agreed to in writing, software
  17  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  18  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  *  See the License for the specific language governing permissions and
  20  *  limitations under the License.
  21  */
  22 #ifndef MBEDTLS_X509_CRL_H
  23 #define MBEDTLS_X509_CRL_H
  24
  25 #if !defined(MBEDTLS_CONFIG_FILE)
  26 #include "mbedtls/config.h"
  27 #else
  28 #include MBEDTLS_CONFIG_FILE
  29 #endif
  30
  31 #include "mbedtls/x509.h"
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 /**
  38  * \addtogroup x509_module
  39  * \{ */
  40
  41 /**
  42  * \name Structures and functions for parsing CRLs
  43  * \{
  44  */
  45
  46 /**
  47  * Certificate revocation list entry.
  48  * Contains the CA-specific serial numbers and revocation dates.
  49  */
  50 typedef struct mbedtls_x509_crl_entry {
  51     mbedtls_x509_buf raw;
  52
  53     mbedtls_x509_buf serial;
  54
  55     mbedtls_x509_time revocation_date;
  56
  57     mbedtls_x509_buf entry_ext;
  58
  59     struct mbedtls_x509_crl_entry *next;
  60 }
  61 mbedtls_x509_crl_entry;
  62
  63 /**
  64  * Certificate revocation list structure.
  65  * Every CRL may have multiple entries.
  66  */
  67 typedef struct mbedtls_x509_crl {
  68     mbedtls_x509_buf raw;           /**< The raw certificate data (DER). */
  69     mbedtls_x509_buf tbs;           /**< The raw certificate body (DER). The part that is To Be Signed. */
  70
  71     int version;            /**< CRL version (1=v1, 2=v2) */
  72     mbedtls_x509_buf sig_oid;       /**< CRL signature type identifier */
  73
  74     mbedtls_x509_buf issuer_raw;    /**< The raw issuer data (DER). */
  75
  76     mbedtls_x509_name issuer;       /**< The parsed issuer data (named information object). */
  77
  78     mbedtls_x509_time this_update;
  79     mbedtls_x509_time next_update;
  80
  81     mbedtls_x509_crl_entry entry;   /**< The CRL entries containing the certificate revocation times for this CA. */
  82
  83     mbedtls_x509_buf crl_ext;
  84
  85     mbedtls_x509_buf sig_oid2;
  86     mbedtls_x509_buf sig;
  87     mbedtls_md_type_t sig_md;           /**< Internal representation of the MD algorithm of the signature algorithm, e.g. MBEDTLS_MD_SHA256 */
  88     mbedtls_pk_type_t sig_pk;           /**< Internal representation of the Public Key algorithm of the signature algorithm, e.g. MBEDTLS_PK_RSA */
  89     void *sig_opts;             /**< Signature options to be passed to mbedtls_pk_verify_ext(), e.g. for RSASSA-PSS */
  90
  91     struct mbedtls_x509_crl *next;
  92 }
  93 mbedtls_x509_crl;
  94
  95 /**
  96  * \brief          Parse a DER-encoded CRL and append it to the chained list
  97  *
  98  * \param chain    points to the start of the chain
  99  * \param buf      buffer holding the CRL data in DER format
 100  * \param buflen   size of the buffer
 101  *                 (including the terminating null byte for PEM data)
 102  *
 103  * \return         0 if successful, or a specific X509 or PEM error code
 104  */
 105 int mbedtls_x509_crl_parse_der(mbedtls_x509_crl *chain,
 106                                const unsigned char *buf, size_t buflen);
 107 /**
 108  * \brief          Parse one or more CRLs and append them to the chained list
 109  *
 110  * \note           Multiple CRLs are accepted only if using PEM format
 111  *
 112  * \param chain    points to the start of the chain
 113  * \param buf      buffer holding the CRL data in PEM or DER format
 114  * \param buflen   size of the buffer
 115  *                 (including the terminating null byte for PEM data)
 116  *
 117  * \return         0 if successful, or a specific X509 or PEM error code
 118  */
 119 int mbedtls_x509_crl_parse(mbedtls_x509_crl *chain, const unsigned char *buf, size_t buflen);
 120
 121 #if defined(MBEDTLS_FS_IO)
 122 /**
 123  * \brief          Load one or more CRLs and append them to the chained list
 124  *
 125  * \note           Multiple CRLs are accepted only if using PEM format
 126  *
 127  * \param chain    points to the start of the chain
 128  * \param path     filename to read the CRLs from (in PEM or DER encoding)
 129  *
 130  * \return         0 if successful, or a specific X509 or PEM error code
 131  */
 132 int mbedtls_x509_crl_parse_file(mbedtls_x509_crl *chain, const char *path);
 133 #endif /* MBEDTLS_FS_IO */
 134
 135 /**
 136  * \brief          Returns an informational string about the CRL.
 137  *
 138  * \param buf      Buffer to write to
 139  * \param size     Maximum size of buffer
 140  * \param prefix   A line prefix
 141  * \param crl      The X509 CRL to represent
 142  *
 143  * \return         The length of the string written (not including the
 144  *                 terminated nul byte), or a negative error code.
 145  */
 146 int mbedtls_x509_crl_info(char *buf, size_t size, const char *prefix,
 147                           const mbedtls_x509_crl *crl);
 148
 149 /**
 150  * \brief          Initialize a CRL (chain)
 151  *
 152  * \param crl      CRL chain to initialize
 153  */
 154 void mbedtls_x509_crl_init(mbedtls_x509_crl *crl);
 155
 156 /**
 157  * \brief          Unallocate all CRL data
 158  *
 159  * \param crl      CRL chain to free
 160  */
 161 void mbedtls_x509_crl_free(mbedtls_x509_crl *crl);
 162
 163 /* \} name */
 164 /* \} addtogroup x509_module */
 165
 166 #ifdef __cplusplus
 167 }
 168 #endif
 169
 170 #endif /* mbedtls_x509_crl.h */