1 /* 2 * 3 * Copyright 2015 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 GRPC_CORE_LIB_SECURITY_SECURITY_CONNECTOR_SECURITY_CONNECTOR_H 20 #define GRPC_CORE_LIB_SECURITY_SECURITY_CONNECTOR_SECURITY_CONNECTOR_H 21 22 #include <grpc/support/port_platform.h> 23 24 #include <stdbool.h> 25 26 #include <grpc/grpc_security.h> 27 28 #include "src/core/lib/channel/handshaker.h" 29 #include "src/core/lib/iomgr/endpoint.h" 30 #include "src/core/lib/iomgr/tcp_server.h" 31 #include "src/core/tsi/ssl_transport_security.h" 32 #include "src/core/tsi/transport_security_interface.h" 33 34 extern grpc_core::DebugOnlyTraceFlag grpc_trace_security_connector_refcount; 35 36 /* --- status enum. --- */ 37 38 typedef enum { GRPC_SECURITY_OK = 0, GRPC_SECURITY_ERROR } grpc_security_status; 39 40 /* --- URL schemes. --- */ 41 42 #define GRPC_SSL_URL_SCHEME "https" 43 #define GRPC_FAKE_SECURITY_URL_SCHEME "http+fake_security" 44 45 /* --- security_connector object. --- 46 47 A security connector object represents away to configure the underlying 48 transport security mechanism and check the resulting trusted peer. */ 49 50 typedef struct grpc_security_connector grpc_security_connector; 51 52 #define GRPC_ARG_SECURITY_CONNECTOR "grpc.security_connector" 53 54 typedef struct { 55 void (*destroy)(grpc_security_connector* sc); 56 void (*check_peer)(grpc_security_connector* sc, tsi_peer peer, 57 grpc_auth_context** auth_context, 58 grpc_closure* on_peer_checked); 59 int (*cmp)(grpc_security_connector* sc, grpc_security_connector* other); 60 } grpc_security_connector_vtable; 61 62 struct grpc_security_connector { 63 const grpc_security_connector_vtable* vtable; 64 gpr_refcount refcount; 65 const char* url_scheme; 66 }; 67 68 /* Refcounting. */ 69 #ifndef NDEBUG 70 #define GRPC_SECURITY_CONNECTOR_REF(p, r) \ 71 grpc_security_connector_ref((p), __FILE__, __LINE__, (r)) 72 #define GRPC_SECURITY_CONNECTOR_UNREF(p, r) \ 73 grpc_security_connector_unref((p), __FILE__, __LINE__, (r)) 74 grpc_security_connector* grpc_security_connector_ref( 75 grpc_security_connector* policy, const char* file, int line, 76 const char* reason); 77 void grpc_security_connector_unref(grpc_security_connector* policy, 78 const char* file, int line, 79 const char* reason); 80 #else 81 #define GRPC_SECURITY_CONNECTOR_REF(p, r) grpc_security_connector_ref((p)) 82 #define GRPC_SECURITY_CONNECTOR_UNREF(p, r) grpc_security_connector_unref((p)) 83 grpc_security_connector* grpc_security_connector_ref( 84 grpc_security_connector* policy); 85 void grpc_security_connector_unref(grpc_security_connector* policy); 86 #endif 87 88 /* Check the peer. Callee takes ownership of the peer object. 89 When done, sets *auth_context and invokes on_peer_checked. */ 90 void grpc_security_connector_check_peer(grpc_security_connector* sc, 91 tsi_peer peer, 92 grpc_auth_context** auth_context, 93 grpc_closure* on_peer_checked); 94 95 /* Compares two security connectors. */ 96 int grpc_security_connector_cmp(grpc_security_connector* sc, 97 grpc_security_connector* other); 98 99 /* Util to encapsulate the connector in a channel arg. */ 100 grpc_arg grpc_security_connector_to_arg(grpc_security_connector* sc); 101 102 /* Util to get the connector from a channel arg. */ 103 grpc_security_connector* grpc_security_connector_from_arg(const grpc_arg* arg); 104 105 /* Util to find the connector from channel args. */ 106 grpc_security_connector* grpc_security_connector_find_in_args( 107 const grpc_channel_args* args); 108 109 /* --- channel_security_connector object. --- 110 111 A channel security connector object represents a way to configure the 112 underlying transport security mechanism on the client side. */ 113 114 typedef struct grpc_channel_security_connector grpc_channel_security_connector; 115 116 struct grpc_channel_security_connector { 117 grpc_security_connector base; 118 grpc_channel_credentials* channel_creds; 119 grpc_call_credentials* request_metadata_creds; 120 bool (*check_call_host)(grpc_channel_security_connector* sc, const char* host, 121 grpc_auth_context* auth_context, 122 grpc_closure* on_call_host_checked, 123 grpc_error** error); 124 void (*cancel_check_call_host)(grpc_channel_security_connector* sc, 125 grpc_closure* on_call_host_checked, 126 grpc_error* error); 127 void (*add_handshakers)(grpc_channel_security_connector* sc, 128 grpc_handshake_manager* handshake_mgr); 129 }; 130 131 /// A helper function for use in grpc_security_connector_cmp() implementations. 132 int grpc_channel_security_connector_cmp(grpc_channel_security_connector* sc1, 133 grpc_channel_security_connector* sc2); 134 135 /// Checks that the host that will be set for a call is acceptable. 136 /// Returns true if completed synchronously, in which case \a error will 137 /// be set to indicate the result. Otherwise, \a on_call_host_checked 138 /// will be invoked when complete. 139 bool grpc_channel_security_connector_check_call_host( 140 grpc_channel_security_connector* sc, const char* host, 141 grpc_auth_context* auth_context, grpc_closure* on_call_host_checked, 142 grpc_error** error); 143 144 /// Cancels a pending asychronous call to 145 /// grpc_channel_security_connector_check_call_host() with 146 /// \a on_call_host_checked as its callback. 147 void grpc_channel_security_connector_cancel_check_call_host( 148 grpc_channel_security_connector* sc, grpc_closure* on_call_host_checked, 149 grpc_error* error); 150 151 /* Registers handshakers with \a handshake_mgr. */ 152 void grpc_channel_security_connector_add_handshakers( 153 grpc_channel_security_connector* connector, 154 grpc_handshake_manager* handshake_mgr); 155 156 /* --- server_security_connector object. --- 157 158 A server security connector object represents a way to configure the 159 underlying transport security mechanism on the server side. */ 160 161 typedef struct grpc_server_security_connector grpc_server_security_connector; 162 163 struct grpc_server_security_connector { 164 grpc_security_connector base; 165 grpc_server_credentials* server_creds; 166 void (*add_handshakers)(grpc_server_security_connector* sc, 167 grpc_handshake_manager* handshake_mgr); 168 }; 169 170 /// A helper function for use in grpc_security_connector_cmp() implementations. 171 int grpc_server_security_connector_cmp(grpc_server_security_connector* sc1, 172 grpc_server_security_connector* sc2); 173 174 void grpc_server_security_connector_add_handshakers( 175 grpc_server_security_connector* sc, grpc_handshake_manager* handshake_mgr); 176 177 /* --- Creation security connectors. --- */ 178 179 /* For TESTING ONLY! 180 Creates a fake connector that emulates real channel security. */ 181 grpc_channel_security_connector* grpc_fake_channel_security_connector_create( 182 grpc_channel_credentials* channel_creds, 183 grpc_call_credentials* request_metadata_creds, const char* target, 184 const grpc_channel_args* args); 185 186 /* For TESTING ONLY! 187 Creates a fake connector that emulates real server security. */ 188 grpc_server_security_connector* grpc_fake_server_security_connector_create( 189 grpc_server_credentials* server_creds); 190 191 /* Config for ssl clients. */ 192 193 typedef struct { 194 tsi_ssl_pem_key_cert_pair* pem_key_cert_pair; 195 char* pem_root_certs; 196 verify_peer_options verify_options; 197 } grpc_ssl_config; 198 199 /* Creates an SSL channel_security_connector. 200 - request_metadata_creds is the credentials object which metadata 201 will be sent with each request. This parameter can be NULL. 202 - config is the SSL config to be used for the SSL channel establishment. 203 - is_client should be 0 for a server or a non-0 value for a client. 204 - secure_peer_name is the secure peer name that should be checked in 205 grpc_channel_security_connector_check_peer. This parameter may be NULL in 206 which case the peer name will not be checked. Note that if this parameter 207 is not NULL, then, pem_root_certs should not be NULL either. 208 - sc is a pointer on the connector to be created. 209 This function returns GRPC_SECURITY_OK in case of success or a 210 specific error code otherwise. 211 */ 212 grpc_security_status grpc_ssl_channel_security_connector_create( 213 grpc_channel_credentials* channel_creds, 214 grpc_call_credentials* request_metadata_creds, 215 const grpc_ssl_config* config, const char* target_name, 216 const char* overridden_target_name, 217 tsi_ssl_session_cache* ssl_session_cache, 218 grpc_channel_security_connector** sc); 219 220 /* Config for ssl servers. */ 221 typedef struct { 222 tsi_ssl_pem_key_cert_pair* pem_key_cert_pairs; 223 size_t num_key_cert_pairs; 224 char* pem_root_certs; 225 grpc_ssl_client_certificate_request_type client_certificate_request; 226 } grpc_ssl_server_config; 227 228 /* Creates an SSL server_security_connector. 229 - config is the SSL config to be used for the SSL channel establishment. 230 - sc is a pointer on the connector to be created. 231 This function returns GRPC_SECURITY_OK in case of success or a 232 specific error code otherwise. 233 */ 234 grpc_security_status grpc_ssl_server_security_connector_create( 235 grpc_server_credentials* server_credentials, 236 grpc_server_security_connector** sc); 237 238 /* Util. */ 239 const tsi_peer_property* tsi_peer_get_property_by_name(const tsi_peer* peer, 240 const char* name); 241 242 /* Exposed for testing only. */ 243 grpc_auth_context* grpc_ssl_peer_to_auth_context(const tsi_peer* peer); 244 tsi_peer grpc_shallow_peer_from_ssl_auth_context( 245 const grpc_auth_context* auth_context); 246 void grpc_shallow_peer_destruct(tsi_peer* peer); 247 int grpc_ssl_host_matches_name(const tsi_peer* peer, const char* peer_name); 248 249 /* --- Default SSL Root Store. --- */ 250 namespace grpc_core { 251 252 // The class implements default SSL root store. 253 class DefaultSslRootStore { 254 public: 255 // Gets the default SSL root store. Returns nullptr if not found. 256 static const tsi_ssl_root_certs_store* GetRootStore(); 257 258 // Gets the default PEM root certificate. 259 static const char* GetPemRootCerts(); 260 261 protected: 262 // Returns default PEM root certificates in nullptr terminated grpc_slice. 263 // This function is protected instead of private, so that it can be tested. 264 static grpc_slice ComputePemRootCerts(); 265 266 private: 267 // Construct me not! 268 DefaultSslRootStore(); 269 270 // Initialization of default SSL root store. 271 static void InitRootStore(); 272 273 // One-time initialization of default SSL root store. 274 static void InitRootStoreOnce(); 275 276 // SSL root store in tsi_ssl_root_certs_store object. 277 static tsi_ssl_root_certs_store* default_root_store_; 278 279 // Default PEM root certificates. 280 static grpc_slice default_pem_root_certs_; 281 }; 282 283 } // namespace grpc_core 284 285 #endif /* GRPC_CORE_LIB_SECURITY_SECURITY_CONNECTOR_SECURITY_CONNECTOR_H */ 286