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