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 explicit TlsCredentialsOptions( 159 std::shared_ptr<CertificateProviderInterface> certificate_provider); 160 // ---- Setters for member fields ---- 161 // Watches the updates of root certificates with name |root_cert_name|. 162 // If used in TLS credentials, it should always be set unless the root 163 // certificates are not needed(e.g. in the one-side TLS scenario, the server 164 // is not required to verify the client). 165 void watch_root_certs(); 166 // Sets the name of root certificates being watched, if |watch_root_certs| is 167 // called. If not set, an empty string will be used as the name. 168 // 169 // @param root_cert_name the name of root certs being set. 170 void set_root_cert_name(const std::string& root_cert_name); 171 // Watches the updates of identity key-cert pairs with name 172 // |identity_cert_name|. If used in TLS credentials, it should always be set 173 // unless the identity certificates are not needed(e.g. in the one-side TLS 174 // scenario, the client is not required to provide certs). 175 void watch_identity_key_cert_pairs(); 176 // Sets the name of identity key-cert pairs being watched, if 177 // |watch_identity_key_cert_pairs| is called. If not set, an empty string will 178 // be used as the name. 179 // 180 // @param identity_cert_name the name of identity key-cert pairs being set. 181 void set_identity_cert_name(const std::string& identity_cert_name); 182 183 // ----- Getters for member fields ---- 184 // Get the internal c options. This function shall be used only internally. c_credentials_options()185 grpc_tls_credentials_options* c_credentials_options() const { 186 return c_credentials_options_; 187 } 188 189 private: 190 std::shared_ptr<CertificateProviderInterface> certificate_provider_; 191 grpc_tls_credentials_options* c_credentials_options_ = nullptr; 192 }; 193 194 // Contains configurable options on the client side. 195 // It is used for experimental purposes for now and it is subject to change. 196 class TlsChannelCredentialsOptions final : public TlsCredentialsOptions { 197 public: TlsChannelCredentialsOptions(std::shared_ptr<CertificateProviderInterface> certificate_provider)198 explicit TlsChannelCredentialsOptions( 199 std::shared_ptr<CertificateProviderInterface> certificate_provider) 200 : TlsCredentialsOptions(std::move(certificate_provider)) {} 201 202 // Sets the option to verify the server. 203 // The default is GRPC_TLS_SERVER_VERIFICATION. 204 void set_server_verification_option( 205 grpc_tls_server_verification_option server_verification_option); 206 // Sets the custom authorization config. 207 void set_server_authorization_check_config( 208 std::shared_ptr<TlsServerAuthorizationCheckConfig> 209 authorization_check_config); 210 211 private: 212 }; 213 214 // Contains configurable options on the server side. 215 // It is used for experimental purposes for now and it is subject to change. 216 class TlsServerCredentialsOptions final : public TlsCredentialsOptions { 217 public: TlsServerCredentialsOptions(std::shared_ptr<CertificateProviderInterface> certificate_provider)218 explicit TlsServerCredentialsOptions( 219 std::shared_ptr<CertificateProviderInterface> certificate_provider) 220 : TlsCredentialsOptions(std::move(certificate_provider)) {} 221 222 // Sets option to request the certificates from the client. 223 // The default is GRPC_SSL_DONT_REQUEST_CLIENT_CERTIFICATE. 224 void set_cert_request_type( 225 grpc_ssl_client_certificate_request_type cert_request_type); 226 227 private: 228 }; 229 230 } // namespace experimental 231 } // namespace grpc 232 233 #endif // GRPCPP_SECURITY_TLS_CREDENTIALS_OPTIONS_H 234