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/security/tls_crl_provider.h> 32 #include <grpcpp/support/config.h> 33 34 namespace grpc { 35 namespace experimental { 36 37 // Base class of configurable options specified by users to configure their 38 // certain security features supported in TLS. It is used for experimental 39 // purposes for now and it is subject to change. 40 class TlsCredentialsOptions { 41 public: 42 // Constructor for base class TlsCredentialsOptions. 43 // 44 // @param certificate_provider the provider which fetches TLS credentials that 45 // will be used in the TLS handshake 46 TlsCredentialsOptions(); 47 ~TlsCredentialsOptions(); 48 49 // Copy constructor does a deep copy of the underlying pointer. No assignment 50 // permitted 51 TlsCredentialsOptions(const TlsCredentialsOptions& other); 52 TlsCredentialsOptions& operator=(const TlsCredentialsOptions& other) = delete; 53 54 // ---- Setters for member fields ---- 55 // Sets the certificate provider used to store root certs and identity certs. 56 void set_certificate_provider( 57 std::shared_ptr<CertificateProviderInterface> certificate_provider); 58 // Watches the updates of root certificates with name |root_cert_name|. 59 // If used in TLS credentials, setting this field is optional for both the 60 // client side and the server side. 61 // If this is not set on the client side, we will use the root certificates 62 // stored in the default system location, since client side must provide root 63 // certificates in TLS(no matter single-side TLS or mutual TLS). 64 // If this is not set on the server side, we will not watch any root 65 // certificate updates, and assume no root certificates needed for the server 66 // (in the one-side TLS scenario, the server is not required to provide root 67 // certs). We don't support default root certs on server side. 68 void watch_root_certs(); 69 // Sets the name of root certificates being watched, if |watch_root_certs| is 70 // called. If not set, an empty string will be used as the name. 71 // 72 // @param root_cert_name the name of root certs being set. 73 void set_root_cert_name(const std::string& root_cert_name); 74 // Watches the updates of identity key-cert pairs with name 75 // |identity_cert_name|. If used in TLS credentials, it is required to be set 76 // on the server side, and optional for the client side(in the one-side 77 // TLS scenario, the client is not required to provide identity certs). 78 void watch_identity_key_cert_pairs(); 79 // Sets the name of identity key-cert pairs being watched, if 80 // |watch_identity_key_cert_pairs| is called. If not set, an empty string will 81 // be used as the name. 82 // 83 // @param identity_cert_name the name of identity key-cert pairs being set. 84 void set_identity_cert_name(const std::string& identity_cert_name); 85 // Sets the Tls session key logging configuration. If not set, tls 86 // session key logging is disabled. Note that this should be used only for 87 // debugging purposes. It should never be used in a production environment 88 // due to security concerns. 89 // 90 // @param tls_session_key_log_file_path: Path where tls session keys would 91 // be logged. 92 void set_tls_session_key_log_file_path( 93 const std::string& tls_session_key_log_file_path); 94 // Sets the certificate verifier used to perform post-handshake peer identity 95 // checks. 96 void set_certificate_verifier( 97 std::shared_ptr<CertificateVerifier> certificate_verifier); 98 // Sets the options of whether to check the hostname of the peer on a per-call 99 // basis. This is usually used in a combination with virtual hosting at the 100 // client side, where each individual call on a channel can have a different 101 // host associated with it. 102 // This check is intended to verify that the host specified for the individual 103 // call is covered by the cert that the peer presented. 104 // We will perform such checks by default. This should be disabled if 105 // verifiers other than the host name verifier is used. 106 void set_check_call_host(bool check_call_host); 107 108 // Deprecated in favor of set_crl_provider. The 109 // crl provider interface provides a significantly more flexible approach to 110 // using CRLs. See gRFC A69 for details. 111 // If set, gRPC will read all hashed x.509 CRL files in the directory and 112 // enforce the CRL files on all TLS handshakes. Only supported for OpenSSL 113 // version > 1.1. 114 void set_crl_directory(const std::string& path); 115 116 void set_crl_provider(std::shared_ptr<CrlProvider> crl_provider); 117 118 // Sets the minimum TLS version that will be negotiated during the TLS 119 // handshake. If not set, the underlying SSL library will use TLS v1.2. 120 // @param tls_version: The minimum TLS version. 121 void set_min_tls_version(grpc_tls_version tls_version); 122 // Sets the maximum TLS version that will be negotiated during the TLS 123 // handshake. If not set, the underlying SSL library will use TLS v1.3. 124 // @param tls_version: The maximum TLS version. 125 void set_max_tls_version(grpc_tls_version tls_version); 126 127 // ----- Getters for member fields ---- 128 // Returns a deep copy of the internal c options. The caller takes ownership 129 // of the returned pointer. This function shall be used only internally. 130 grpc_tls_credentials_options* c_credentials_options() const; 131 132 protected: 133 // Returns the internal c options. The caller does not take ownership of the 134 // returned pointer. mutable_c_credentials_options()135 grpc_tls_credentials_options* mutable_c_credentials_options() { 136 return c_credentials_options_; 137 } 138 139 private: 140 std::shared_ptr<CertificateProviderInterface> certificate_provider_; 141 std::shared_ptr<CertificateVerifier> certificate_verifier_; 142 grpc_tls_credentials_options* c_credentials_options_ = nullptr; 143 }; 144 145 // Contains configurable options on the client side. 146 // Client side doesn't need to always use certificate provider. When the 147 // certificate provider is not set, we will use the root certificates stored 148 // in the system default locations, and assume client won't provide any 149 // identity certificates(single side TLS). 150 // It is used for experimental purposes for now and it is subject to change. 151 class TlsChannelCredentialsOptions final : public TlsCredentialsOptions { 152 public: 153 // Sets the decision of whether to do a crypto check on the server certs. 154 // The default is true. 155 void set_verify_server_certs(bool verify_server_certs); 156 157 private: 158 }; 159 160 // Contains configurable options on the server side. 161 // It is used for experimental purposes for now and it is subject to change. 162 class TlsServerCredentialsOptions final : public TlsCredentialsOptions { 163 public: 164 // Server side is required to use a provider, because server always needs to 165 // use identity certs. TlsServerCredentialsOptions(std::shared_ptr<CertificateProviderInterface> certificate_provider)166 explicit TlsServerCredentialsOptions( 167 std::shared_ptr<CertificateProviderInterface> certificate_provider) 168 : TlsCredentialsOptions() { 169 set_certificate_provider(certificate_provider); 170 } 171 172 // Sets option to request the certificates from the client. 173 // The default is GRPC_SSL_DONT_REQUEST_CLIENT_CERTIFICATE. 174 void set_cert_request_type( 175 grpc_ssl_client_certificate_request_type cert_request_type); 176 177 // Sets whether or not a TLS server should send a list of CA names in the 178 // ServerHello. This list of CA names is read from the server's trust bundle, 179 // so that the client can use this list as a hint to know which certificate it 180 // should send to the server. 181 // 182 // By default, this option is turned off. 183 // 184 // WARNING: This API is extremely dangerous and should not be used. If the 185 // server's trust bundle is too large, then the TLS server will be unable to 186 // form a ServerHello, and hence will be unusable. 187 void set_send_client_ca_list(bool send_client_ca_list); 188 189 private: 190 }; 191 192 } // namespace experimental 193 } // namespace grpc 194 195 #endif // GRPCPP_SECURITY_TLS_CREDENTIALS_OPTIONS_H 196