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/support/config.h> 26 27 #include <memory> 28 #include <vector> 29 30 typedef struct grpc_tls_credential_reload_arg grpc_tls_credential_reload_arg; 31 typedef struct grpc_tls_credential_reload_config 32 grpc_tls_credential_reload_config; 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 39 namespace grpc_impl { 40 namespace experimental { 41 42 /** TLS key materials config, wrapper for grpc_tls_key_materials_config. It is 43 * used for experimental purposes for now and subject to change. **/ 44 class TlsKeyMaterialsConfig { 45 public: 46 struct PemKeyCertPair { 47 grpc::string private_key; 48 grpc::string cert_chain; 49 }; 50 51 /** Getters for member fields. **/ pem_root_certs()52 const grpc::string pem_root_certs() const { return pem_root_certs_; } pem_key_cert_pair_list()53 const std::vector<PemKeyCertPair>& pem_key_cert_pair_list() const { 54 return pem_key_cert_pair_list_; 55 } version()56 int version() const { return version_; } 57 58 /** Setter for key materials that will be called by the user. Ownership of the 59 * arguments will not be transferred. **/ 60 void set_pem_root_certs(const grpc::string& pem_root_certs); 61 void add_pem_key_cert_pair(const PemKeyCertPair& pem_key_cert_pair); 62 void set_key_materials( 63 const grpc::string& pem_root_certs, 64 const std::vector<PemKeyCertPair>& pem_key_cert_pair_list); set_version(int version)65 void set_version(int version) { version_ = version; }; 66 67 private: 68 int version_ = 0; 69 std::vector<PemKeyCertPair> pem_key_cert_pair_list_; 70 grpc::string pem_root_certs_; 71 }; 72 73 /** TLS credential reload arguments, wraps grpc_tls_credential_reload_arg. It is 74 * used for experimental purposes for now and it is subject to change. 75 * 76 * The credential reload arg contains all the info necessary to schedule/cancel 77 * a credential reload request. The callback function must be called after 78 * finishing the schedule operation. See the description of the 79 * grpc_tls_credential_reload_arg struct in grpc_security.h for more details. 80 * **/ 81 class TlsCredentialReloadArg { 82 public: 83 /** TlsCredentialReloadArg does not take ownership of the C arg that is passed 84 * to the constructor. One must remember to free any memory allocated to the 85 * C arg after using the setter functions below. **/ 86 TlsCredentialReloadArg(grpc_tls_credential_reload_arg* arg); 87 ~TlsCredentialReloadArg(); 88 89 /** Getters for member fields. **/ 90 void* cb_user_data() const; 91 bool is_pem_key_cert_pair_list_empty() const; 92 grpc_ssl_certificate_config_reload_status status() const; 93 grpc::string error_details() const; 94 95 /** Setters for member fields. Ownership of the arguments will not be 96 * transferred. **/ 97 void set_cb_user_data(void* cb_user_data); 98 void set_pem_root_certs(const grpc::string& pem_root_certs); 99 void add_pem_key_cert_pair( 100 const TlsKeyMaterialsConfig::PemKeyCertPair& pem_key_cert_pair); 101 void set_key_materials(const grpc::string& pem_root_certs, 102 std::vector<TlsKeyMaterialsConfig::PemKeyCertPair> 103 pem_key_cert_pair_list); 104 void set_key_materials_config( 105 const std::shared_ptr<TlsKeyMaterialsConfig>& key_materials_config); 106 void set_status(grpc_ssl_certificate_config_reload_status status); 107 void set_error_details(const grpc::string& error_details); 108 109 /** Calls the C arg's callback function. **/ 110 void OnCredentialReloadDoneCallback(); 111 112 private: 113 grpc_tls_credential_reload_arg* c_arg_; 114 }; 115 116 /** An interface that the application derives and uses to instantiate a 117 * TlsCredentialReloadConfig instance. Refer to the definition of the 118 * grpc_tls_credential_reload_config in grpc_tls_credentials_options.h for more 119 * details on the expectations of the member functions of the interface. **/ 120 struct TlsCredentialReloadInterface { 121 virtual ~TlsCredentialReloadInterface() = default; 122 /** A callback that invokes the credential reload. **/ 123 virtual int Schedule(TlsCredentialReloadArg* arg) = 0; 124 /** A callback that cancels a credential reload request. **/ CancelTlsCredentialReloadInterface125 virtual void Cancel(TlsCredentialReloadArg* /* arg */) {} 126 }; 127 128 /** TLS credential reloag config, wraps grpc_tls_credential_reload_config. It is 129 * used for experimental purposes for now and it is subject to change. **/ 130 class TlsCredentialReloadConfig { 131 public: 132 TlsCredentialReloadConfig(std::shared_ptr<TlsCredentialReloadInterface> 133 credential_reload_interface); 134 ~TlsCredentialReloadConfig(); 135 Schedule(TlsCredentialReloadArg * arg)136 int Schedule(TlsCredentialReloadArg* arg) const { 137 if (credential_reload_interface_ == nullptr) { 138 gpr_log(GPR_ERROR, "credential reload interface is nullptr"); 139 if (arg != nullptr) { 140 arg->set_status(GRPC_SSL_CERTIFICATE_CONFIG_RELOAD_FAIL); 141 arg->set_error_details( 142 "the interface of the credential reload config is nullptr"); 143 } 144 return 1; 145 } 146 return credential_reload_interface_->Schedule(arg); 147 } 148 Cancel(TlsCredentialReloadArg * arg)149 void Cancel(TlsCredentialReloadArg* arg) const { 150 if (credential_reload_interface_ == nullptr) { 151 gpr_log(GPR_ERROR, "credential reload interface is nullptr"); 152 if (arg != nullptr) { 153 arg->set_status(GRPC_SSL_CERTIFICATE_CONFIG_RELOAD_FAIL); 154 arg->set_error_details( 155 "the interface of the credential reload config is nullptr"); 156 } 157 return; 158 } 159 credential_reload_interface_->Cancel(arg); 160 } 161 162 /** Returns a C struct for the credential reload config. **/ c_config()163 grpc_tls_credential_reload_config* c_config() const { return c_config_; } 164 165 private: 166 grpc_tls_credential_reload_config* c_config_; 167 std::shared_ptr<TlsCredentialReloadInterface> credential_reload_interface_; 168 }; 169 170 /** TLS server authorization check arguments, wraps 171 * grpc_tls_server_authorization_check_arg. It is used for experimental 172 * purposes for now and it is subject to change. 173 * 174 * The server authorization check arg contains all the info necessary to 175 * schedule/cancel a server authorization check request. The callback function 176 * must be called after finishing the schedule operation. See the description 177 * of the grpc_tls_server_authorization_check_arg struct in grpc_security.h for 178 * more details. **/ 179 class TlsServerAuthorizationCheckArg { 180 public: 181 /** TlsServerAuthorizationCheckArg does not take ownership of the C arg passed 182 * to the constructor. One must remember to free any memory allocated to the 183 * C arg after using the setter functions below. **/ 184 TlsServerAuthorizationCheckArg(grpc_tls_server_authorization_check_arg* arg); 185 ~TlsServerAuthorizationCheckArg(); 186 187 /** Getters for member fields. **/ 188 void* cb_user_data() const; 189 int success() const; 190 grpc::string target_name() const; 191 grpc::string peer_cert() const; 192 grpc::string peer_cert_full_chain() const; 193 grpc_status_code status() const; 194 grpc::string error_details() const; 195 196 /** Setters for member fields. **/ 197 void set_cb_user_data(void* cb_user_data); 198 void set_success(int success); 199 void set_target_name(const grpc::string& target_name); 200 void set_peer_cert(const grpc::string& peer_cert); 201 void set_peer_cert_full_chain(const grpc::string& peer_cert_full_chain); 202 void set_status(grpc_status_code status); 203 void set_error_details(const grpc::string& error_details); 204 205 /** Calls the C arg's callback function. **/ 206 void OnServerAuthorizationCheckDoneCallback(); 207 208 private: 209 grpc_tls_server_authorization_check_arg* c_arg_; 210 }; 211 212 /** An interface that the application derives and uses to instantiate a 213 * TlsServerAuthorizationCheckConfig instance. Refer to the definition of the 214 * grpc_tls_server_authorization_check_config in grpc_tls_credentials_options.h 215 * for more details on the expectations of the member functions of the 216 * interface. 217 * **/ 218 struct TlsServerAuthorizationCheckInterface { 219 virtual ~TlsServerAuthorizationCheckInterface() = default; 220 /** A callback that invokes the server authorization check. **/ 221 virtual int Schedule(TlsServerAuthorizationCheckArg* arg) = 0; 222 /** A callback that cancels a server authorization check request. **/ CancelTlsServerAuthorizationCheckInterface223 virtual void Cancel(TlsServerAuthorizationCheckArg* /* arg */) {} 224 }; 225 226 /** TLS server authorization check config, wraps 227 * grps_tls_server_authorization_check_config. It is used for experimental 228 * purposes for now and it is subject to change. **/ 229 class TlsServerAuthorizationCheckConfig { 230 public: 231 TlsServerAuthorizationCheckConfig( 232 std::shared_ptr<TlsServerAuthorizationCheckInterface> 233 server_authorization_check_interface); 234 ~TlsServerAuthorizationCheckConfig(); 235 Schedule(TlsServerAuthorizationCheckArg * arg)236 int Schedule(TlsServerAuthorizationCheckArg* arg) const { 237 if (server_authorization_check_interface_ == nullptr) { 238 gpr_log(GPR_ERROR, "server authorization check interface is nullptr"); 239 if (arg != nullptr) { 240 arg->set_status(GRPC_STATUS_NOT_FOUND); 241 arg->set_error_details( 242 "the interface of the server authorization check config is " 243 "nullptr"); 244 } 245 return 1; 246 } 247 return server_authorization_check_interface_->Schedule(arg); 248 } 249 Cancel(TlsServerAuthorizationCheckArg * arg)250 void Cancel(TlsServerAuthorizationCheckArg* arg) const { 251 if (server_authorization_check_interface_ == nullptr) { 252 gpr_log(GPR_ERROR, "server authorization check interface is nullptr"); 253 if (arg != nullptr) { 254 arg->set_status(GRPC_STATUS_NOT_FOUND); 255 arg->set_error_details( 256 "the interface of the server authorization check config is " 257 "nullptr"); 258 } 259 return; 260 } 261 server_authorization_check_interface_->Cancel(arg); 262 } 263 264 /** Returns C struct for the server authorization check config. **/ c_config()265 grpc_tls_server_authorization_check_config* c_config() const { 266 return c_config_; 267 } 268 269 private: 270 grpc_tls_server_authorization_check_config* c_config_; 271 std::shared_ptr<TlsServerAuthorizationCheckInterface> 272 server_authorization_check_interface_; 273 }; 274 275 /** TLS credentials options, wrapper for grpc_tls_credentials_options. It is 276 * used for experimental purposes for now and it is subject to change. See the 277 * description of the grpc_tls_credentials_options struct in grpc_security.h for 278 * more details. **/ 279 class TlsCredentialsOptions { 280 public: 281 // Constructor for client. 282 explicit TlsCredentialsOptions( 283 grpc_tls_server_verification_option server_verification_option, 284 std::shared_ptr<TlsKeyMaterialsConfig> key_materials_config, 285 std::shared_ptr<TlsCredentialReloadConfig> credential_reload_config, 286 std::shared_ptr<TlsServerAuthorizationCheckConfig> 287 server_authorization_check_config); 288 289 // Constructor for server. 290 explicit TlsCredentialsOptions( 291 grpc_ssl_client_certificate_request_type cert_request_type, 292 std::shared_ptr<TlsKeyMaterialsConfig> key_materials_config, 293 std::shared_ptr<TlsCredentialReloadConfig> credential_reload_config); 294 295 // This constructor will be deprecated. 296 TlsCredentialsOptions( 297 grpc_ssl_client_certificate_request_type cert_request_type, 298 grpc_tls_server_verification_option server_verification_option, 299 std::shared_ptr<TlsKeyMaterialsConfig> key_materials_config, 300 std::shared_ptr<TlsCredentialReloadConfig> credential_reload_config, 301 std::shared_ptr<TlsServerAuthorizationCheckConfig> 302 server_authorization_check_config); 303 ~TlsCredentialsOptions(); 304 305 /** Getters for member fields. **/ cert_request_type()306 grpc_ssl_client_certificate_request_type cert_request_type() const { 307 return cert_request_type_; 308 } server_verification_option()309 grpc_tls_server_verification_option server_verification_option() const { 310 return server_verification_option_; 311 } key_materials_config()312 std::shared_ptr<TlsKeyMaterialsConfig> key_materials_config() const { 313 return key_materials_config_; 314 } credential_reload_config()315 std::shared_ptr<TlsCredentialReloadConfig> credential_reload_config() const { 316 return credential_reload_config_; 317 } 318 std::shared_ptr<TlsServerAuthorizationCheckConfig> server_authorization_check_config()319 server_authorization_check_config() const { 320 return server_authorization_check_config_; 321 } c_credentials_options()322 grpc_tls_credentials_options* c_credentials_options() const { 323 return c_credentials_options_; 324 } 325 326 private: 327 /** The cert_request_type_ flag is only relevant when the 328 * TlsCredentialsOptions are used to instantiate server credentials; the flag 329 * goes unused when creating channel credentials, and the user can set it to 330 * GRPC_SSL_DONT_REQUEST_CLIENT_CERTIFICATE. **/ 331 grpc_ssl_client_certificate_request_type cert_request_type_; 332 /** The server_verification_option_ flag is only relevant when the 333 * TlsCredentialsOptions are used to instantiate client credentials; **/ 334 grpc_tls_server_verification_option server_verification_option_; 335 std::shared_ptr<TlsKeyMaterialsConfig> key_materials_config_; 336 std::shared_ptr<TlsCredentialReloadConfig> credential_reload_config_; 337 std::shared_ptr<TlsServerAuthorizationCheckConfig> 338 server_authorization_check_config_; 339 grpc_tls_credentials_options* c_credentials_options_; 340 }; 341 342 } // namespace experimental 343 } // namespace grpc_impl 344 345 #endif // GRPCPP_SECURITY_TLS_CREDENTIALS_OPTIONS_H 346