• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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