1 // 2 // 3 // Copyright 2019 gRPC authors. 4 // 5 // Licensed under the Apache License, Version 2.0 (the "License"); 6 // you may not use this file except in compliance with the License. 7 // You may obtain a copy of the License at 8 // 9 // http://www.apache.org/licenses/LICENSE-2.0 10 // 11 // Unless required by applicable law or agreed to in writing, software 12 // distributed under the License is distributed on an "AS IS" BASIS, 13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 // See the License for the specific language governing permissions and 15 // limitations under the License. 16 // 17 // 18 19 #ifndef GRPCPP_SECURITY_TLS_CREDENTIALS_OPTIONS_H 20 #define GRPCPP_SECURITY_TLS_CREDENTIALS_OPTIONS_H 21 22 #include <memory> 23 #include <vector> 24 25 #include <grpc/grpc_security.h> 26 #include <grpc/grpc_security_constants.h> 27 #include <grpc/status.h> 28 #include <grpc/support/log.h> 29 #include <grpcpp/security/tls_certificate_provider.h> 30 #include <grpcpp/security/tls_certificate_verifier.h> 31 #include <grpcpp/support/config.h> 32 33 namespace grpc { 34 namespace experimental { 35 36 // Base class of configurable options specified by users to configure their 37 // certain security features supported in TLS. It is used for experimental 38 // purposes for now and it is subject to change. 39 class TlsCredentialsOptions { 40 public: 41 // Constructor for base class TlsCredentialsOptions. 42 // 43 // @param certificate_provider the provider which fetches TLS credentials that 44 // will be used in the TLS handshake 45 TlsCredentialsOptions(); 46 // ---- Setters for member fields ---- 47 // Sets the certificate provider used to store root certs and identity certs. 48 void set_certificate_provider( 49 std::shared_ptr<CertificateProviderInterface> certificate_provider); 50 // Watches the updates of root certificates with name |root_cert_name|. 51 // If used in TLS credentials, setting this field is optional for both the 52 // client side and the server side. 53 // If this is not set on the client side, we will use the root certificates 54 // stored in the default system location, since client side must provide root 55 // certificates in TLS(no matter single-side TLS or mutual TLS). 56 // If this is not set on the server side, we will not watch any root 57 // certificate updates, and assume no root certificates needed for the server 58 // (in the one-side TLS scenario, the server is not required to provide root 59 // certs). We don't support default root certs on server side. 60 void watch_root_certs(); 61 // Sets the name of root certificates being watched, if |watch_root_certs| is 62 // called. If not set, an empty string will be used as the name. 63 // 64 // @param root_cert_name the name of root certs being set. 65 void set_root_cert_name(const std::string& root_cert_name); 66 // Watches the updates of identity key-cert pairs with name 67 // |identity_cert_name|. If used in TLS credentials, it is required to be set 68 // on the server side, and optional for the client side(in the one-side 69 // TLS scenario, the client is not required to provide identity certs). 70 void watch_identity_key_cert_pairs(); 71 // Sets the name of identity key-cert pairs being watched, if 72 // |watch_identity_key_cert_pairs| is called. If not set, an empty string will 73 // be used as the name. 74 // 75 // @param identity_cert_name the name of identity key-cert pairs being set. 76 void set_identity_cert_name(const std::string& identity_cert_name); 77 // Sets the Tls session key logging configuration. If not set, tls 78 // session key logging is disabled. Note that this should be used only for 79 // debugging purposes. It should never be used in a production environment 80 // due to security concerns. 81 // 82 // @param tls_session_key_log_file_path: Path where tls session keys would 83 // be logged. 84 void set_tls_session_key_log_file_path( 85 const std::string& tls_session_key_log_file_path); 86 // Sets the certificate verifier used to perform post-handshake peer identity 87 // checks. 88 void set_certificate_verifier( 89 std::shared_ptr<CertificateVerifier> certificate_verifier); 90 // Sets the options of whether to check the hostname of the peer on a per-call 91 // basis. This is usually used in a combination with virtual hosting at the 92 // client side, where each individual call on a channel can have a different 93 // host associated with it. 94 // This check is intended to verify that the host specified for the individual 95 // call is covered by the cert that the peer presented. 96 // We will perform such checks by default. This should be disabled if 97 // verifiers other than the host name verifier is used. 98 void set_check_call_host(bool check_call_host); 99 100 // TODO(zhenlian): This is an experimental API is likely to change in the 101 // future. Before de-experiementalizing, verify the API is up to date. 102 // If set, gRPC will read all hashed x.509 CRL files in the directory and 103 // enforce the CRL files on all TLS handshakes. Only supported for OpenSSL 104 // version > 1.1. 105 void set_crl_directory(const std::string& path); 106 107 // ----- Getters for member fields ---- 108 // Get the internal c options. This function shall be used only internally. c_credentials_options()109 grpc_tls_credentials_options* c_credentials_options() const { 110 return c_credentials_options_; 111 } 112 113 private: 114 std::shared_ptr<CertificateProviderInterface> certificate_provider_; 115 std::shared_ptr<CertificateVerifier> certificate_verifier_; 116 grpc_tls_credentials_options* c_credentials_options_ = nullptr; 117 }; 118 119 // Contains configurable options on the client side. 120 // Client side doesn't need to always use certificate provider. When the 121 // certificate provider is not set, we will use the root certificates stored 122 // in the system default locations, and assume client won't provide any 123 // identity certificates(single side TLS). 124 // It is used for experimental purposes for now and it is subject to change. 125 class TlsChannelCredentialsOptions final : public TlsCredentialsOptions { 126 public: 127 // Sets the decision of whether to do a crypto check on the server certs. 128 // The default is true. 129 void set_verify_server_certs(bool verify_server_certs); 130 131 private: 132 }; 133 134 // Contains configurable options on the server side. 135 // It is used for experimental purposes for now and it is subject to change. 136 class TlsServerCredentialsOptions final : public TlsCredentialsOptions { 137 public: 138 // Server side is required to use a provider, because server always needs to 139 // use identity certs. TlsServerCredentialsOptions(std::shared_ptr<CertificateProviderInterface> certificate_provider)140 explicit TlsServerCredentialsOptions( 141 std::shared_ptr<CertificateProviderInterface> certificate_provider) 142 : TlsCredentialsOptions() { 143 set_certificate_provider(certificate_provider); 144 } 145 146 // Sets option to request the certificates from the client. 147 // The default is GRPC_SSL_DONT_REQUEST_CLIENT_CERTIFICATE. 148 void set_cert_request_type( 149 grpc_ssl_client_certificate_request_type cert_request_type); 150 151 // Sets whether or not a TLS server should send a list of CA names in the 152 // ServerHello. This list of CA names is read from the server's trust bundle, 153 // so that the client can use this list as a hint to know which certificate it 154 // should send to the server. 155 // 156 // By default, this option is turned off. 157 // 158 // WARNING: This API is extremely dangerous and should not be used. If the 159 // server's trust bundle is too large, then the TLS server will be unable to 160 // form a ServerHello, and hence will be unusable. 161 void set_send_client_ca_list(bool send_client_ca_list); 162 163 private: 164 }; 165 166 } // namespace experimental 167 } // namespace grpc 168 169 #endif // GRPCPP_SECURITY_TLS_CREDENTIALS_OPTIONS_H 170