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_constants.h> 23 #include <grpc/status.h> 24 #include <grpc/support/log.h> 25 #include <grpcpp/security/tls_certificate_provider.h> 26 #include <grpcpp/support/config.h> 27 28 #include <memory> 29 #include <vector> 30 31 // TODO(yihuazhang): remove the forward declaration here and include 32 // <grpc/grpc_security.h> directly once the insecure builds are cleaned up. 33 typedef struct grpc_tls_server_authorization_check_arg 34 grpc_tls_server_authorization_check_arg; 35 typedef struct grpc_tls_server_authorization_check_config 36 grpc_tls_server_authorization_check_config; 37 typedef struct grpc_tls_credentials_options grpc_tls_credentials_options; 38 typedef struct grpc_tls_certificate_provider grpc_tls_certificate_provider; 39 40 namespace grpc { 41 namespace experimental { 42 43 /** TLS server authorization check arguments, wraps 44 * grpc_tls_server_authorization_check_arg. It is used for experimental 45 * purposes for now and it is subject to change. 46 * 47 * The server authorization check arg contains all the info necessary to 48 * schedule/cancel a server authorization check request. The callback function 49 * must be called after finishing the schedule operation. See the description 50 * of the grpc_tls_server_authorization_check_arg struct in grpc_security.h for 51 * more details. **/ 52 class TlsServerAuthorizationCheckArg { 53 public: 54 /** TlsServerAuthorizationCheckArg does not take ownership of the C arg passed 55 * to the constructor. One must remember to free any memory allocated to the 56 * C arg after using the setter functions below. **/ 57 explicit TlsServerAuthorizationCheckArg( 58 grpc_tls_server_authorization_check_arg* arg); 59 ~TlsServerAuthorizationCheckArg(); 60 61 /** Getters for member fields. **/ 62 void* cb_user_data() const; 63 int success() const; 64 std::string target_name() const; 65 std::string peer_cert() const; 66 std::string peer_cert_full_chain() const; 67 grpc_status_code status() const; 68 std::string error_details() const; 69 70 /** Setters for member fields. **/ 71 void set_cb_user_data(void* cb_user_data); 72 void set_success(int success); 73 void set_target_name(const std::string& target_name); 74 void set_peer_cert(const std::string& peer_cert); 75 void set_peer_cert_full_chain(const std::string& peer_cert_full_chain); 76 void set_status(grpc_status_code status); 77 void set_error_details(const std::string& error_details); 78 79 /** Calls the C arg's callback function. **/ 80 void OnServerAuthorizationCheckDoneCallback(); 81 82 private: 83 grpc_tls_server_authorization_check_arg* c_arg_; 84 }; 85 86 /** An interface that the application derives and uses to instantiate a 87 * TlsServerAuthorizationCheckConfig instance. Refer to the definition of the 88 * grpc_tls_server_authorization_check_config in grpc_tls_credentials_options.h 89 * for more details on the expectations of the member functions of the 90 * interface. 91 * **/ 92 struct TlsServerAuthorizationCheckInterface { 93 virtual ~TlsServerAuthorizationCheckInterface() = default; 94 /** A callback that invokes the server authorization check. **/ 95 virtual int Schedule(TlsServerAuthorizationCheckArg* arg) = 0; 96 /** A callback that cancels a server authorization check request. **/ CancelTlsServerAuthorizationCheckInterface97 virtual void Cancel(TlsServerAuthorizationCheckArg* /* arg */) {} 98 }; 99 100 /** TLS server authorization check config, wraps 101 * grps_tls_server_authorization_check_config. It is used for experimental 102 * purposes for now and it is subject to change. **/ 103 class TlsServerAuthorizationCheckConfig { 104 public: 105 explicit TlsServerAuthorizationCheckConfig( 106 std::shared_ptr<TlsServerAuthorizationCheckInterface> 107 server_authorization_check_interface); 108 ~TlsServerAuthorizationCheckConfig(); 109 Schedule(TlsServerAuthorizationCheckArg * arg)110 int Schedule(TlsServerAuthorizationCheckArg* arg) const { 111 if (server_authorization_check_interface_ == nullptr) { 112 gpr_log(GPR_ERROR, "server authorization check interface is nullptr"); 113 if (arg != nullptr) { 114 arg->set_status(GRPC_STATUS_NOT_FOUND); 115 arg->set_error_details( 116 "the interface of the server authorization check config is " 117 "nullptr"); 118 } 119 return 1; 120 } 121 return server_authorization_check_interface_->Schedule(arg); 122 } 123 Cancel(TlsServerAuthorizationCheckArg * arg)124 void Cancel(TlsServerAuthorizationCheckArg* arg) const { 125 if (server_authorization_check_interface_ == nullptr) { 126 gpr_log(GPR_ERROR, "server authorization check interface is nullptr"); 127 if (arg != nullptr) { 128 arg->set_status(GRPC_STATUS_NOT_FOUND); 129 arg->set_error_details( 130 "the interface of the server authorization check config is " 131 "nullptr"); 132 } 133 return; 134 } 135 server_authorization_check_interface_->Cancel(arg); 136 } 137 138 /** Returns C struct for the server authorization check config. **/ c_config()139 grpc_tls_server_authorization_check_config* c_config() const { 140 return c_config_; 141 } 142 143 private: 144 grpc_tls_server_authorization_check_config* c_config_; 145 std::shared_ptr<TlsServerAuthorizationCheckInterface> 146 server_authorization_check_interface_; 147 }; 148 149 // Base class of configurable options specified by users to configure their 150 // certain security features supported in TLS. It is used for experimental 151 // purposes for now and it is subject to change. 152 class TlsCredentialsOptions { 153 public: 154 // Constructor for base class TlsCredentialsOptions. 155 // 156 // @param certificate_provider the provider which fetches TLS credentials that 157 // will be used in the TLS handshake 158 TlsCredentialsOptions(); 159 // ---- Setters for member fields ---- 160 // Sets the certificate provider used to store root certs and identity certs. 161 void set_certificate_provider( 162 std::shared_ptr<CertificateProviderInterface> certificate_provider); 163 // Watches the updates of root certificates with name |root_cert_name|. 164 // If used in TLS credentials, setting this field is optional for both the 165 // client side and the server side. 166 // If this is not set on the client side, we will use the root certificates 167 // stored in the default system location, since client side must provide root 168 // certificates in TLS(no matter single-side TLS or mutual TLS). 169 // If this is not set on the server side, we will not watch any root 170 // certificate updates, and assume no root certificates needed for the server 171 // (in the one-side TLS scenario, the server is not required to provide root 172 // certs). We don't support default root certs on server side. 173 void watch_root_certs(); 174 // Sets the name of root certificates being watched, if |watch_root_certs| is 175 // called. If not set, an empty string will be used as the name. 176 // 177 // @param root_cert_name the name of root certs being set. 178 void set_root_cert_name(const std::string& root_cert_name); 179 // Watches the updates of identity key-cert pairs with name 180 // |identity_cert_name|. If used in TLS credentials, it is required to be set 181 // on the server side, and optional for the client side(in the one-side 182 // TLS scenario, the client is not required to provide identity certs). 183 void watch_identity_key_cert_pairs(); 184 // Sets the name of identity key-cert pairs being watched, if 185 // |watch_identity_key_cert_pairs| is called. If not set, an empty string will 186 // be used as the name. 187 // 188 // @param identity_cert_name the name of identity key-cert pairs being set. 189 void set_identity_cert_name(const std::string& identity_cert_name); 190 191 // ----- Getters for member fields ---- 192 // Get the internal c options. This function shall be used only internally. c_credentials_options()193 grpc_tls_credentials_options* c_credentials_options() const { 194 return c_credentials_options_; 195 } 196 197 private: 198 std::shared_ptr<CertificateProviderInterface> certificate_provider_; 199 grpc_tls_credentials_options* c_credentials_options_ = nullptr; 200 }; 201 202 // Contains configurable options on the client side. 203 // Client side doesn't need to always use certificate provider. When the 204 // certificate provider is not set, we will use the root certificates stored 205 // in the system default locations, and assume client won't provide any 206 // identity certificates(single side TLS). 207 // It is used for experimental purposes for now and it is subject to change. 208 class TlsChannelCredentialsOptions final : public TlsCredentialsOptions { 209 public: 210 // Sets the option to verify the server. 211 // The default is GRPC_TLS_SERVER_VERIFICATION. 212 void set_server_verification_option( 213 grpc_tls_server_verification_option server_verification_option); 214 // Sets the custom authorization config. 215 void set_server_authorization_check_config( 216 std::shared_ptr<TlsServerAuthorizationCheckConfig> 217 authorization_check_config); 218 219 private: 220 }; 221 222 // Contains configurable options on the server side. 223 // It is used for experimental purposes for now and it is subject to change. 224 class TlsServerCredentialsOptions final : public TlsCredentialsOptions { 225 public: 226 // Server side is required to use a provider, because server always needs to 227 // use identity certs. TlsServerCredentialsOptions(std::shared_ptr<CertificateProviderInterface> certificate_provider)228 explicit TlsServerCredentialsOptions( 229 std::shared_ptr<CertificateProviderInterface> certificate_provider) 230 : TlsCredentialsOptions() { 231 set_certificate_provider(certificate_provider); 232 } 233 234 // Sets option to request the certificates from the client. 235 // The default is GRPC_SSL_DONT_REQUEST_CLIENT_CERTIFICATE. 236 void set_cert_request_type( 237 grpc_ssl_client_certificate_request_type cert_request_type); 238 239 private: 240 }; 241 242 } // namespace experimental 243 } // namespace grpc 244 245 #endif // GRPCPP_SECURITY_TLS_CREDENTIALS_OPTIONS_H 246