Subversion Repositories Kolibri OS

Rev

Blame | Last modification | View Log | Download | RSS feed

  1. /**
  2.  * \file x509_crt.h
  3.  *
  4.  * \brief X.509 certificate parsing and writing
  5.  */
  6. /*
  7.  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  8.  *  SPDX-License-Identifier: GPL-2.0
  9.  *
  10.  *  This program is free software; you can redistribute it and/or modify
  11.  *  it under the terms of the GNU General Public License as published by
  12.  *  the Free Software Foundation; either version 2 of the License, or
  13.  *  (at your option) any later version.
  14.  *
  15.  *  This program is distributed in the hope that it will be useful,
  16.  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  17.  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18.  *  GNU General Public License for more details.
  19.  *
  20.  *  You should have received a copy of the GNU General Public License along
  21.  *  with this program; if not, write to the Free Software Foundation, Inc.,
  22.  *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  23.  *
  24.  *  This file is part of mbed TLS (https://tls.mbed.org)
  25.  */
  26. #ifndef MBEDTLS_X509_CRT_H
  27. #define MBEDTLS_X509_CRT_H
  28.  
  29. #if !defined(MBEDTLS_CONFIG_FILE)
  30. #include "config.h"
  31. #else
  32. #include MBEDTLS_CONFIG_FILE
  33. #endif
  34.  
  35. #include "x509.h"
  36. #include "x509_crl.h"
  37.  
  38. /**
  39.  * \addtogroup x509_module
  40.  * \{
  41.  */
  42.  
  43. #ifdef __cplusplus
  44. extern "C" {
  45. #endif
  46.  
  47. /**
  48.  * \name Structures and functions for parsing and writing X.509 certificates
  49.  * \{
  50.  */
  51.  
  52. /**
  53.  * Container for an X.509 certificate. The certificate may be chained.
  54.  */
  55. typedef struct mbedtls_x509_crt
  56. {
  57.     mbedtls_x509_buf raw;               /**< The raw certificate data (DER). */
  58.     mbedtls_x509_buf tbs;               /**< The raw certificate body (DER). The part that is To Be Signed. */
  59.  
  60.     int version;                /**< The X.509 version. (1=v1, 2=v2, 3=v3) */
  61.     mbedtls_x509_buf serial;            /**< Unique id for certificate issued by a specific CA. */
  62.     mbedtls_x509_buf sig_oid;           /**< Signature algorithm, e.g. sha1RSA */
  63.  
  64.     mbedtls_x509_buf issuer_raw;        /**< The raw issuer data (DER). Used for quick comparison. */
  65.     mbedtls_x509_buf subject_raw;       /**< The raw subject data (DER). Used for quick comparison. */
  66.  
  67.     mbedtls_x509_name issuer;           /**< The parsed issuer data (named information object). */
  68.     mbedtls_x509_name subject;          /**< The parsed subject data (named information object). */
  69.  
  70.     mbedtls_x509_time valid_from;       /**< Start time of certificate validity. */
  71.     mbedtls_x509_time valid_to;         /**< End time of certificate validity. */
  72.  
  73.     mbedtls_pk_context pk;              /**< Container for the public key context. */
  74.  
  75.     mbedtls_x509_buf issuer_id;         /**< Optional X.509 v2/v3 issuer unique identifier. */
  76.     mbedtls_x509_buf subject_id;        /**< Optional X.509 v2/v3 subject unique identifier. */
  77.     mbedtls_x509_buf v3_ext;            /**< Optional X.509 v3 extensions.  */
  78.     mbedtls_x509_sequence subject_alt_names;    /**< Optional list of Subject Alternative Names (Only dNSName supported). */
  79.  
  80.     int ext_types;              /**< Bit string containing detected and parsed extensions */
  81.     int ca_istrue;              /**< Optional Basic Constraint extension value: 1 if this certificate belongs to a CA, 0 otherwise. */
  82.     int max_pathlen;            /**< Optional Basic Constraint extension value: The maximum path length to the root certificate. Path length is 1 higher than RFC 5280 'meaning', so 1+ */
  83.  
  84.     unsigned int key_usage;     /**< Optional key usage extension value: See the values in x509.h */
  85.  
  86.     mbedtls_x509_sequence ext_key_usage; /**< Optional list of extended key usage OIDs. */
  87.  
  88.     unsigned char ns_cert_type; /**< Optional Netscape certificate type extension value: See the values in x509.h */
  89.  
  90.     mbedtls_x509_buf sig;               /**< Signature: hash of the tbs part signed with the private key. */
  91.     mbedtls_md_type_t sig_md;           /**< Internal representation of the MD algorithm of the signature algorithm, e.g. MBEDTLS_MD_SHA256 */
  92.     mbedtls_pk_type_t sig_pk;           /**< Internal representation of the Public Key algorithm of the signature algorithm, e.g. MBEDTLS_PK_RSA */
  93.     void *sig_opts;             /**< Signature options to be passed to mbedtls_pk_verify_ext(), e.g. for RSASSA-PSS */
  94.  
  95.     struct mbedtls_x509_crt *next;     /**< Next certificate in the CA-chain. */
  96. }
  97. mbedtls_x509_crt;
  98.  
  99. /**
  100.  * Build flag from an algorithm/curve identifier (pk, md, ecp)
  101.  * Since 0 is always XXX_NONE, ignore it.
  102.  */
  103. #define MBEDTLS_X509_ID_FLAG( id )   ( 1 << ( (id) - 1 ) )
  104.  
  105. /**
  106.  * Security profile for certificate verification.
  107.  *
  108.  * All lists are bitfields, built by ORing flags from MBEDTLS_X509_ID_FLAG().
  109.  */
  110. typedef struct mbedtls_x509_crt_profile
  111. {
  112.     uint32_t allowed_mds;       /**< MDs for signatures         */
  113.     uint32_t allowed_pks;       /**< PK algs for signatures     */
  114.     uint32_t allowed_curves;    /**< Elliptic curves for ECDSA  */
  115.     uint32_t rsa_min_bitlen;    /**< Minimum size for RSA keys  */
  116. }
  117. mbedtls_x509_crt_profile;
  118.  
  119. #define MBEDTLS_X509_CRT_VERSION_1              0
  120. #define MBEDTLS_X509_CRT_VERSION_2              1
  121. #define MBEDTLS_X509_CRT_VERSION_3              2
  122.  
  123. #define MBEDTLS_X509_RFC5280_MAX_SERIAL_LEN 32
  124. #define MBEDTLS_X509_RFC5280_UTC_TIME_LEN   15
  125.  
  126. #if !defined( MBEDTLS_X509_MAX_FILE_PATH_LEN )
  127. #define MBEDTLS_X509_MAX_FILE_PATH_LEN 512
  128. #endif
  129.  
  130. /**
  131.  * Container for writing a certificate (CRT)
  132.  */
  133. typedef struct mbedtls_x509write_cert
  134. {
  135.     int version;
  136.     mbedtls_mpi serial;
  137.     mbedtls_pk_context *subject_key;
  138.     mbedtls_pk_context *issuer_key;
  139.     mbedtls_asn1_named_data *subject;
  140.     mbedtls_asn1_named_data *issuer;
  141.     mbedtls_md_type_t md_alg;
  142.     char not_before[MBEDTLS_X509_RFC5280_UTC_TIME_LEN + 1];
  143.     char not_after[MBEDTLS_X509_RFC5280_UTC_TIME_LEN + 1];
  144.     mbedtls_asn1_named_data *extensions;
  145. }
  146. mbedtls_x509write_cert;
  147.  
  148. /**
  149.  * Item in a verification chain: cert and flags for it
  150.  */
  151. typedef struct {
  152.     mbedtls_x509_crt *crt;
  153.     uint32_t flags;
  154. } mbedtls_x509_crt_verify_chain_item;
  155.  
  156. /**
  157.  * Max size of verification chain: end-entity + intermediates + trusted root
  158.  */
  159. #define MBEDTLS_X509_MAX_VERIFY_CHAIN_SIZE  ( MBEDTLS_X509_MAX_INTERMEDIATE_CA + 2 )
  160.  
  161. /**
  162.  * Verification chain as built by \c mbedtls_crt_verify_chain()
  163.  */
  164. typedef struct
  165. {
  166.     mbedtls_x509_crt_verify_chain_item items[MBEDTLS_X509_MAX_VERIFY_CHAIN_SIZE];
  167.     unsigned len;
  168. } mbedtls_x509_crt_verify_chain;
  169.  
  170. #if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
  171.  
  172. /**
  173.  * \brief       Context for resuming X.509 verify operations
  174.  */
  175. typedef struct
  176. {
  177.     /* for check_signature() */
  178.     mbedtls_pk_restart_ctx pk;
  179.  
  180.     /* for find_parent_in() */
  181.     mbedtls_x509_crt *parent; /* non-null iff parent_in in progress */
  182.     mbedtls_x509_crt *fallback_parent;
  183.     int fallback_signature_is_good;
  184.  
  185.     /* for find_parent() */
  186.     int parent_is_trusted; /* -1 if find_parent is not in progress */
  187.  
  188.     /* for verify_chain() */
  189.     enum {
  190.         x509_crt_rs_none,
  191.         x509_crt_rs_find_parent,
  192.     } in_progress;  /* none if no operation is in progress */
  193.     int self_cnt;
  194.     mbedtls_x509_crt_verify_chain ver_chain;
  195.  
  196. } mbedtls_x509_crt_restart_ctx;
  197.  
  198. #else /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
  199.  
  200. /* Now we can declare functions that take a pointer to that */
  201. typedef void mbedtls_x509_crt_restart_ctx;
  202.  
  203. #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
  204.  
  205. #if defined(MBEDTLS_X509_CRT_PARSE_C)
  206. /**
  207.  * Default security profile. Should provide a good balance between security
  208.  * and compatibility with current deployments.
  209.  */
  210. extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_default;
  211.  
  212. /**
  213.  * Expected next default profile. Recommended for new deployments.
  214.  * Currently targets a 128-bit security level, except for RSA-2048.
  215.  */
  216. extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_next;
  217.  
  218. /**
  219.  * NSA Suite B profile.
  220.  */
  221. extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_suiteb;
  222.  
  223. /**
  224.  * \brief          Parse a single DER formatted certificate and add it
  225.  *                 to the chained list.
  226.  *
  227.  * \param chain    points to the start of the chain
  228.  * \param buf      buffer holding the certificate DER data
  229.  * \param buflen   size of the buffer
  230.  *
  231.  * \return         0 if successful, or a specific X509 or PEM error code
  232.  */
  233. int mbedtls_x509_crt_parse_der( mbedtls_x509_crt *chain, const unsigned char *buf,
  234.                         size_t buflen );
  235.  
  236. /**
  237.  * \brief          Parse one DER-encoded or one or more concatenated PEM-encoded
  238.  *                 certificates and add them to the chained list.
  239.  *
  240.  *                 For CRTs in PEM encoding, the function parses permissively:
  241.  *                 if at least one certificate can be parsed, the function
  242.  *                 returns the number of certificates for which parsing failed
  243.  *                 (hence \c 0 if all certificates were parsed successfully).
  244.  *                 If no certificate could be parsed, the function returns
  245.  *                 the first (negative) error encountered during parsing.
  246.  *
  247.  *                 PEM encoded certificates may be interleaved by other data
  248.  *                 such as human readable descriptions of their content, as
  249.  *                 long as the certificates are enclosed in the PEM specific
  250.  *                 '-----{BEGIN/END} CERTIFICATE-----' delimiters.
  251.  *
  252.  * \param chain    The chain to which to add the parsed certificates.
  253.  * \param buf      The buffer holding the certificate data in PEM or DER format.
  254.  *                 For certificates in PEM encoding, this may be a concatenation
  255.  *                 of multiple certificates; for DER encoding, the buffer must
  256.  *                 comprise exactly one certificate.
  257.  * \param buflen   The size of \p buf, including the terminating \c NULL byte
  258.  *                 in case of PEM encoded data.
  259.  *
  260.  * \return         \c 0 if all certificates were parsed successfully.
  261.  * \return         The (positive) number of certificates that couldn't
  262.  *                 be parsed if parsing was partly successful (see above).
  263.  * \return         A negative X509 or PEM error code otherwise.
  264.  *
  265.  */
  266. int mbedtls_x509_crt_parse( mbedtls_x509_crt *chain, const unsigned char *buf, size_t buflen );
  267.  
  268. #if defined(MBEDTLS_FS_IO)
  269. /**
  270.  * \brief          Load one or more certificates and add them
  271.  *                 to the chained list. Parses permissively. If some
  272.  *                 certificates can be parsed, the result is the number
  273.  *                 of failed certificates it encountered. If none complete
  274.  *                 correctly, the first error is returned.
  275.  *
  276.  * \param chain    points to the start of the chain
  277.  * \param path     filename to read the certificates from
  278.  *
  279.  * \return         0 if all certificates parsed successfully, a positive number
  280.  *                 if partly successful or a specific X509 or PEM error code
  281.  */
  282. int mbedtls_x509_crt_parse_file( mbedtls_x509_crt *chain, const char *path );
  283.  
  284. /**
  285.  * \brief          Load one or more certificate files from a path and add them
  286.  *                 to the chained list. Parses permissively. If some
  287.  *                 certificates can be parsed, the result is the number
  288.  *                 of failed certificates it encountered. If none complete
  289.  *                 correctly, the first error is returned.
  290.  *
  291.  * \param chain    points to the start of the chain
  292.  * \param path     directory / folder to read the certificate files from
  293.  *
  294.  * \return         0 if all certificates parsed successfully, a positive number
  295.  *                 if partly successful or a specific X509 or PEM error code
  296.  */
  297. int mbedtls_x509_crt_parse_path( mbedtls_x509_crt *chain, const char *path );
  298. #endif /* MBEDTLS_FS_IO */
  299.  
  300. /**
  301.  * \brief          Returns an informational string about the
  302.  *                 certificate.
  303.  *
  304.  * \param buf      Buffer to write to
  305.  * \param size     Maximum size of buffer
  306.  * \param prefix   A line prefix
  307.  * \param crt      The X509 certificate to represent
  308.  *
  309.  * \return         The length of the string written (not including the
  310.  *                 terminated nul byte), or a negative error code.
  311.  */
  312. int mbedtls_x509_crt_info( char *buf, size_t size, const char *prefix,
  313.                    const mbedtls_x509_crt *crt );
  314.  
  315. /**
  316.  * \brief          Returns an informational string about the
  317.  *                 verification status of a certificate.
  318.  *
  319.  * \param buf      Buffer to write to
  320.  * \param size     Maximum size of buffer
  321.  * \param prefix   A line prefix
  322.  * \param flags    Verification flags created by mbedtls_x509_crt_verify()
  323.  *
  324.  * \return         The length of the string written (not including the
  325.  *                 terminated nul byte), or a negative error code.
  326.  */
  327. int mbedtls_x509_crt_verify_info( char *buf, size_t size, const char *prefix,
  328.                           uint32_t flags );
  329.  
  330. /**
  331.  * \brief          Verify the certificate signature
  332.  *
  333.  *                 The verify callback is a user-supplied callback that
  334.  *                 can clear / modify / add flags for a certificate. If set,
  335.  *                 the verification callback is called for each
  336.  *                 certificate in the chain (from the trust-ca down to the
  337.  *                 presented crt). The parameters for the callback are:
  338.  *                 (void *parameter, mbedtls_x509_crt *crt, int certificate_depth,
  339.  *                 int *flags). With the flags representing current flags for
  340.  *                 that specific certificate and the certificate depth from
  341.  *                 the bottom (Peer cert depth = 0).
  342.  *
  343.  *                 All flags left after returning from the callback
  344.  *                 are also returned to the application. The function should
  345.  *                 return 0 for anything (including invalid certificates)
  346.  *                 other than fatal error, as a non-zero return code
  347.  *                 immediately aborts the verification process. For fatal
  348.  *                 errors, a specific error code should be used (different
  349.  *                 from MBEDTLS_ERR_X509_CERT_VERIFY_FAILED which should not
  350.  *                 be returned at this point), or MBEDTLS_ERR_X509_FATAL_ERROR
  351.  *                 can be used if no better code is available.
  352.  *
  353.  * \note           In case verification failed, the results can be displayed
  354.  *                 using \c mbedtls_x509_crt_verify_info()
  355.  *
  356.  * \note           Same as \c mbedtls_x509_crt_verify_with_profile() with the
  357.  *                 default security profile.
  358.  *
  359.  * \note           It is your responsibility to provide up-to-date CRLs for
  360.  *                 all trusted CAs. If no CRL is provided for the CA that was
  361.  *                 used to sign the certificate, CRL verification is skipped
  362.  *                 silently, that is *without* setting any flag.
  363.  *
  364.  * \note           The \c trust_ca list can contain two types of certificates:
  365.  *                 (1) those of trusted root CAs, so that certificates
  366.  *                 chaining up to those CAs will be trusted, and (2)
  367.  *                 self-signed end-entity certificates to be trusted (for
  368.  *                 specific peers you know) - in that case, the self-signed
  369.  *                 certificate doesn't need to have the CA bit set.
  370.  *
  371.  * \param crt      a certificate (chain) to be verified
  372.  * \param trust_ca the list of trusted CAs (see note above)
  373.  * \param ca_crl   the list of CRLs for trusted CAs (see note above)
  374.  * \param cn       expected Common Name (can be set to
  375.  *                 NULL if the CN must not be verified)
  376.  * \param flags    result of the verification
  377.  * \param f_vrfy   verification function
  378.  * \param p_vrfy   verification parameter
  379.  *
  380.  * \return         0 (and flags set to 0) if the chain was verified and valid,
  381.  *                 MBEDTLS_ERR_X509_CERT_VERIFY_FAILED if the chain was verified
  382.  *                 but found to be invalid, in which case *flags will have one
  383.  *                 or more MBEDTLS_X509_BADCERT_XXX or MBEDTLS_X509_BADCRL_XXX
  384.  *                 flags set, or another error (and flags set to 0xffffffff)
  385.  *                 in case of a fatal error encountered during the
  386.  *                 verification process.
  387.  */
  388. int mbedtls_x509_crt_verify( mbedtls_x509_crt *crt,
  389.                      mbedtls_x509_crt *trust_ca,
  390.                      mbedtls_x509_crl *ca_crl,
  391.                      const char *cn, uint32_t *flags,
  392.                      int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *),
  393.                      void *p_vrfy );
  394.  
  395. /**
  396.  * \brief          Verify the certificate signature according to profile
  397.  *
  398.  * \note           Same as \c mbedtls_x509_crt_verify(), but with explicit
  399.  *                 security profile.
  400.  *
  401.  * \note           The restrictions on keys (RSA minimum size, allowed curves
  402.  *                 for ECDSA) apply to all certificates: trusted root,
  403.  *                 intermediate CAs if any, and end entity certificate.
  404.  *
  405.  * \param crt      a certificate (chain) to be verified
  406.  * \param trust_ca the list of trusted CAs
  407.  * \param ca_crl   the list of CRLs for trusted CAs
  408.  * \param profile  security profile for verification
  409.  * \param cn       expected Common Name (can be set to
  410.  *                 NULL if the CN must not be verified)
  411.  * \param flags    result of the verification
  412.  * \param f_vrfy   verification function
  413.  * \param p_vrfy   verification parameter
  414.  *
  415.  * \return         0 if successful or MBEDTLS_ERR_X509_CERT_VERIFY_FAILED
  416.  *                 in which case *flags will have one or more
  417.  *                 MBEDTLS_X509_BADCERT_XXX or MBEDTLS_X509_BADCRL_XXX flags
  418.  *                 set,
  419.  *                 or another error in case of a fatal error encountered
  420.  *                 during the verification process.
  421.  */
  422. int mbedtls_x509_crt_verify_with_profile( mbedtls_x509_crt *crt,
  423.                      mbedtls_x509_crt *trust_ca,
  424.                      mbedtls_x509_crl *ca_crl,
  425.                      const mbedtls_x509_crt_profile *profile,
  426.                      const char *cn, uint32_t *flags,
  427.                      int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *),
  428.                      void *p_vrfy );
  429.  
  430. /**
  431.  * \brief          Restartable version of \c mbedtls_crt_verify_with_profile()
  432.  *
  433.  * \note           Performs the same job as \c mbedtls_crt_verify_with_profile()
  434.  *                 but can return early and restart according to the limit
  435.  *                 set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
  436.  *
  437.  * \param crt      a certificate (chain) to be verified
  438.  * \param trust_ca the list of trusted CAs
  439.  * \param ca_crl   the list of CRLs for trusted CAs
  440.  * \param profile  security profile for verification
  441.  * \param cn       expected Common Name (can be set to
  442.  *                 NULL if the CN must not be verified)
  443.  * \param flags    result of the verification
  444.  * \param f_vrfy   verification function
  445.  * \param p_vrfy   verification parameter
  446.  * \param rs_ctx   restart context (NULL to disable restart)
  447.  *
  448.  * \return         See \c mbedtls_crt_verify_with_profile(), or
  449.  * \return         #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
  450.  *                 operations was reached: see \c mbedtls_ecp_set_max_ops().
  451.  */
  452. int mbedtls_x509_crt_verify_restartable( mbedtls_x509_crt *crt,
  453.                      mbedtls_x509_crt *trust_ca,
  454.                      mbedtls_x509_crl *ca_crl,
  455.                      const mbedtls_x509_crt_profile *profile,
  456.                      const char *cn, uint32_t *flags,
  457.                      int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *),
  458.                      void *p_vrfy,
  459.                      mbedtls_x509_crt_restart_ctx *rs_ctx );
  460.  
  461. #if defined(MBEDTLS_X509_CHECK_KEY_USAGE)
  462. /**
  463.  * \brief          Check usage of certificate against keyUsage extension.
  464.  *
  465.  * \param crt      Leaf certificate used.
  466.  * \param usage    Intended usage(s) (eg MBEDTLS_X509_KU_KEY_ENCIPHERMENT
  467.  *                 before using the certificate to perform an RSA key
  468.  *                 exchange).
  469.  *
  470.  * \note           Except for decipherOnly and encipherOnly, a bit set in the
  471.  *                 usage argument means this bit MUST be set in the
  472.  *                 certificate. For decipherOnly and encipherOnly, it means
  473.  *                 that bit MAY be set.
  474.  *
  475.  * \return         0 is these uses of the certificate are allowed,
  476.  *                 MBEDTLS_ERR_X509_BAD_INPUT_DATA if the keyUsage extension
  477.  *                 is present but does not match the usage argument.
  478.  *
  479.  * \note           You should only call this function on leaf certificates, on
  480.  *                 (intermediate) CAs the keyUsage extension is automatically
  481.  *                 checked by \c mbedtls_x509_crt_verify().
  482.  */
  483. int mbedtls_x509_crt_check_key_usage( const mbedtls_x509_crt *crt,
  484.                                       unsigned int usage );
  485. #endif /* MBEDTLS_X509_CHECK_KEY_USAGE) */
  486.  
  487. #if defined(MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE)
  488. /**
  489.  * \brief           Check usage of certificate against extendedKeyUsage.
  490.  *
  491.  * \param crt       Leaf certificate used.
  492.  * \param usage_oid Intended usage (eg MBEDTLS_OID_SERVER_AUTH or
  493.  *                  MBEDTLS_OID_CLIENT_AUTH).
  494.  * \param usage_len Length of usage_oid (eg given by MBEDTLS_OID_SIZE()).
  495.  *
  496.  * \return          0 if this use of the certificate is allowed,
  497.  *                  MBEDTLS_ERR_X509_BAD_INPUT_DATA if not.
  498.  *
  499.  * \note            Usually only makes sense on leaf certificates.
  500.  */
  501. int mbedtls_x509_crt_check_extended_key_usage( const mbedtls_x509_crt *crt,
  502.                                                const char *usage_oid,
  503.                                                size_t usage_len );
  504. #endif /* MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE */
  505.  
  506. #if defined(MBEDTLS_X509_CRL_PARSE_C)
  507. /**
  508.  * \brief          Verify the certificate revocation status
  509.  *
  510.  * \param crt      a certificate to be verified
  511.  * \param crl      the CRL to verify against
  512.  *
  513.  * \return         1 if the certificate is revoked, 0 otherwise
  514.  *
  515.  */
  516. int mbedtls_x509_crt_is_revoked( const mbedtls_x509_crt *crt, const mbedtls_x509_crl *crl );
  517. #endif /* MBEDTLS_X509_CRL_PARSE_C */
  518.  
  519. /**
  520.  * \brief          Initialize a certificate (chain)
  521.  *
  522.  * \param crt      Certificate chain to initialize
  523.  */
  524. void mbedtls_x509_crt_init( mbedtls_x509_crt *crt );
  525.  
  526. /**
  527.  * \brief          Unallocate all certificate data
  528.  *
  529.  * \param crt      Certificate chain to free
  530.  */
  531. void mbedtls_x509_crt_free( mbedtls_x509_crt *crt );
  532.  
  533. #if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
  534. /**
  535.  * \brief           Initialize a restart context
  536.  */
  537. void mbedtls_x509_crt_restart_init( mbedtls_x509_crt_restart_ctx *ctx );
  538.  
  539. /**
  540.  * \brief           Free the components of a restart context
  541.  */
  542. void mbedtls_x509_crt_restart_free( mbedtls_x509_crt_restart_ctx *ctx );
  543. #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
  544. #endif /* MBEDTLS_X509_CRT_PARSE_C */
  545.  
  546. /* \} name */
  547. /* \} addtogroup x509_module */
  548.  
  549. #if defined(MBEDTLS_X509_CRT_WRITE_C)
  550. /**
  551.  * \brief           Initialize a CRT writing context
  552.  *
  553.  * \param ctx       CRT context to initialize
  554.  */
  555. void mbedtls_x509write_crt_init( mbedtls_x509write_cert *ctx );
  556.  
  557. /**
  558.  * \brief           Set the verion for a Certificate
  559.  *                  Default: MBEDTLS_X509_CRT_VERSION_3
  560.  *
  561.  * \param ctx       CRT context to use
  562.  * \param version   version to set (MBEDTLS_X509_CRT_VERSION_1, MBEDTLS_X509_CRT_VERSION_2 or
  563.  *                                  MBEDTLS_X509_CRT_VERSION_3)
  564.  */
  565. void mbedtls_x509write_crt_set_version( mbedtls_x509write_cert *ctx, int version );
  566.  
  567. /**
  568.  * \brief           Set the serial number for a Certificate.
  569.  *
  570.  * \param ctx       CRT context to use
  571.  * \param serial    serial number to set
  572.  *
  573.  * \return          0 if successful
  574.  */
  575. int mbedtls_x509write_crt_set_serial( mbedtls_x509write_cert *ctx, const mbedtls_mpi *serial );
  576.  
  577. /**
  578.  * \brief           Set the validity period for a Certificate
  579.  *                  Timestamps should be in string format for UTC timezone
  580.  *                  i.e. "YYYYMMDDhhmmss"
  581.  *                  e.g. "20131231235959" for December 31st 2013
  582.  *                       at 23:59:59
  583.  *
  584.  * \param ctx       CRT context to use
  585.  * \param not_before    not_before timestamp
  586.  * \param not_after     not_after timestamp
  587.  *
  588.  * \return          0 if timestamp was parsed successfully, or
  589.  *                  a specific error code
  590.  */
  591. int mbedtls_x509write_crt_set_validity( mbedtls_x509write_cert *ctx, const char *not_before,
  592.                                 const char *not_after );
  593.  
  594. /**
  595.  * \brief           Set the issuer name for a Certificate
  596.  *                  Issuer names should contain a comma-separated list
  597.  *                  of OID types and values:
  598.  *                  e.g. "C=UK,O=ARM,CN=mbed TLS CA"
  599.  *
  600.  * \param ctx           CRT context to use
  601.  * \param issuer_name   issuer name to set
  602.  *
  603.  * \return          0 if issuer name was parsed successfully, or
  604.  *                  a specific error code
  605.  */
  606. int mbedtls_x509write_crt_set_issuer_name( mbedtls_x509write_cert *ctx,
  607.                                    const char *issuer_name );
  608.  
  609. /**
  610.  * \brief           Set the subject name for a Certificate
  611.  *                  Subject names should contain a comma-separated list
  612.  *                  of OID types and values:
  613.  *                  e.g. "C=UK,O=ARM,CN=mbed TLS Server 1"
  614.  *
  615.  * \param ctx           CRT context to use
  616.  * \param subject_name  subject name to set
  617.  *
  618.  * \return          0 if subject name was parsed successfully, or
  619.  *                  a specific error code
  620.  */
  621. int mbedtls_x509write_crt_set_subject_name( mbedtls_x509write_cert *ctx,
  622.                                     const char *subject_name );
  623.  
  624. /**
  625.  * \brief           Set the subject public key for the certificate
  626.  *
  627.  * \param ctx       CRT context to use
  628.  * \param key       public key to include
  629.  */
  630. void mbedtls_x509write_crt_set_subject_key( mbedtls_x509write_cert *ctx, mbedtls_pk_context *key );
  631.  
  632. /**
  633.  * \brief           Set the issuer key used for signing the certificate
  634.  *
  635.  * \param ctx       CRT context to use
  636.  * \param key       private key to sign with
  637.  */
  638. void mbedtls_x509write_crt_set_issuer_key( mbedtls_x509write_cert *ctx, mbedtls_pk_context *key );
  639.  
  640. /**
  641.  * \brief           Set the MD algorithm to use for the signature
  642.  *                  (e.g. MBEDTLS_MD_SHA1)
  643.  *
  644.  * \param ctx       CRT context to use
  645.  * \param md_alg    MD algorithm to use
  646.  */
  647. void mbedtls_x509write_crt_set_md_alg( mbedtls_x509write_cert *ctx, mbedtls_md_type_t md_alg );
  648.  
  649. /**
  650.  * \brief           Generic function to add to or replace an extension in the
  651.  *                  CRT
  652.  *
  653.  * \param ctx       CRT context to use
  654.  * \param oid       OID of the extension
  655.  * \param oid_len   length of the OID
  656.  * \param critical  if the extension is critical (per the RFC's definition)
  657.  * \param val       value of the extension OCTET STRING
  658.  * \param val_len   length of the value data
  659.  *
  660.  * \return          0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
  661.  */
  662. int mbedtls_x509write_crt_set_extension( mbedtls_x509write_cert *ctx,
  663.                                  const char *oid, size_t oid_len,
  664.                                  int critical,
  665.                                  const unsigned char *val, size_t val_len );
  666.  
  667. /**
  668.  * \brief           Set the basicConstraints extension for a CRT
  669.  *
  670.  * \param ctx       CRT context to use
  671.  * \param is_ca     is this a CA certificate
  672.  * \param max_pathlen   maximum length of certificate chains below this
  673.  *                      certificate (only for CA certificates, -1 is
  674.  *                      inlimited)
  675.  *
  676.  * \return          0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
  677.  */
  678. int mbedtls_x509write_crt_set_basic_constraints( mbedtls_x509write_cert *ctx,
  679.                                          int is_ca, int max_pathlen );
  680.  
  681. #if defined(MBEDTLS_SHA1_C)
  682. /**
  683.  * \brief           Set the subjectKeyIdentifier extension for a CRT
  684.  *                  Requires that mbedtls_x509write_crt_set_subject_key() has been
  685.  *                  called before
  686.  *
  687.  * \param ctx       CRT context to use
  688.  *
  689.  * \return          0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
  690.  */
  691. int mbedtls_x509write_crt_set_subject_key_identifier( mbedtls_x509write_cert *ctx );
  692.  
  693. /**
  694.  * \brief           Set the authorityKeyIdentifier extension for a CRT
  695.  *                  Requires that mbedtls_x509write_crt_set_issuer_key() has been
  696.  *                  called before
  697.  *
  698.  * \param ctx       CRT context to use
  699.  *
  700.  * \return          0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
  701.  */
  702. int mbedtls_x509write_crt_set_authority_key_identifier( mbedtls_x509write_cert *ctx );
  703. #endif /* MBEDTLS_SHA1_C */
  704.  
  705. /**
  706.  * \brief           Set the Key Usage Extension flags
  707.  *                  (e.g. MBEDTLS_X509_KU_DIGITAL_SIGNATURE | MBEDTLS_X509_KU_KEY_CERT_SIGN)
  708.  *
  709.  * \param ctx       CRT context to use
  710.  * \param key_usage key usage flags to set
  711.  *
  712.  * \return          0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED
  713.  */
  714. int mbedtls_x509write_crt_set_key_usage( mbedtls_x509write_cert *ctx,
  715.                                          unsigned int key_usage );
  716.  
  717. /**
  718.  * \brief           Set the Netscape Cert Type flags
  719.  *                  (e.g. MBEDTLS_X509_NS_CERT_TYPE_SSL_CLIENT | MBEDTLS_X509_NS_CERT_TYPE_EMAIL)
  720.  *
  721.  * \param ctx           CRT context to use
  722.  * \param ns_cert_type  Netscape Cert Type flags to set
  723.  *
  724.  * \return          0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED
  725.  */
  726. int mbedtls_x509write_crt_set_ns_cert_type( mbedtls_x509write_cert *ctx,
  727.                                     unsigned char ns_cert_type );
  728.  
  729. /**
  730.  * \brief           Free the contents of a CRT write context
  731.  *
  732.  * \param ctx       CRT context to free
  733.  */
  734. void mbedtls_x509write_crt_free( mbedtls_x509write_cert *ctx );
  735.  
  736. /**
  737.  * \brief           Write a built up certificate to a X509 DER structure
  738.  *                  Note: data is written at the end of the buffer! Use the
  739.  *                        return value to determine where you should start
  740.  *                        using the buffer
  741.  *
  742.  * \param ctx       certificate to write away
  743.  * \param buf       buffer to write to
  744.  * \param size      size of the buffer
  745.  * \param f_rng     RNG function (for signature, see note)
  746.  * \param p_rng     RNG parameter
  747.  *
  748.  * \return          length of data written if successful, or a specific
  749.  *                  error code
  750.  *
  751.  * \note            f_rng may be NULL if RSA is used for signature and the
  752.  *                  signature is made offline (otherwise f_rng is desirable
  753.  *                  for countermeasures against timing attacks).
  754.  *                  ECDSA signatures always require a non-NULL f_rng.
  755.  */
  756. int mbedtls_x509write_crt_der( mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size,
  757.                        int (*f_rng)(void *, unsigned char *, size_t),
  758.                        void *p_rng );
  759.  
  760. #if defined(MBEDTLS_PEM_WRITE_C)
  761. /**
  762.  * \brief           Write a built up certificate to a X509 PEM string
  763.  *
  764.  * \param ctx       certificate to write away
  765.  * \param buf       buffer to write to
  766.  * \param size      size of the buffer
  767.  * \param f_rng     RNG function (for signature, see note)
  768.  * \param p_rng     RNG parameter
  769.  *
  770.  * \return          0 if successful, or a specific error code
  771.  *
  772.  * \note            f_rng may be NULL if RSA is used for signature and the
  773.  *                  signature is made offline (otherwise f_rng is desirable
  774.  *                  for countermeasures against timing attacks).
  775.  *                  ECDSA signatures always require a non-NULL f_rng.
  776.  */
  777. int mbedtls_x509write_crt_pem( mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size,
  778.                        int (*f_rng)(void *, unsigned char *, size_t),
  779.                        void *p_rng );
  780. #endif /* MBEDTLS_PEM_WRITE_C */
  781. #endif /* MBEDTLS_X509_CRT_WRITE_C */
  782.  
  783. #ifdef __cplusplus
  784. }
  785. #endif
  786.  
  787. #endif /* mbedtls_x509_crt.h */
  788.