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