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 TlsServerAuthorizationCheckArg(grpc_tls_server_authorization_check_arg* arg); 58 ~TlsServerAuthorizationCheckArg(); 59 60 /** Getters for member fields. **/ 61 void* cb_user_data() const; 62 int success() const; 63 std::string target_name() const; 64 std::string peer_cert() const; 65 std::string peer_cert_full_chain() const; 66 grpc_status_code status() const; 67 std::string error_details() const; 68 69 /** Setters for member fields. **/ 70 void set_cb_user_data(void* cb_user_data); 71 void set_success(int success); 72 void set_target_name(const std::string& target_name); 73 void set_peer_cert(const std::string& peer_cert); 74 void set_peer_cert_full_chain(const std::string& peer_cert_full_chain); 75 void set_status(grpc_status_code status); 76 void set_error_details(const std::string& error_details); 77 78 /** Calls the C arg's callback function. **/ 79 void OnServerAuthorizationCheckDoneCallback(); 80 81 private: 82 grpc_tls_server_authorization_check_arg* c_arg_; 83 }; 84 85 /** An interface that the application derives and uses to instantiate a 86 * TlsServerAuthorizationCheckConfig instance. Refer to the definition of the 87 * grpc_tls_server_authorization_check_config in grpc_tls_credentials_options.h 88 * for more details on the expectations of the member functions of the 89 * interface. 90 * **/ 91 struct TlsServerAuthorizationCheckInterface { 92 virtual ~TlsServerAuthorizationCheckInterface() = default; 93 /** A callback that invokes the server authorization check. **/ 94 virtual int Schedule(TlsServerAuthorizationCheckArg* arg) = 0; 95 /** A callback that cancels a server authorization check request. **/ CancelTlsServerAuthorizationCheckInterface96 virtual void Cancel(TlsServerAuthorizationCheckArg* /* arg */) {} 97 }; 98 99 /** TLS server authorization check config, wraps 100 * grps_tls_server_authorization_check_config. It is used for experimental 101 * purposes for now and it is subject to change. **/ 102 class TlsServerAuthorizationCheckConfig { 103 public: 104 TlsServerAuthorizationCheckConfig( 105 std::shared_ptr<TlsServerAuthorizationCheckInterface> 106 server_authorization_check_interface); 107 ~TlsServerAuthorizationCheckConfig(); 108 Schedule(TlsServerAuthorizationCheckArg * arg)109 int Schedule(TlsServerAuthorizationCheckArg* arg) const { 110 if (server_authorization_check_interface_ == nullptr) { 111 gpr_log(GPR_ERROR, "server authorization check interface is nullptr"); 112 if (arg != nullptr) { 113 arg->set_status(GRPC_STATUS_NOT_FOUND); 114 arg->set_error_details( 115 "the interface of the server authorization check config is " 116 "nullptr"); 117 } 118 return 1; 119 } 120 return server_authorization_check_interface_->Schedule(arg); 121 } 122 Cancel(TlsServerAuthorizationCheckArg * arg)123 void Cancel(TlsServerAuthorizationCheckArg* arg) const { 124 if (server_authorization_check_interface_ == nullptr) { 125 gpr_log(GPR_ERROR, "server authorization check interface is nullptr"); 126 if (arg != nullptr) { 127 arg->set_status(GRPC_STATUS_NOT_FOUND); 128 arg->set_error_details( 129 "the interface of the server authorization check config is " 130 "nullptr"); 131 } 132 return; 133 } 134 server_authorization_check_interface_->Cancel(arg); 135 } 136 137 /** Returns C struct for the server authorization check config. **/ c_config()138 grpc_tls_server_authorization_check_config* c_config() const { 139 return c_config_; 140 } 141 142 private: 143 grpc_tls_server_authorization_check_config* c_config_; 144 std::shared_ptr<TlsServerAuthorizationCheckInterface> 145 server_authorization_check_interface_; 146 }; 147 148 // Base class of configurable options specified by users to configure their 149 // certain security features supported in TLS. It is used for experimental 150 // purposes for now and it is subject to change. 151 class TlsCredentialsOptions { 152 public: 153 // Constructor for base class TlsCredentialsOptions. 154 // 155 // @param certificate_provider the provider which fetches TLS credentials that 156 // will be used in the TLS handshake 157 explicit TlsCredentialsOptions( 158 std::shared_ptr<CertificateProviderInterface> certificate_provider); 159 // ---- Setters for member fields ---- 160 // Watches the updates of root certificates with name |root_cert_name|. 161 // If used in TLS credentials, it should always be set unless the root 162 // certificates are not needed(e.g. in the one-side TLS scenario, the server 163 // is not required to verify the client). 164 void watch_root_certs(); 165 // Sets the name of root certificates being watched, if |watch_root_certs| is 166 // called. If not set, an empty string will be used as the name. 167 // 168 // @param root_cert_name the name of root certs being set. 169 void set_root_cert_name(const std::string& root_cert_name); 170 // Watches the updates of identity key-cert pairs with name 171 // |identity_cert_name|. If used in TLS credentials, it should always be set 172 // unless the identity certificates are not needed(e.g. in the one-side TLS 173 // scenario, the client is not required to provide certs). 174 void watch_identity_key_cert_pairs(); 175 // Sets the name of identity key-cert pairs being watched, if 176 // |watch_identity_key_cert_pairs| is called. If not set, an empty string will 177 // be used as the name. 178 // 179 // @param identity_cert_name the name of identity key-cert pairs being set. 180 void set_identity_cert_name(const std::string& identity_cert_name); 181 182 // ----- Getters for member fields ---- 183 // Get the internal c options. This function shall be used only internally. c_credentials_options()184 grpc_tls_credentials_options* c_credentials_options() const { 185 return c_credentials_options_; 186 } 187 188 private: 189 std::shared_ptr<CertificateProviderInterface> certificate_provider_; 190 grpc_tls_credentials_options* c_credentials_options_ = nullptr; 191 }; 192 193 // Contains configurable options on the client side. 194 // It is used for experimental purposes for now and it is subject to change. 195 class TlsChannelCredentialsOptions final : public TlsCredentialsOptions { 196 public: TlsChannelCredentialsOptions(std::shared_ptr<CertificateProviderInterface> certificate_provider)197 explicit TlsChannelCredentialsOptions( 198 std::shared_ptr<CertificateProviderInterface> certificate_provider) 199 : TlsCredentialsOptions(std::move(certificate_provider)) {} 200 201 // Sets the option to verify the server. 202 // The default is GRPC_TLS_SERVER_VERIFICATION. 203 void set_server_verification_option( 204 grpc_tls_server_verification_option server_verification_option); 205 // Sets the custom authorization config. 206 void set_server_authorization_check_config( 207 std::shared_ptr<TlsServerAuthorizationCheckConfig> 208 authorization_check_config); 209 210 private: 211 }; 212 213 // Contains configurable options on the server side. 214 // It is used for experimental purposes for now and it is subject to change. 215 class TlsServerCredentialsOptions final : public TlsCredentialsOptions { 216 public: TlsServerCredentialsOptions(std::shared_ptr<CertificateProviderInterface> certificate_provider)217 explicit TlsServerCredentialsOptions( 218 std::shared_ptr<CertificateProviderInterface> certificate_provider) 219 : TlsCredentialsOptions(std::move(certificate_provider)) {} 220 221 // Sets option to request the certificates from the client. 222 // The default is GRPC_SSL_DONT_REQUEST_CLIENT_CERTIFICATE. 223 void set_cert_request_type( 224 grpc_ssl_client_certificate_request_type cert_request_type); 225 226 private: 227 }; 228 229 } // namespace experimental 230 } // namespace grpc 231 232 #endif // GRPCPP_SECURITY_TLS_CREDENTIALS_OPTIONS_H 233