include/mbedtls/x509_crl.h

0001 /**
0002  * \file x509_crl.h
0003  *
0004  * \brief X.509 certificate revocation list parsing
0005  */
0006 /*
0007  *  Copyright The Mbed TLS Contributors
0008  *  SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
0009  */
0010 #ifndef MBEDTLS_X509_CRL_H
0011 #define MBEDTLS_X509_CRL_H
0012 #include "mbedtls/private_access.h"
0013
0014 #include "mbedtls/build_info.h"
0015
0016 #include "mbedtls/x509.h"
0017
0018 #ifdef __cplusplus
0019 extern "C" {
0020 #endif
0021
0022 /**
0023  * \addtogroup x509_module
0024  * \{ */
0025
0026 /**
0027  * \name Structures and functions for parsing CRLs
0028  * \{
0029  */
0030
0031 /**
0032  * Certificate revocation list entry.
0033  * Contains the CA-specific serial numbers and revocation dates.
0034  *
0035  * Some fields of this structure are publicly readable. Do not modify
0036  * them except via Mbed TLS library functions: the effect of modifying
0037  * those fields or the data that those fields points to is unspecified.
0038  */
0039 typedef struct mbedtls_x509_crl_entry {
0040     /** Direct access to the whole entry inside the containing buffer. */
0041     mbedtls_x509_buf raw;
0042     /** The serial number of the revoked certificate. */
0043     mbedtls_x509_buf serial;
0044     /** The revocation date of this entry. */
0045     mbedtls_x509_time revocation_date;
0046     /** Direct access to the list of CRL entry extensions
0047      * (an ASN.1 constructed sequence).
0048      *
0049      * If there are no extensions, `entry_ext.len == 0` and
0050      * `entry_ext.p == NULL`. */
0051     mbedtls_x509_buf entry_ext;
0052
0053     /** Next element in the linked list of entries.
0054      * \p NULL indicates the end of the list.
0055      * Do not modify this field directly. */
0056     struct mbedtls_x509_crl_entry *next;
0057 }
0058 mbedtls_x509_crl_entry;
0059
0060 /**
0061  * Certificate revocation list structure.
0062  * Every CRL may have multiple entries.
0063  */
0064 typedef struct mbedtls_x509_crl {
0065     mbedtls_x509_buf raw;           /**< The raw certificate data (DER). */
0066     mbedtls_x509_buf tbs;           /**< The raw certificate body (DER). The part that is To Be Signed. */
0067
0068     int version;            /**< CRL version (1=v1, 2=v2) */
0069     mbedtls_x509_buf sig_oid;       /**< CRL signature type identifier */
0070
0071     mbedtls_x509_buf issuer_raw;    /**< The raw issuer data (DER). */
0072
0073     mbedtls_x509_name issuer;       /**< The parsed issuer data (named information object). */
0074
0075     mbedtls_x509_time this_update;
0076     mbedtls_x509_time next_update;
0077
0078     mbedtls_x509_crl_entry entry;   /**< The CRL entries containing the certificate revocation times for this CA. */
0079
0080     mbedtls_x509_buf crl_ext;
0081
0082     mbedtls_x509_buf MBEDTLS_PRIVATE(sig_oid2);
0083     mbedtls_x509_buf MBEDTLS_PRIVATE(sig);
0084     mbedtls_md_type_t MBEDTLS_PRIVATE(sig_md);           /**< Internal representation of the MD algorithm of the signature algorithm, e.g. MBEDTLS_MD_SHA256 */
0085     mbedtls_pk_type_t MBEDTLS_PRIVATE(sig_pk);           /**< Internal representation of the Public Key algorithm of the signature algorithm, e.g. MBEDTLS_PK_RSA */
0086     void *MBEDTLS_PRIVATE(sig_opts);             /**< Signature options to be passed to mbedtls_pk_verify_ext(), e.g. for RSASSA-PSS */
0087
0088     /** Next element in the linked list of CRL.
0089      * \p NULL indicates the end of the list.
0090      * Do not modify this field directly. */
0091     struct mbedtls_x509_crl *next;
0092 }
0093 mbedtls_x509_crl;
0094
0095 /**
0096  * \brief          Parse a DER-encoded CRL and append it to the chained list
0097  *
0098  * \note           If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
0099  *                 subsystem must have been initialized by calling
0100  *                 psa_crypto_init() before calling this function.
0101  *
0102  * \param chain    points to the start of the chain
0103  * \param buf      buffer holding the CRL data in DER format
0104  * \param buflen   size of the buffer
0105  *                 (including the terminating null byte for PEM data)
0106  *
0107  * \return         0 if successful, or a specific X509 or PEM error code
0108  */
0109 int mbedtls_x509_crl_parse_der(mbedtls_x509_crl *chain,
0110                                const unsigned char *buf, size_t buflen);
0111 /**
0112  * \brief          Parse one or more CRLs and append them to the chained list
0113  *
0114  * \note           Multiple CRLs are accepted only if using PEM format
0115  *
0116  * \note           If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
0117  *                 subsystem must have been initialized by calling
0118  *                 psa_crypto_init() before calling this function.
0119  *
0120  * \param chain    points to the start of the chain
0121  * \param buf      buffer holding the CRL data in PEM or DER format
0122  * \param buflen   size of the buffer
0123  *                 (including the terminating null byte for PEM data)
0124  *
0125  * \return         0 if successful, or a specific X509 or PEM error code
0126  */
0127 int mbedtls_x509_crl_parse(mbedtls_x509_crl *chain, const unsigned char *buf, size_t buflen);
0128
0129 #if defined(MBEDTLS_FS_IO)
0130 /**
0131  * \brief          Load one or more CRLs and append them to the chained list
0132  *
0133  * \note           Multiple CRLs are accepted only if using PEM format
0134  *
0135  * \note           If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
0136  *                 subsystem must have been initialized by calling
0137  *                 psa_crypto_init() before calling this function.
0138  *
0139  * \param chain    points to the start of the chain
0140  * \param path     filename to read the CRLs from (in PEM or DER encoding)
0141  *
0142  * \return         0 if successful, or a specific X509 or PEM error code
0143  */
0144 int mbedtls_x509_crl_parse_file(mbedtls_x509_crl *chain, const char *path);
0145 #endif /* MBEDTLS_FS_IO */
0146
0147 #if !defined(MBEDTLS_X509_REMOVE_INFO)
0148 /**
0149  * \brief          Returns an informational string about the CRL.
0150  *
0151  * \param buf      Buffer to write to
0152  * \param size     Maximum size of buffer
0153  * \param prefix   A line prefix
0154  * \param crl      The X509 CRL to represent
0155  *
0156  * \return         The length of the string written (not including the
0157  *                 terminated nul byte), or a negative error code.
0158  */
0159 int mbedtls_x509_crl_info(char *buf, size_t size, const char *prefix,
0160                           const mbedtls_x509_crl *crl);
0161 #endif /* !MBEDTLS_X509_REMOVE_INFO */
0162
0163 /**
0164  * \brief          Initialize a CRL (chain)
0165  *
0166  * \param crl      CRL chain to initialize
0167  */
0168 void mbedtls_x509_crl_init(mbedtls_x509_crl *crl);
0169
0170 /**
0171  * \brief          Unallocate all CRL data
0172  *
0173  * \param crl      CRL chain to free
0174  */
0175 void mbedtls_x509_crl_free(mbedtls_x509_crl *crl);
0176
0177 /** \} name Structures and functions for parsing CRLs */
0178 /** \} addtogroup x509_module */
0179
0180 #ifdef __cplusplus
0181 }
0182 #endif
0183
0184 #endif /* mbedtls_x509_crl.h */