Branch data     Line data    Source code

       1                 :            : /*
       2                 :            :  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
       3                 :            :  *
       4                 :            :  * Licensed under the Apache License, Version 2.0 (the "License").
       5                 :            :  * You may not use this file except in compliance with the License.
       6                 :            :  * A copy of the License is located at
       7                 :            :  *
       8                 :            :  *  http://aws.amazon.com/apache2.0
       9                 :            :  *
      10                 :            :  * or in the "license" file accompanying this file. This file is distributed
      11                 :            :  * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
      12                 :            :  * express or implied. See the License for the specific language governing
      13                 :            :  * permissions and limitations under the License.
      14                 :            :  */
      15                 :            : 
      16                 :            : #pragma once
      17                 :            : 
      18                 :            : #include <openssl/x509v3.h>
      19                 :            : 
      20                 :            : #include "api/s2n.h"
      21                 :            : #include "tls/s2n_signature_scheme.h"
      22                 :            : 
      23                 :            : /* one day, BoringSSL may add ocsp stapling support. Let's future proof this a bit by grabbing a definition
      24                 :            :  * that would have to be there when they add support */
      25                 :            : #if defined(OPENSSL_IS_BORINGSSL) && !defined(OCSP_RESPONSE_STATUS_SUCCESSFUL)
      26                 :            :     #define S2N_OCSP_STAPLING_SUPPORTED 0
      27                 :            : #else
      28                 :        156 :     #define S2N_OCSP_STAPLING_SUPPORTED 1
      29                 :            : #endif /* defined(OPENSSL_IS_BORINGSSL) && !defined(OCSP_RESPONSE_STATUS_SUCCESSFUL) */
      30                 :            : 
      31                 :            : typedef enum {
      32                 :            :     UNINIT,
      33                 :            :     INIT,
      34                 :            :     READY_TO_VERIFY,
      35                 :            :     AWAITING_CRL_CALLBACK,
      36                 :            :     VALIDATED,
      37                 :            :     OCSP_VALIDATED,
      38                 :            : } validator_state;
      39                 :            : 
      40                 :            : /** Return TRUE for trusted, FALSE for untrusted **/
      41                 :            : typedef uint8_t (*verify_host)(const char *host_name, size_t host_name_len, void *data);
      42                 :            : struct s2n_connection;
      43                 :            : 
      44                 :            : /**
      45                 :            :  * Trust store simply contains the trust store each connection should validate certs against.
      46                 :            :  * For most use cases, you only need one of these per application.
      47                 :            :  */
      48                 :            : struct s2n_x509_trust_store {
      49                 :            :     X509_STORE *trust_store;
      50                 :            : 
      51                 :            :     /* Indicates whether system default certs have been loaded into the trust store */
      52                 :            :     unsigned loaded_system_certs : 1;
      53                 :            : };
      54                 :            : 
      55                 :            : struct s2n_cert_validation_info {
      56                 :            :     unsigned finished : 1;
      57                 :            :     unsigned accepted : 1;
      58                 :            : };
      59                 :            : 
      60                 :            : /**
      61                 :            :  * You should have one instance of this per connection.
      62                 :            :  */
      63                 :            : struct s2n_x509_validator {
      64                 :            :     struct s2n_x509_trust_store *trust_store;
      65                 :            :     X509_STORE_CTX *store_ctx;
      66                 :            :     uint8_t skip_cert_validation;
      67                 :            :     uint8_t check_stapled_ocsp;
      68                 :            :     uint16_t max_chain_depth;
      69                 :            :     STACK_OF(X509) *cert_chain_from_wire;
      70                 :            :     int state;
      71                 :            :     struct s2n_array *crl_lookup_list;
      72                 :            :     struct s2n_cert_validation_info cert_validation_info;
      73                 :            :     bool cert_validation_cb_invoked;
      74                 :            : };
      75                 :            : 
      76                 :            : /** Some libcrypto implementations do not support OCSP validation. Returns 1 if supported, 0 otherwise. */
      77                 :            : uint8_t s2n_x509_ocsp_stapling_supported(void);
      78                 :            : 
      79                 :            : /** Initialize the trust store to empty defaults (no allocations happen here) */
      80                 :            : void s2n_x509_trust_store_init_empty(struct s2n_x509_trust_store *store);
      81                 :            : 
      82                 :            : /** Returns TRUE if the trust store has certificates installed, FALSE otherwise */
      83                 :            : uint8_t s2n_x509_trust_store_has_certs(struct s2n_x509_trust_store *store);
      84                 :            : 
      85                 :            : /** Initialize trust store from a PEM. This will allocate memory, and load PEM into the Trust Store **/
      86                 :            : int s2n_x509_trust_store_add_pem(struct s2n_x509_trust_store *store, const char *pem);
      87                 :            : 
      88                 :            : /** Initialize trust store from a CA file. This will allocate memory, and load each cert in the file into the trust store
      89                 :            :  *  Returns 0 on success, or S2N error codes on failure. */
      90                 :            : int s2n_x509_trust_store_from_ca_file(struct s2n_x509_trust_store *store, const char *ca_pem_filename, const char *ca_dir);
      91                 :            : 
      92                 :            : /** Cleans up, and frees any underlying memory in the trust store. */
      93                 :            : void s2n_x509_trust_store_wipe(struct s2n_x509_trust_store *store);
      94                 :            : 
      95                 :            : /** Initialize the validator in unsafe mode. No validity checks for OCSP, host checks, or X.509 will be performed. */
      96                 :            : int s2n_x509_validator_init_no_x509_validation(struct s2n_x509_validator *validator);
      97                 :            : 
      98                 :            : /** Initialize the validator in safe mode. Will use trust store to validate x.509 certificates, ocsp responses, and will call
      99                 :            :  *  the verify host callback to determine if a subject name or alternative name from the cert should be trusted.
     100                 :            :  *  Returns 0 on success, and an S2N_ERR_* on failure.
     101                 :            :  */
     102                 :            : int s2n_x509_validator_init(struct s2n_x509_validator *validator, struct s2n_x509_trust_store *trust_store, uint8_t check_ocsp);
     103                 :            : 
     104                 :            : /**
     105                 :            :  * Sets the maximum depth for a cert chain that can be used at validation.
     106                 :            :  */
     107                 :            : int s2n_x509_validator_set_max_chain_depth(struct s2n_x509_validator *validator, uint16_t max_depth);
     108                 :            : 
     109                 :            : /** Cleans up underlying memory and data members. Struct can be reused afterwards. */
     110                 :            : int s2n_x509_validator_wipe(struct s2n_x509_validator *validator);
     111                 :            : 
     112                 :            : /**
     113                 :            :  * Validates a certificate chain against the configured trust store in safe mode. In unsafe mode, it will find the public key
     114                 :            :  * and return it but not validate the certificates. Alternative Names and Subject Name will be passed to the host verification callback.
     115                 :            :  * The verification callback will be possibly called multiple times depending on how many names are found.
     116                 :            :  * If any of those calls return TRUE, that stage of the validation will continue, otherwise once all names are tried and none matched as
     117                 :            :  * trusted, the chain will be considered UNTRUSTED.
     118                 :            :  *
     119                 :            :  * This function can only be called once per instance of an s2n_x509_validator. If must be called prior to calling
     120                 :            :  * s2n_x509_validator_validate_cert_stapled_ocsp_response().
     121                 :            :  */
     122                 :            : S2N_RESULT s2n_x509_validator_validate_cert_chain(struct s2n_x509_validator *validator, struct s2n_connection *conn,
     123                 :            :         uint8_t *cert_chain_in, uint32_t cert_chain_len, s2n_pkey_type *pkey_type,
     124                 :            :         struct s2n_pkey *public_key_out);
     125                 :            : 
     126                 :            : /**
     127                 :            :  * Validates an ocsp response against the most recent certificate chain. Also verifies the timestamps on the response. This function can only be
     128                 :            :  * called once per instance of an s2n_x509_validator and only after a successful call to s2n_x509_validator_validate_cert_chain().
     129                 :            :  */
     130                 :            : S2N_RESULT s2n_x509_validator_validate_cert_stapled_ocsp_response(struct s2n_x509_validator *validator, struct s2n_connection *conn,
     131                 :            :         const uint8_t *ocsp_response, uint32_t size);
     132                 :            : 
     133                 :            : /**
     134                 :            :  * Checks whether the peer's certificate chain has been received and validated.
     135                 :            :  * Should be verified before any use of the peer's certificate data.
     136                 :            :  */
     137                 :            : bool s2n_x509_validator_is_cert_chain_validated(const struct s2n_x509_validator *validator);