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 OR GPL-2.0-or-later 9 */ 10 #ifndef MBEDTLS_X509_CRL_H 11 #define MBEDTLS_X509_CRL_H 12 #include "mbedtls/private_access.h" 13 14 #include "mbedtls/build_info.h" 15 16 #include "mbedtls/x509.h" 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 /** 23 * \addtogroup x509_module 24 * \{ */ 25 26 /** 27 * \name Structures and functions for parsing CRLs 28 * \{ 29 */ 30 31 /** 32 * Certificate revocation list entry. 33 * Contains the CA-specific serial numbers and revocation dates. 34 * 35 * Some fields of this structure are publicly readable. Do not modify 36 * them except via Mbed TLS library functions: the effect of modifying 37 * those fields or the data that those fields points to is unspecified. 38 */ 39 typedef struct mbedtls_x509_crl_entry { 40 /** Direct access to the whole entry inside the containing buffer. */ 41 mbedtls_x509_buf raw; 42 /** The serial number of the revoked certificate. */ 43 mbedtls_x509_buf serial; 44 /** The revocation date of this entry. */ 45 mbedtls_x509_time revocation_date; 46 /** Direct access to the list of CRL entry extensions 47 * (an ASN.1 constructed sequence). 48 * 49 * If there are no extensions, `entry_ext.len == 0` and 50 * `entry_ext.p == NULL`. */ 51 mbedtls_x509_buf entry_ext; 52 53 /** Next element in the linked list of entries. 54 * \p NULL indicates the end of the list. 55 * Do not modify this field directly. */ 56 struct mbedtls_x509_crl_entry *next; 57 } 58 mbedtls_x509_crl_entry; 59 60 /** 61 * Certificate revocation list structure. 62 * Every CRL may have multiple entries. 63 */ 64 typedef struct mbedtls_x509_crl { 65 mbedtls_x509_buf raw; /**< The raw certificate data (DER). */ 66 mbedtls_x509_buf tbs; /**< The raw certificate body (DER). The part that is To Be Signed. */ 67 68 int version; /**< CRL version (1=v1, 2=v2) */ 69 mbedtls_x509_buf sig_oid; /**< CRL signature type identifier */ 70 71 mbedtls_x509_buf issuer_raw; /**< The raw issuer data (DER). */ 72 73 mbedtls_x509_name issuer; /**< The parsed issuer data (named information object). */ 74 75 mbedtls_x509_time this_update; 76 mbedtls_x509_time next_update; 77 78 mbedtls_x509_crl_entry entry; /**< The CRL entries containing the certificate revocation times for this CA. */ 79 80 mbedtls_x509_buf crl_ext; 81 82 mbedtls_x509_buf MBEDTLS_PRIVATE(sig_oid2); 83 mbedtls_x509_buf MBEDTLS_PRIVATE(sig); 84 mbedtls_md_type_t MBEDTLS_PRIVATE(sig_md); /**< Internal representation of the MD algorithm of the signature algorithm, e.g. MBEDTLS_MD_SHA256 */ 85 mbedtls_pk_sigalg_t MBEDTLS_PRIVATE(sig_pk); /**< Internal representation of the Public Key algorithm of the signature algorithm, e.g. MBEDTLS_PK_RSA */ 86 87 /** Next element in the linked list of CRL. 88 * \p NULL indicates the end of the list. 89 * Do not modify this field directly. */ 90 struct mbedtls_x509_crl *next; 91 } 92 mbedtls_x509_crl; 93 94 /** 95 * \brief Parse a DER-encoded CRL and append it to the chained list 96 * 97 * \note The PSA crypto subsystem must have been initialized by 98 * calling psa_crypto_init() before calling this function. 99 * 100 * \param chain points to the start of the chain 101 * \param buf buffer holding the CRL data in DER format 102 * \param buflen size of the buffer 103 * (including the terminating null byte for PEM data) 104 * 105 * \return 0 if successful, or a specific X509 or PEM error code 106 */ 107 int mbedtls_x509_crl_parse_der(mbedtls_x509_crl *chain, 108 const unsigned char *buf, size_t buflen); 109 /** 110 * \brief Parse one or more CRLs and append them to the chained list 111 * 112 * \note Multiple CRLs are accepted only if using PEM format 113 * 114 * \note The PSA crypto subsystem must have been initialized by 115 * calling psa_crypto_init() before calling this function. 116 * 117 * \param chain points to the start of the chain 118 * \param buf buffer holding the CRL data in PEM or DER format 119 * \param buflen size of the buffer 120 * (including the terminating null byte for PEM data) 121 * 122 * \return 0 if successful, or a specific X509 or PEM error code 123 */ 124 int mbedtls_x509_crl_parse(mbedtls_x509_crl *chain, const unsigned char *buf, size_t buflen); 125 126 #if defined(MBEDTLS_FS_IO) 127 /** 128 * \brief Load one or more CRLs and append them to the chained list 129 * 130 * \note Multiple CRLs are accepted only if using PEM format 131 * 132 * \note The PSA crypto subsystem must have been initialized by 133 * calling psa_crypto_init() before calling this function. 134 * 135 * \param chain points to the start of the chain 136 * \param path filename to read the CRLs from (in PEM or DER encoding) 137 * 138 * \return 0 if successful, or a specific X509 or PEM error code 139 */ 140 int mbedtls_x509_crl_parse_file(mbedtls_x509_crl *chain, const char *path); 141 #endif /* MBEDTLS_FS_IO */ 142 143 #if !defined(MBEDTLS_X509_REMOVE_INFO) 144 /** 145 * \brief Returns an informational string about the CRL. 146 * 147 * \param buf Buffer to write to 148 * \param size Maximum size of buffer 149 * \param prefix A line prefix 150 * \param crl The X509 CRL to represent 151 * 152 * \return The length of the string written (not including the 153 * terminated nul byte), or a negative error code. 154 */ 155 int mbedtls_x509_crl_info(char *buf, size_t size, const char *prefix, 156 const mbedtls_x509_crl *crl); 157 #endif /* !MBEDTLS_X509_REMOVE_INFO */ 158 159 /** 160 * \brief Initialize a CRL (chain) 161 * 162 * \param crl CRL chain to initialize 163 */ 164 void mbedtls_x509_crl_init(mbedtls_x509_crl *crl); 165 166 /** 167 * \brief Unallocate all CRL data 168 * 169 * \param crl CRL chain to free 170 */ 171 void mbedtls_x509_crl_free(mbedtls_x509_crl *crl); 172 173 /** \} name Structures and functions for parsing CRLs */ 174 /** \} addtogroup x509_module */ 175 176 #ifdef __cplusplus 177 } 178 #endif 179 180 #endif /* mbedtls_x509_crl.h */ 181