Willie Solano / mbedtls-slave-prot-prod

mbed TLS Build

Dependents:   Slave-prot-prod

include/mbedtls/x509_crt.h@1:1a219dea6cb5, 2019-06-04 (annotated)

Committer:
williequesada
Date:
Tue Jun 04 16:03:38 2019 +0000
Revision:
1:1a219dea6cb5
Parent:
0:cdf462088d13 
compartir a Pablo

Who changed what in which revision?

UserRevisionLine numberNew contents of line
markrad 0:cdf462088d13 1 /**
markrad 0:cdf462088d13 2 * \file x509_crt.h
markrad 0:cdf462088d13 3 *
markrad 0:cdf462088d13 4 * \brief X.509 certificate parsing and writing
markrad 0:cdf462088d13 5 *
markrad 0:cdf462088d13 6 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
markrad 0:cdf462088d13 7 * SPDX-License-Identifier: Apache-2.0
markrad 0:cdf462088d13 8 *
markrad 0:cdf462088d13 9 * Licensed under the Apache License, Version 2.0 (the "License"); you may
markrad 0:cdf462088d13 10 * not use this file except in compliance with the License.
markrad 0:cdf462088d13 11 * You may obtain a copy of the License at
markrad 0:cdf462088d13 12 *
markrad 0:cdf462088d13 13 * http://www.apache.org/licenses/LICENSE-2.0
markrad 0:cdf462088d13 14 *
markrad 0:cdf462088d13 15 * Unless required by applicable law or agreed to in writing, software
markrad 0:cdf462088d13 16 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
markrad 0:cdf462088d13 17 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
markrad 0:cdf462088d13 18 * See the License for the specific language governing permissions and
markrad 0:cdf462088d13 19 * limitations under the License.
markrad 0:cdf462088d13 20 *
markrad 0:cdf462088d13 21 * This file is part of mbed TLS (https://tls.mbed.org)
markrad 0:cdf462088d13 22 */
markrad 0:cdf462088d13 23 #ifndef MBEDTLS_X509_CRT_H
markrad 0:cdf462088d13 24 #define MBEDTLS_X509_CRT_H
markrad 0:cdf462088d13 25
markrad 0:cdf462088d13 26 #if !defined(MBEDTLS_CONFIG_FILE)
markrad 0:cdf462088d13 27 #include "config.h"
markrad 0:cdf462088d13 28 #else
markrad 0:cdf462088d13 29 #include MBEDTLS_CONFIG_FILE
markrad 0:cdf462088d13 30 #endif
markrad 0:cdf462088d13 31
markrad 0:cdf462088d13 32 #include "x509.h"
markrad 0:cdf462088d13 33 #include "x509_crl.h"
markrad 0:cdf462088d13 34
markrad 0:cdf462088d13 35 /**
markrad 0:cdf462088d13 36 * \addtogroup x509_module
markrad 0:cdf462088d13 37 * \{
markrad 0:cdf462088d13 38 */
markrad 0:cdf462088d13 39
markrad 0:cdf462088d13 40 #ifdef __cplusplus
markrad 0:cdf462088d13 41 extern "C" {
markrad 0:cdf462088d13 42 #endif
markrad 0:cdf462088d13 43
markrad 0:cdf462088d13 44 /**
markrad 0:cdf462088d13 45 * \name Structures and functions for parsing and writing X.509 certificates
markrad 0:cdf462088d13 46 * \{
markrad 0:cdf462088d13 47 */
markrad 0:cdf462088d13 48
markrad 0:cdf462088d13 49 /**
markrad 0:cdf462088d13 50 * Container for an X.509 certificate. The certificate may be chained.
markrad 0:cdf462088d13 51 */
markrad 0:cdf462088d13 52 typedef struct mbedtls_x509_crt
markrad 0:cdf462088d13 53 {
markrad 0:cdf462088d13 54 mbedtls_x509_buf raw; /**< The raw certificate data (DER). */
markrad 0:cdf462088d13 55 mbedtls_x509_buf tbs; /**< The raw certificate body (DER). The part that is To Be Signed. */
markrad 0:cdf462088d13 56
markrad 0:cdf462088d13 57 int version; /**< The X.509 version. (1=v1, 2=v2, 3=v3) */
markrad 0:cdf462088d13 58 mbedtls_x509_buf serial; /**< Unique id for certificate issued by a specific CA. */
markrad 0:cdf462088d13 59 mbedtls_x509_buf sig_oid; /**< Signature algorithm, e.g. sha1RSA */
markrad 0:cdf462088d13 60
markrad 0:cdf462088d13 61 mbedtls_x509_buf issuer_raw; /**< The raw issuer data (DER). Used for quick comparison. */
markrad 0:cdf462088d13 62 mbedtls_x509_buf subject_raw; /**< The raw subject data (DER). Used for quick comparison. */
markrad 0:cdf462088d13 63
markrad 0:cdf462088d13 64 mbedtls_x509_name issuer; /**< The parsed issuer data (named information object). */
markrad 0:cdf462088d13 65 mbedtls_x509_name subject; /**< The parsed subject data (named information object). */
markrad 0:cdf462088d13 66
markrad 0:cdf462088d13 67 mbedtls_x509_time valid_from; /**< Start time of certificate validity. */
markrad 0:cdf462088d13 68 mbedtls_x509_time valid_to; /**< End time of certificate validity. */
markrad 0:cdf462088d13 69
markrad 0:cdf462088d13 70 mbedtls_pk_context pk; /**< Container for the public key context. */
markrad 0:cdf462088d13 71
markrad 0:cdf462088d13 72 mbedtls_x509_buf issuer_id; /**< Optional X.509 v2/v3 issuer unique identifier. */
markrad 0:cdf462088d13 73 mbedtls_x509_buf subject_id; /**< Optional X.509 v2/v3 subject unique identifier. */
markrad 0:cdf462088d13 74 mbedtls_x509_buf v3_ext; /**< Optional X.509 v3 extensions. */
markrad 0:cdf462088d13 75 mbedtls_x509_sequence subject_alt_names; /**< Optional list of Subject Alternative Names (Only dNSName supported). */
markrad 0:cdf462088d13 76
markrad 0:cdf462088d13 77 int ext_types; /**< Bit string containing detected and parsed extensions */
markrad 0:cdf462088d13 78 int ca_istrue; /**< Optional Basic Constraint extension value: 1 if this certificate belongs to a CA, 0 otherwise. */
markrad 0:cdf462088d13 79 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+ */
markrad 0:cdf462088d13 80
markrad 0:cdf462088d13 81 unsigned int key_usage; /**< Optional key usage extension value: See the values in x509.h */
markrad 0:cdf462088d13 82
markrad 0:cdf462088d13 83 mbedtls_x509_sequence ext_key_usage; /**< Optional list of extended key usage OIDs. */
markrad 0:cdf462088d13 84
markrad 0:cdf462088d13 85 unsigned char ns_cert_type; /**< Optional Netscape certificate type extension value: See the values in x509.h */
markrad 0:cdf462088d13 86
markrad 0:cdf462088d13 87 mbedtls_x509_buf sig; /**< Signature: hash of the tbs part signed with the private key. */
markrad 0:cdf462088d13 88 mbedtls_md_type_t sig_md; /**< Internal representation of the MD algorithm of the signature algorithm, e.g. MBEDTLS_MD_SHA256 */
markrad 0:cdf462088d13 89 mbedtls_pk_type_t sig_pk; /**< Internal representation of the Public Key algorithm of the signature algorithm, e.g. MBEDTLS_PK_RSA */
markrad 0:cdf462088d13 90 void *sig_opts; /**< Signature options to be passed to mbedtls_pk_verify_ext(), e.g. for RSASSA-PSS */
markrad 0:cdf462088d13 91
markrad 0:cdf462088d13 92 struct mbedtls_x509_crt *next; /**< Next certificate in the CA-chain. */
markrad 0:cdf462088d13 93 }
markrad 0:cdf462088d13 94 mbedtls_x509_crt;
markrad 0:cdf462088d13 95
markrad 0:cdf462088d13 96 /**
markrad 0:cdf462088d13 97 * Build flag from an algorithm/curve identifier (pk, md, ecp)
markrad 0:cdf462088d13 98 * Since 0 is always XXX_NONE, ignore it.
markrad 0:cdf462088d13 99 */
markrad 0:cdf462088d13 100 #define MBEDTLS_X509_ID_FLAG( id ) ( 1 << ( id - 1 ) )
markrad 0:cdf462088d13 101
markrad 0:cdf462088d13 102 /**
markrad 0:cdf462088d13 103 * Security profile for certificate verification.
markrad 0:cdf462088d13 104 *
markrad 0:cdf462088d13 105 * All lists are bitfields, built by ORing flags from MBEDTLS_X509_ID_FLAG().
markrad 0:cdf462088d13 106 */
markrad 0:cdf462088d13 107 typedef struct
markrad 0:cdf462088d13 108 {
markrad 0:cdf462088d13 109 uint32_t allowed_mds; /**< MDs for signatures */
markrad 0:cdf462088d13 110 uint32_t allowed_pks; /**< PK algs for signatures */
markrad 0:cdf462088d13 111 uint32_t allowed_curves; /**< Elliptic curves for ECDSA */
markrad 0:cdf462088d13 112 uint32_t rsa_min_bitlen; /**< Minimum size for RSA keys */
markrad 0:cdf462088d13 113 }
markrad 0:cdf462088d13 114 mbedtls_x509_crt_profile;
markrad 0:cdf462088d13 115
markrad 0:cdf462088d13 116 #define MBEDTLS_X509_CRT_VERSION_1 0
markrad 0:cdf462088d13 117 #define MBEDTLS_X509_CRT_VERSION_2 1
markrad 0:cdf462088d13 118 #define MBEDTLS_X509_CRT_VERSION_3 2
markrad 0:cdf462088d13 119
markrad 0:cdf462088d13 120 #define MBEDTLS_X509_RFC5280_MAX_SERIAL_LEN 32
markrad 0:cdf462088d13 121 #define MBEDTLS_X509_RFC5280_UTC_TIME_LEN 15
markrad 0:cdf462088d13 122
markrad 0:cdf462088d13 123 #if !defined( MBEDTLS_X509_MAX_FILE_PATH_LEN )
markrad 0:cdf462088d13 124 #define MBEDTLS_X509_MAX_FILE_PATH_LEN 512
markrad 0:cdf462088d13 125 #endif
markrad 0:cdf462088d13 126
markrad 0:cdf462088d13 127 /**
markrad 0:cdf462088d13 128 * Container for writing a certificate (CRT)
markrad 0:cdf462088d13 129 */
markrad 0:cdf462088d13 130 typedef struct mbedtls_x509write_cert
markrad 0:cdf462088d13 131 {
markrad 0:cdf462088d13 132 int version;
markrad 0:cdf462088d13 133 mbedtls_mpi serial;
markrad 0:cdf462088d13 134 mbedtls_pk_context *subject_key;
markrad 0:cdf462088d13 135 mbedtls_pk_context *issuer_key;
markrad 0:cdf462088d13 136 mbedtls_asn1_named_data *subject;
markrad 0:cdf462088d13 137 mbedtls_asn1_named_data *issuer;
markrad 0:cdf462088d13 138 mbedtls_md_type_t md_alg;
markrad 0:cdf462088d13 139 char not_before[MBEDTLS_X509_RFC5280_UTC_TIME_LEN + 1];
markrad 0:cdf462088d13 140 char not_after[MBEDTLS_X509_RFC5280_UTC_TIME_LEN + 1];
markrad 0:cdf462088d13 141 mbedtls_asn1_named_data *extensions;
markrad 0:cdf462088d13 142 }
markrad 0:cdf462088d13 143 mbedtls_x509write_cert;
markrad 0:cdf462088d13 144
markrad 0:cdf462088d13 145 #if defined(MBEDTLS_X509_CRT_PARSE_C)
markrad 0:cdf462088d13 146 /**
markrad 0:cdf462088d13 147 * Default security profile. Should provide a good balance between security
markrad 0:cdf462088d13 148 * and compatibility with current deployments.
markrad 0:cdf462088d13 149 */
markrad 0:cdf462088d13 150 extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_default;
markrad 0:cdf462088d13 151
markrad 0:cdf462088d13 152 /**
markrad 0:cdf462088d13 153 * Expected next default profile. Recommended for new deployments.
markrad 0:cdf462088d13 154 * Currently targets a 128-bit security level, except for RSA-2048.
markrad 0:cdf462088d13 155 */
markrad 0:cdf462088d13 156 extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_next;
markrad 0:cdf462088d13 157
markrad 0:cdf462088d13 158 /**
markrad 0:cdf462088d13 159 * NSA Suite B profile.
markrad 0:cdf462088d13 160 */
markrad 0:cdf462088d13 161 extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_suiteb;
markrad 0:cdf462088d13 162
markrad 0:cdf462088d13 163 /**
markrad 0:cdf462088d13 164 * \brief Parse a single DER formatted certificate and add it
markrad 0:cdf462088d13 165 * to the chained list.
markrad 0:cdf462088d13 166 *
markrad 0:cdf462088d13 167 * \param chain points to the start of the chain
markrad 0:cdf462088d13 168 * \param buf buffer holding the certificate DER data
markrad 0:cdf462088d13 169 * \param buflen size of the buffer
markrad 0:cdf462088d13 170 *
markrad 0:cdf462088d13 171 * \return 0 if successful, or a specific X509 or PEM error code
markrad 0:cdf462088d13 172 */
markrad 0:cdf462088d13 173 int mbedtls_x509_crt_parse_der( mbedtls_x509_crt *chain, const unsigned char *buf,
markrad 0:cdf462088d13 174 size_t buflen );
markrad 0:cdf462088d13 175
markrad 0:cdf462088d13 176 /**
markrad 0:cdf462088d13 177 * \brief Parse one or more certificates and add them
markrad 0:cdf462088d13 178 * to the chained list. Parses permissively. If some
markrad 0:cdf462088d13 179 * certificates can be parsed, the result is the number
markrad 0:cdf462088d13 180 * of failed certificates it encountered. If none complete
markrad 0:cdf462088d13 181 * correctly, the first error is returned.
markrad 0:cdf462088d13 182 *
markrad 0:cdf462088d13 183 * \param chain points to the start of the chain
markrad 0:cdf462088d13 184 * \param buf buffer holding the certificate data in PEM or DER format
markrad 0:cdf462088d13 185 * \param buflen size of the buffer
markrad 0:cdf462088d13 186 * (including the terminating null byte for PEM data)
markrad 0:cdf462088d13 187 *
markrad 0:cdf462088d13 188 * \return 0 if all certificates parsed successfully, a positive number
markrad 0:cdf462088d13 189 * if partly successful or a specific X509 or PEM error code
markrad 0:cdf462088d13 190 */
markrad 0:cdf462088d13 191 int mbedtls_x509_crt_parse( mbedtls_x509_crt *chain, const unsigned char *buf, size_t buflen );
markrad 0:cdf462088d13 192
markrad 0:cdf462088d13 193 #if defined(MBEDTLS_FS_IO)
markrad 0:cdf462088d13 194 /**
markrad 0:cdf462088d13 195 * \brief Load one or more certificates and add them
markrad 0:cdf462088d13 196 * to the chained list. Parses permissively. If some
markrad 0:cdf462088d13 197 * certificates can be parsed, the result is the number
markrad 0:cdf462088d13 198 * of failed certificates it encountered. If none complete
markrad 0:cdf462088d13 199 * correctly, the first error is returned.
markrad 0:cdf462088d13 200 *
markrad 0:cdf462088d13 201 * \param chain points to the start of the chain
markrad 0:cdf462088d13 202 * \param path filename to read the certificates from
markrad 0:cdf462088d13 203 *
markrad 0:cdf462088d13 204 * \return 0 if all certificates parsed successfully, a positive number
markrad 0:cdf462088d13 205 * if partly successful or a specific X509 or PEM error code
markrad 0:cdf462088d13 206 */
markrad 0:cdf462088d13 207 int mbedtls_x509_crt_parse_file( mbedtls_x509_crt *chain, const char *path );
markrad 0:cdf462088d13 208
markrad 0:cdf462088d13 209 /**
markrad 0:cdf462088d13 210 * \brief Load one or more certificate files from a path and add them
markrad 0:cdf462088d13 211 * to the chained list. Parses permissively. If some
markrad 0:cdf462088d13 212 * certificates can be parsed, the result is the number
markrad 0:cdf462088d13 213 * of failed certificates it encountered. If none complete
markrad 0:cdf462088d13 214 * correctly, the first error is returned.
markrad 0:cdf462088d13 215 *
markrad 0:cdf462088d13 216 * \param chain points to the start of the chain
markrad 0:cdf462088d13 217 * \param path directory / folder to read the certificate files from
markrad 0:cdf462088d13 218 *
markrad 0:cdf462088d13 219 * \return 0 if all certificates parsed successfully, a positive number
markrad 0:cdf462088d13 220 * if partly successful or a specific X509 or PEM error code
markrad 0:cdf462088d13 221 */
markrad 0:cdf462088d13 222 int mbedtls_x509_crt_parse_path( mbedtls_x509_crt *chain, const char *path );
markrad 0:cdf462088d13 223 #endif /* MBEDTLS_FS_IO */
markrad 0:cdf462088d13 224
markrad 0:cdf462088d13 225 /**
markrad 0:cdf462088d13 226 * \brief Returns an informational string about the
markrad 0:cdf462088d13 227 * certificate.
markrad 0:cdf462088d13 228 *
markrad 0:cdf462088d13 229 * \param buf Buffer to write to
markrad 0:cdf462088d13 230 * \param size Maximum size of buffer
markrad 0:cdf462088d13 231 * \param prefix A line prefix
markrad 0:cdf462088d13 232 * \param crt The X509 certificate to represent
markrad 0:cdf462088d13 233 *
markrad 0:cdf462088d13 234 * \return The length of the string written (not including the
markrad 0:cdf462088d13 235 * terminated nul byte), or a negative error code.
markrad 0:cdf462088d13 236 */
markrad 0:cdf462088d13 237 int mbedtls_x509_crt_info( char *buf, size_t size, const char *prefix,
markrad 0:cdf462088d13 238 const mbedtls_x509_crt *crt );
markrad 0:cdf462088d13 239
markrad 0:cdf462088d13 240 /**
markrad 0:cdf462088d13 241 * \brief Returns an informational string about the
markrad 0:cdf462088d13 242 * verification status of a certificate.
markrad 0:cdf462088d13 243 *
markrad 0:cdf462088d13 244 * \param buf Buffer to write to
markrad 0:cdf462088d13 245 * \param size Maximum size of buffer
markrad 0:cdf462088d13 246 * \param prefix A line prefix
markrad 0:cdf462088d13 247 * \param flags Verification flags created by mbedtls_x509_crt_verify()
markrad 0:cdf462088d13 248 *
markrad 0:cdf462088d13 249 * \return The length of the string written (not including the
markrad 0:cdf462088d13 250 * terminated nul byte), or a negative error code.
markrad 0:cdf462088d13 251 */
markrad 0:cdf462088d13 252 int mbedtls_x509_crt_verify_info( char *buf, size_t size, const char *prefix,
markrad 0:cdf462088d13 253 uint32_t flags );
markrad 0:cdf462088d13 254
markrad 0:cdf462088d13 255 /**
markrad 0:cdf462088d13 256 * \brief Verify the certificate signature
markrad 0:cdf462088d13 257 *
markrad 0:cdf462088d13 258 * The verify callback is a user-supplied callback that
markrad 0:cdf462088d13 259 * can clear / modify / add flags for a certificate. If set,
markrad 0:cdf462088d13 260 * the verification callback is called for each
markrad 0:cdf462088d13 261 * certificate in the chain (from the trust-ca down to the
markrad 0:cdf462088d13 262 * presented crt). The parameters for the callback are:
markrad 0:cdf462088d13 263 * (void *parameter, mbedtls_x509_crt *crt, int certificate_depth,
markrad 0:cdf462088d13 264 * int *flags). With the flags representing current flags for
markrad 0:cdf462088d13 265 * that specific certificate and the certificate depth from
markrad 0:cdf462088d13 266 * the bottom (Peer cert depth = 0).
markrad 0:cdf462088d13 267 *
markrad 0:cdf462088d13 268 * All flags left after returning from the callback
markrad 0:cdf462088d13 269 * are also returned to the application. The function should
markrad 0:cdf462088d13 270 * return 0 for anything but a fatal error.
markrad 0:cdf462088d13 271 *
markrad 0:cdf462088d13 272 * \note In case verification failed, the results can be displayed
markrad 0:cdf462088d13 273 * using \c mbedtls_x509_crt_verify_info()
markrad 0:cdf462088d13 274 *
markrad 0:cdf462088d13 275 * \note Same as \c mbedtls_x509_crt_verify_with_profile() with the
markrad 0:cdf462088d13 276 * default security profile.
markrad 0:cdf462088d13 277 *
markrad 0:cdf462088d13 278 * \note It is your responsibility to provide up-to-date CRLs for
markrad 0:cdf462088d13 279 * all trusted CAs. If no CRL is provided for the CA that was
markrad 0:cdf462088d13 280 * used to sign the certificate, CRL verification is skipped
markrad 0:cdf462088d13 281 * silently, that is *without* setting any flag.
markrad 0:cdf462088d13 282 *
markrad 0:cdf462088d13 283 * \param crt a certificate (chain) to be verified
markrad 0:cdf462088d13 284 * \param trust_ca the list of trusted CAs
markrad 0:cdf462088d13 285 * \param ca_crl the list of CRLs for trusted CAs (see note above)
markrad 0:cdf462088d13 286 * \param cn expected Common Name (can be set to
markrad 0:cdf462088d13 287 * NULL if the CN must not be verified)
markrad 0:cdf462088d13 288 * \param flags result of the verification
markrad 0:cdf462088d13 289 * \param f_vrfy verification function
markrad 0:cdf462088d13 290 * \param p_vrfy verification parameter
markrad 0:cdf462088d13 291 *
markrad 0:cdf462088d13 292 * \return 0 if successful or MBEDTLS_ERR_X509_CERT_VERIFY_FAILED
markrad 0:cdf462088d13 293 * in which case *flags will have one or more
markrad 0:cdf462088d13 294 * MBEDTLS_X509_BADCERT_XXX or MBEDTLS_X509_BADCRL_XXX flags
markrad 0:cdf462088d13 295 * set,
markrad 0:cdf462088d13 296 * or another error in case of a fatal error encountered
markrad 0:cdf462088d13 297 * during the verification process.
markrad 0:cdf462088d13 298 */
markrad 0:cdf462088d13 299 int mbedtls_x509_crt_verify( mbedtls_x509_crt *crt,
markrad 0:cdf462088d13 300 mbedtls_x509_crt *trust_ca,
markrad 0:cdf462088d13 301 mbedtls_x509_crl *ca_crl,
markrad 0:cdf462088d13 302 const char *cn, uint32_t *flags,
markrad 0:cdf462088d13 303 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *),
markrad 0:cdf462088d13 304 void *p_vrfy );
markrad 0:cdf462088d13 305
markrad 0:cdf462088d13 306 /**
markrad 0:cdf462088d13 307 * \brief Verify the certificate signature according to profile
markrad 0:cdf462088d13 308 *
markrad 0:cdf462088d13 309 * \note Same as \c mbedtls_x509_crt_verify(), but with explicit
markrad 0:cdf462088d13 310 * security profile.
markrad 0:cdf462088d13 311 *
markrad 0:cdf462088d13 312 * \note The restrictions on keys (RSA minimum size, allowed curves
markrad 0:cdf462088d13 313 * for ECDSA) apply to all certificates: trusted root,
markrad 0:cdf462088d13 314 * intermediate CAs if any, and end entity certificate.
markrad 0:cdf462088d13 315 *
markrad 0:cdf462088d13 316 * \param crt a certificate (chain) to be verified
markrad 0:cdf462088d13 317 * \param trust_ca the list of trusted CAs
markrad 0:cdf462088d13 318 * \param ca_crl the list of CRLs for trusted CAs
markrad 0:cdf462088d13 319 * \param profile security profile for verification
markrad 0:cdf462088d13 320 * \param cn expected Common Name (can be set to
markrad 0:cdf462088d13 321 * NULL if the CN must not be verified)
markrad 0:cdf462088d13 322 * \param flags result of the verification
markrad 0:cdf462088d13 323 * \param f_vrfy verification function
markrad 0:cdf462088d13 324 * \param p_vrfy verification parameter
markrad 0:cdf462088d13 325 *
markrad 0:cdf462088d13 326 * \return 0 if successful or MBEDTLS_ERR_X509_CERT_VERIFY_FAILED
markrad 0:cdf462088d13 327 * in which case *flags will have one or more
markrad 0:cdf462088d13 328 * MBEDTLS_X509_BADCERT_XXX or MBEDTLS_X509_BADCRL_XXX flags
markrad 0:cdf462088d13 329 * set,
markrad 0:cdf462088d13 330 * or another error in case of a fatal error encountered
markrad 0:cdf462088d13 331 * during the verification process.
markrad 0:cdf462088d13 332 */
markrad 0:cdf462088d13 333 int mbedtls_x509_crt_verify_with_profile( mbedtls_x509_crt *crt,
markrad 0:cdf462088d13 334 mbedtls_x509_crt *trust_ca,
markrad 0:cdf462088d13 335 mbedtls_x509_crl *ca_crl,
markrad 0:cdf462088d13 336 const mbedtls_x509_crt_profile *profile,
markrad 0:cdf462088d13 337 const char *cn, uint32_t *flags,
markrad 0:cdf462088d13 338 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *),
markrad 0:cdf462088d13 339 void *p_vrfy );
markrad 0:cdf462088d13 340
markrad 0:cdf462088d13 341 #if defined(MBEDTLS_X509_CHECK_KEY_USAGE)
markrad 0:cdf462088d13 342 /**
markrad 0:cdf462088d13 343 * \brief Check usage of certificate against keyUsage extension.
markrad 0:cdf462088d13 344 *
markrad 0:cdf462088d13 345 * \param crt Leaf certificate used.
markrad 0:cdf462088d13 346 * \param usage Intended usage(s) (eg MBEDTLS_X509_KU_KEY_ENCIPHERMENT
markrad 0:cdf462088d13 347 * before using the certificate to perform an RSA key
markrad 0:cdf462088d13 348 * exchange).
markrad 0:cdf462088d13 349 *
markrad 0:cdf462088d13 350 * \note Except for decipherOnly and encipherOnly, a bit set in the
markrad 0:cdf462088d13 351 * usage argument means this bit MUST be set in the
markrad 0:cdf462088d13 352 * certificate. For decipherOnly and encipherOnly, it means
markrad 0:cdf462088d13 353 * that bit MAY be set.
markrad 0:cdf462088d13 354 *
markrad 0:cdf462088d13 355 * \return 0 is these uses of the certificate are allowed,
markrad 0:cdf462088d13 356 * MBEDTLS_ERR_X509_BAD_INPUT_DATA if the keyUsage extension
markrad 0:cdf462088d13 357 * is present but does not match the usage argument.
markrad 0:cdf462088d13 358 *
markrad 0:cdf462088d13 359 * \note You should only call this function on leaf certificates, on
markrad 0:cdf462088d13 360 * (intermediate) CAs the keyUsage extension is automatically
markrad 0:cdf462088d13 361 * checked by \c mbedtls_x509_crt_verify().
markrad 0:cdf462088d13 362 */
markrad 0:cdf462088d13 363 int mbedtls_x509_crt_check_key_usage( const mbedtls_x509_crt *crt,
markrad 0:cdf462088d13 364 unsigned int usage );
markrad 0:cdf462088d13 365 #endif /* MBEDTLS_X509_CHECK_KEY_USAGE) */
markrad 0:cdf462088d13 366
markrad 0:cdf462088d13 367 #if defined(MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE)
markrad 0:cdf462088d13 368 /**
markrad 0:cdf462088d13 369 * \brief Check usage of certificate against extentedJeyUsage.
markrad 0:cdf462088d13 370 *
markrad 0:cdf462088d13 371 * \param crt Leaf certificate used.
markrad 0:cdf462088d13 372 * \param usage_oid Intended usage (eg MBEDTLS_OID_SERVER_AUTH or MBEDTLS_OID_CLIENT_AUTH).
markrad 0:cdf462088d13 373 * \param usage_len Length of usage_oid (eg given by MBEDTLS_OID_SIZE()).
markrad 0:cdf462088d13 374 *
markrad 0:cdf462088d13 375 * \return 0 if this use of the certificate is allowed,
markrad 0:cdf462088d13 376 * MBEDTLS_ERR_X509_BAD_INPUT_DATA if not.
markrad 0:cdf462088d13 377 *
markrad 0:cdf462088d13 378 * \note Usually only makes sense on leaf certificates.
markrad 0:cdf462088d13 379 */
markrad 0:cdf462088d13 380 int mbedtls_x509_crt_check_extended_key_usage( const mbedtls_x509_crt *crt,
markrad 0:cdf462088d13 381 const char *usage_oid,
markrad 0:cdf462088d13 382 size_t usage_len );
markrad 0:cdf462088d13 383 #endif /* MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE) */
markrad 0:cdf462088d13 384
markrad 0:cdf462088d13 385 #if defined(MBEDTLS_X509_CRL_PARSE_C)
markrad 0:cdf462088d13 386 /**
markrad 0:cdf462088d13 387 * \brief Verify the certificate revocation status
markrad 0:cdf462088d13 388 *
markrad 0:cdf462088d13 389 * \param crt a certificate to be verified
markrad 0:cdf462088d13 390 * \param crl the CRL to verify against
markrad 0:cdf462088d13 391 *
markrad 0:cdf462088d13 392 * \return 1 if the certificate is revoked, 0 otherwise
markrad 0:cdf462088d13 393 *
markrad 0:cdf462088d13 394 */
markrad 0:cdf462088d13 395 int mbedtls_x509_crt_is_revoked( const mbedtls_x509_crt *crt, const mbedtls_x509_crl *crl );
markrad 0:cdf462088d13 396 #endif /* MBEDTLS_X509_CRL_PARSE_C */
markrad 0:cdf462088d13 397
markrad 0:cdf462088d13 398 /**
markrad 0:cdf462088d13 399 * \brief Initialize a certificate (chain)
markrad 0:cdf462088d13 400 *
markrad 0:cdf462088d13 401 * \param crt Certificate chain to initialize
markrad 0:cdf462088d13 402 */
markrad 0:cdf462088d13 403 void mbedtls_x509_crt_init( mbedtls_x509_crt *crt );
markrad 0:cdf462088d13 404
markrad 0:cdf462088d13 405 /**
markrad 0:cdf462088d13 406 * \brief Unallocate all certificate data
markrad 0:cdf462088d13 407 *
markrad 0:cdf462088d13 408 * \param crt Certificate chain to free
markrad 0:cdf462088d13 409 */
markrad 0:cdf462088d13 410 void mbedtls_x509_crt_free( mbedtls_x509_crt *crt );
markrad 0:cdf462088d13 411 #endif /* MBEDTLS_X509_CRT_PARSE_C */
markrad 0:cdf462088d13 412
markrad 0:cdf462088d13 413 /* \} name */
markrad 0:cdf462088d13 414 /* \} addtogroup x509_module */
markrad 0:cdf462088d13 415
markrad 0:cdf462088d13 416 #if defined(MBEDTLS_X509_CRT_WRITE_C)
markrad 0:cdf462088d13 417 /**
markrad 0:cdf462088d13 418 * \brief Initialize a CRT writing context
markrad 0:cdf462088d13 419 *
markrad 0:cdf462088d13 420 * \param ctx CRT context to initialize
markrad 0:cdf462088d13 421 */
markrad 0:cdf462088d13 422 void mbedtls_x509write_crt_init( mbedtls_x509write_cert *ctx );
markrad 0:cdf462088d13 423
markrad 0:cdf462088d13 424 /**
markrad 0:cdf462088d13 425 * \brief Set the verion for a Certificate
markrad 0:cdf462088d13 426 * Default: MBEDTLS_X509_CRT_VERSION_3
markrad 0:cdf462088d13 427 *
markrad 0:cdf462088d13 428 * \param ctx CRT context to use
markrad 0:cdf462088d13 429 * \param version version to set (MBEDTLS_X509_CRT_VERSION_1, MBEDTLS_X509_CRT_VERSION_2 or
markrad 0:cdf462088d13 430 * MBEDTLS_X509_CRT_VERSION_3)
markrad 0:cdf462088d13 431 */
markrad 0:cdf462088d13 432 void mbedtls_x509write_crt_set_version( mbedtls_x509write_cert *ctx, int version );
markrad 0:cdf462088d13 433
markrad 0:cdf462088d13 434 /**
markrad 0:cdf462088d13 435 * \brief Set the serial number for a Certificate.
markrad 0:cdf462088d13 436 *
markrad 0:cdf462088d13 437 * \param ctx CRT context to use
markrad 0:cdf462088d13 438 * \param serial serial number to set
markrad 0:cdf462088d13 439 *
markrad 0:cdf462088d13 440 * \return 0 if successful
markrad 0:cdf462088d13 441 */
markrad 0:cdf462088d13 442 int mbedtls_x509write_crt_set_serial( mbedtls_x509write_cert *ctx, const mbedtls_mpi *serial );
markrad 0:cdf462088d13 443
markrad 0:cdf462088d13 444 /**
markrad 0:cdf462088d13 445 * \brief Set the validity period for a Certificate
markrad 0:cdf462088d13 446 * Timestamps should be in string format for UTC timezone
markrad 0:cdf462088d13 447 * i.e. "YYYYMMDDhhmmss"
markrad 0:cdf462088d13 448 * e.g. "20131231235959" for December 31st 2013
markrad 0:cdf462088d13 449 * at 23:59:59
markrad 0:cdf462088d13 450 *
markrad 0:cdf462088d13 451 * \param ctx CRT context to use
markrad 0:cdf462088d13 452 * \param not_before not_before timestamp
markrad 0:cdf462088d13 453 * \param not_after not_after timestamp
markrad 0:cdf462088d13 454 *
markrad 0:cdf462088d13 455 * \return 0 if timestamp was parsed successfully, or
markrad 0:cdf462088d13 456 * a specific error code
markrad 0:cdf462088d13 457 */
markrad 0:cdf462088d13 458 int mbedtls_x509write_crt_set_validity( mbedtls_x509write_cert *ctx, const char *not_before,
markrad 0:cdf462088d13 459 const char *not_after );
markrad 0:cdf462088d13 460
markrad 0:cdf462088d13 461 /**
markrad 0:cdf462088d13 462 * \brief Set the issuer name for a Certificate
markrad 0:cdf462088d13 463 * Issuer names should contain a comma-separated list
markrad 0:cdf462088d13 464 * of OID types and values:
markrad 0:cdf462088d13 465 * e.g. "C=UK,O=ARM,CN=mbed TLS CA"
markrad 0:cdf462088d13 466 *
markrad 0:cdf462088d13 467 * \param ctx CRT context to use
markrad 0:cdf462088d13 468 * \param issuer_name issuer name to set
markrad 0:cdf462088d13 469 *
markrad 0:cdf462088d13 470 * \return 0 if issuer name was parsed successfully, or
markrad 0:cdf462088d13 471 * a specific error code
markrad 0:cdf462088d13 472 */
markrad 0:cdf462088d13 473 int mbedtls_x509write_crt_set_issuer_name( mbedtls_x509write_cert *ctx,
markrad 0:cdf462088d13 474 const char *issuer_name );
markrad 0:cdf462088d13 475
markrad 0:cdf462088d13 476 /**
markrad 0:cdf462088d13 477 * \brief Set the subject name for a Certificate
markrad 0:cdf462088d13 478 * Subject names should contain a comma-separated list
markrad 0:cdf462088d13 479 * of OID types and values:
markrad 0:cdf462088d13 480 * e.g. "C=UK,O=ARM,CN=mbed TLS Server 1"
markrad 0:cdf462088d13 481 *
markrad 0:cdf462088d13 482 * \param ctx CRT context to use
markrad 0:cdf462088d13 483 * \param subject_name subject name to set
markrad 0:cdf462088d13 484 *
markrad 0:cdf462088d13 485 * \return 0 if subject name was parsed successfully, or
markrad 0:cdf462088d13 486 * a specific error code
markrad 0:cdf462088d13 487 */
markrad 0:cdf462088d13 488 int mbedtls_x509write_crt_set_subject_name( mbedtls_x509write_cert *ctx,
markrad 0:cdf462088d13 489 const char *subject_name );
markrad 0:cdf462088d13 490
markrad 0:cdf462088d13 491 /**
markrad 0:cdf462088d13 492 * \brief Set the subject public key for the certificate
markrad 0:cdf462088d13 493 *
markrad 0:cdf462088d13 494 * \param ctx CRT context to use
markrad 0:cdf462088d13 495 * \param key public key to include
markrad 0:cdf462088d13 496 */
markrad 0:cdf462088d13 497 void mbedtls_x509write_crt_set_subject_key( mbedtls_x509write_cert *ctx, mbedtls_pk_context *key );
markrad 0:cdf462088d13 498
markrad 0:cdf462088d13 499 /**
markrad 0:cdf462088d13 500 * \brief Set the issuer key used for signing the certificate
markrad 0:cdf462088d13 501 *
markrad 0:cdf462088d13 502 * \param ctx CRT context to use
markrad 0:cdf462088d13 503 * \param key private key to sign with
markrad 0:cdf462088d13 504 */
markrad 0:cdf462088d13 505 void mbedtls_x509write_crt_set_issuer_key( mbedtls_x509write_cert *ctx, mbedtls_pk_context *key );
markrad 0:cdf462088d13 506
markrad 0:cdf462088d13 507 /**
markrad 0:cdf462088d13 508 * \brief Set the MD algorithm to use for the signature
markrad 0:cdf462088d13 509 * (e.g. MBEDTLS_MD_SHA1)
markrad 0:cdf462088d13 510 *
markrad 0:cdf462088d13 511 * \param ctx CRT context to use
markrad 0:cdf462088d13 512 * \param md_alg MD algorithm to use
markrad 0:cdf462088d13 513 */
markrad 0:cdf462088d13 514 void mbedtls_x509write_crt_set_md_alg( mbedtls_x509write_cert *ctx, mbedtls_md_type_t md_alg );
markrad 0:cdf462088d13 515
markrad 0:cdf462088d13 516 /**
markrad 0:cdf462088d13 517 * \brief Generic function to add to or replace an extension in the
markrad 0:cdf462088d13 518 * CRT
markrad 0:cdf462088d13 519 *
markrad 0:cdf462088d13 520 * \param ctx CRT context to use
markrad 0:cdf462088d13 521 * \param oid OID of the extension
markrad 0:cdf462088d13 522 * \param oid_len length of the OID
markrad 0:cdf462088d13 523 * \param critical if the extension is critical (per the RFC's definition)
markrad 0:cdf462088d13 524 * \param val value of the extension OCTET STRING
markrad 0:cdf462088d13 525 * \param val_len length of the value data
markrad 0:cdf462088d13 526 *
markrad 0:cdf462088d13 527 * \return 0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
markrad 0:cdf462088d13 528 */
markrad 0:cdf462088d13 529 int mbedtls_x509write_crt_set_extension( mbedtls_x509write_cert *ctx,
markrad 0:cdf462088d13 530 const char *oid, size_t oid_len,
markrad 0:cdf462088d13 531 int critical,
markrad 0:cdf462088d13 532 const unsigned char *val, size_t val_len );
markrad 0:cdf462088d13 533
markrad 0:cdf462088d13 534 /**
markrad 0:cdf462088d13 535 * \brief Set the basicConstraints extension for a CRT
markrad 0:cdf462088d13 536 *
markrad 0:cdf462088d13 537 * \param ctx CRT context to use
markrad 0:cdf462088d13 538 * \param is_ca is this a CA certificate
markrad 0:cdf462088d13 539 * \param max_pathlen maximum length of certificate chains below this
markrad 0:cdf462088d13 540 * certificate (only for CA certificates, -1 is
markrad 0:cdf462088d13 541 * inlimited)
markrad 0:cdf462088d13 542 *
markrad 0:cdf462088d13 543 * \return 0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
markrad 0:cdf462088d13 544 */
markrad 0:cdf462088d13 545 int mbedtls_x509write_crt_set_basic_constraints( mbedtls_x509write_cert *ctx,
markrad 0:cdf462088d13 546 int is_ca, int max_pathlen );
markrad 0:cdf462088d13 547
markrad 0:cdf462088d13 548 #if defined(MBEDTLS_SHA1_C)
markrad 0:cdf462088d13 549 /**
markrad 0:cdf462088d13 550 * \brief Set the subjectKeyIdentifier extension for a CRT
markrad 0:cdf462088d13 551 * Requires that mbedtls_x509write_crt_set_subject_key() has been
markrad 0:cdf462088d13 552 * called before
markrad 0:cdf462088d13 553 *
markrad 0:cdf462088d13 554 * \param ctx CRT context to use
markrad 0:cdf462088d13 555 *
markrad 0:cdf462088d13 556 * \return 0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
markrad 0:cdf462088d13 557 */
markrad 0:cdf462088d13 558 int mbedtls_x509write_crt_set_subject_key_identifier( mbedtls_x509write_cert *ctx );
markrad 0:cdf462088d13 559
markrad 0:cdf462088d13 560 /**
markrad 0:cdf462088d13 561 * \brief Set the authorityKeyIdentifier extension for a CRT
markrad 0:cdf462088d13 562 * Requires that mbedtls_x509write_crt_set_issuer_key() has been
markrad 0:cdf462088d13 563 * called before
markrad 0:cdf462088d13 564 *
markrad 0:cdf462088d13 565 * \param ctx CRT context to use
markrad 0:cdf462088d13 566 *
markrad 0:cdf462088d13 567 * \return 0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
markrad 0:cdf462088d13 568 */
markrad 0:cdf462088d13 569 int mbedtls_x509write_crt_set_authority_key_identifier( mbedtls_x509write_cert *ctx );
markrad 0:cdf462088d13 570 #endif /* MBEDTLS_SHA1_C */
markrad 0:cdf462088d13 571
markrad 0:cdf462088d13 572 /**
markrad 0:cdf462088d13 573 * \brief Set the Key Usage Extension flags
markrad 0:cdf462088d13 574 * (e.g. MBEDTLS_X509_KU_DIGITAL_SIGNATURE | MBEDTLS_X509_KU_KEY_CERT_SIGN)
markrad 0:cdf462088d13 575 *
markrad 0:cdf462088d13 576 * \param ctx CRT context to use
markrad 0:cdf462088d13 577 * \param key_usage key usage flags to set
markrad 0:cdf462088d13 578 *
markrad 0:cdf462088d13 579 * \return 0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED
markrad 0:cdf462088d13 580 */
markrad 0:cdf462088d13 581 int mbedtls_x509write_crt_set_key_usage( mbedtls_x509write_cert *ctx,
markrad 0:cdf462088d13 582 unsigned int key_usage );
markrad 0:cdf462088d13 583
markrad 0:cdf462088d13 584 /**
markrad 0:cdf462088d13 585 * \brief Set the Netscape Cert Type flags
markrad 0:cdf462088d13 586 * (e.g. MBEDTLS_X509_NS_CERT_TYPE_SSL_CLIENT | MBEDTLS_X509_NS_CERT_TYPE_EMAIL)
markrad 0:cdf462088d13 587 *
markrad 0:cdf462088d13 588 * \param ctx CRT context to use
markrad 0:cdf462088d13 589 * \param ns_cert_type Netscape Cert Type flags to set
markrad 0:cdf462088d13 590 *
markrad 0:cdf462088d13 591 * \return 0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED
markrad 0:cdf462088d13 592 */
markrad 0:cdf462088d13 593 int mbedtls_x509write_crt_set_ns_cert_type( mbedtls_x509write_cert *ctx,
markrad 0:cdf462088d13 594 unsigned char ns_cert_type );
markrad 0:cdf462088d13 595
markrad 0:cdf462088d13 596 /**
markrad 0:cdf462088d13 597 * \brief Free the contents of a CRT write context
markrad 0:cdf462088d13 598 *
markrad 0:cdf462088d13 599 * \param ctx CRT context to free
markrad 0:cdf462088d13 600 */
markrad 0:cdf462088d13 601 void mbedtls_x509write_crt_free( mbedtls_x509write_cert *ctx );
markrad 0:cdf462088d13 602
markrad 0:cdf462088d13 603 /**
markrad 0:cdf462088d13 604 * \brief Write a built up certificate to a X509 DER structure
markrad 0:cdf462088d13 605 * Note: data is written at the end of the buffer! Use the
markrad 0:cdf462088d13 606 * return value to determine where you should start
markrad 0:cdf462088d13 607 * using the buffer
markrad 0:cdf462088d13 608 *
markrad 0:cdf462088d13 609 * \param ctx certificate to write away
markrad 0:cdf462088d13 610 * \param buf buffer to write to
markrad 0:cdf462088d13 611 * \param size size of the buffer
markrad 0:cdf462088d13 612 * \param f_rng RNG function (for signature, see note)
markrad 0:cdf462088d13 613 * \param p_rng RNG parameter
markrad 0:cdf462088d13 614 *
markrad 0:cdf462088d13 615 * \return length of data written if successful, or a specific
markrad 0:cdf462088d13 616 * error code
markrad 0:cdf462088d13 617 *
markrad 0:cdf462088d13 618 * \note f_rng may be NULL if RSA is used for signature and the
markrad 0:cdf462088d13 619 * signature is made offline (otherwise f_rng is desirable
markrad 0:cdf462088d13 620 * for countermeasures against timing attacks).
markrad 0:cdf462088d13 621 * ECDSA signatures always require a non-NULL f_rng.
markrad 0:cdf462088d13 622 */
markrad 0:cdf462088d13 623 int mbedtls_x509write_crt_der( mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size,
markrad 0:cdf462088d13 624 int (*f_rng)(void *, unsigned char *, size_t),
markrad 0:cdf462088d13 625 void *p_rng );
markrad 0:cdf462088d13 626
markrad 0:cdf462088d13 627 #if defined(MBEDTLS_PEM_WRITE_C)
markrad 0:cdf462088d13 628 /**
markrad 0:cdf462088d13 629 * \brief Write a built up certificate to a X509 PEM string
markrad 0:cdf462088d13 630 *
markrad 0:cdf462088d13 631 * \param ctx certificate to write away
markrad 0:cdf462088d13 632 * \param buf buffer to write to
markrad 0:cdf462088d13 633 * \param size size of the buffer
markrad 0:cdf462088d13 634 * \param f_rng RNG function (for signature, see note)
markrad 0:cdf462088d13 635 * \param p_rng RNG parameter
markrad 0:cdf462088d13 636 *
markrad 0:cdf462088d13 637 * \return 0 if successful, or a specific error code
markrad 0:cdf462088d13 638 *
markrad 0:cdf462088d13 639 * \note f_rng may be NULL if RSA is used for signature and the
markrad 0:cdf462088d13 640 * signature is made offline (otherwise f_rng is desirable
markrad 0:cdf462088d13 641 * for countermeasures against timing attacks).
markrad 0:cdf462088d13 642 * ECDSA signatures always require a non-NULL f_rng.
markrad 0:cdf462088d13 643 */
markrad 0:cdf462088d13 644 int mbedtls_x509write_crt_pem( mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size,
markrad 0:cdf462088d13 645 int (*f_rng)(void *, unsigned char *, size_t),
markrad 0:cdf462088d13 646 void *p_rng );
markrad 0:cdf462088d13 647 #endif /* MBEDTLS_PEM_WRITE_C */
markrad 0:cdf462088d13 648 #endif /* MBEDTLS_X509_CRT_WRITE_C */
markrad 0:cdf462088d13 649
markrad 0:cdf462088d13 650 #ifdef __cplusplus
markrad 0:cdf462088d13 651 }
markrad 0:cdf462088d13 652 #endif
markrad 0:cdf462088d13 653
markrad 0:cdf462088d13 654 #endif /* mbedtls_x509_crt.h */