GRPC Core  0.10.0.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
security_connector.h
Go to the documentation of this file.
1 /*
2  *
3  * Copyright 2015, Google Inc.
4  * All rights reserved.
5  *
6  * Redistribution and use in source and binary forms, with or without
7  * modification, are permitted provided that the following conditions are
8  * met:
9  *
10  * * Redistributions of source code must retain the above copyright
11  * notice, this list of conditions and the following disclaimer.
12  * * Redistributions in binary form must reproduce the above
13  * copyright notice, this list of conditions and the following disclaimer
14  * in the documentation and/or other materials provided with the
15  * distribution.
16  * * Neither the name of Google Inc. nor the names of its
17  * contributors may be used to endorse or promote products derived from
18  * this software without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  *
32  */
33 
34 #ifndef GRPC_INTERNAL_CORE_SECURITY_SECURITY_CONNECTOR_H
35 #define GRPC_INTERNAL_CORE_SECURITY_SECURITY_CONNECTOR_H
36 
37 #include <grpc/grpc_security.h>
40 
41 /* --- status enum. --- */
42 
43 typedef enum {
48 
49 /* --- URL schemes. --- */
50 
51 #define GRPC_SSL_URL_SCHEME "https"
52 #define GRPC_FAKE_SECURITY_URL_SCHEME "http+fake_security"
53 
54 /* --- security_connector object. ---
55 
56  A security connector object represents away to configure the underlying
57  transport security mechanism and check the resulting trusted peer. */
58 
60 
61 #define GRPC_SECURITY_CONNECTOR_ARG "grpc.security_connector"
62 
63 typedef void (*grpc_security_check_cb)(void *user_data,
64  grpc_security_status status);
65 
66 typedef struct {
67  void (*destroy)(grpc_security_connector *sc);
69  tsi_handshaker **handshaker);
72  void *user_data);
74 
79  const char *url_scheme;
80  grpc_auth_context *auth_context; /* Populated after the peer is checked. */
81 };
82 
83 /* Refcounting. */
84 #ifdef GRPC_SECURITY_CONNECTOR_REFCOUNT_DEBUG
85 #define GRPC_SECURITY_CONNECTOR_REF(p, r) \
86  grpc_security_connector_ref((p), __FILE__, __LINE__, (r))
87 #define GRPC_SECURITY_CONNECTOR_UNREF(p, r) \
88  grpc_security_connector_unref((p), __FILE__, __LINE__, (r))
90  grpc_security_connector *policy, const char *file, int line,
91  const char *reason);
93  const char *file, int line,
94  const char *reason);
95 #else
96 #define GRPC_SECURITY_CONNECTOR_REF(p, r) grpc_security_connector_ref((p))
97 #define GRPC_SECURITY_CONNECTOR_UNREF(p, r) grpc_security_connector_unref((p))
99  grpc_security_connector *policy);
101 #endif
102 
103 /* Handshake creation. */
105  grpc_security_connector *sc, tsi_handshaker **handshaker);
106 
107 /* Check the peer.
108  Implementations can choose to check the peer either synchronously or
109  asynchronously. In the first case, a successful call will return
110  GRPC_SECURITY_OK. In the asynchronous case, the call will return
111  GRPC_SECURITY_PENDING unless an error is detected early on.
112  Ownership of the peer is transfered.
113 */
116  void *user_data);
117 
118 /* Util to encapsulate the connector in a channel arg. */
120 
121 /* Util to get the connector from a channel arg. */
123 
124 /* Util to find the connector from channel args. */
126  const grpc_channel_args *args);
127 
128 /* --- channel_security_connector object. ---
129 
130  A channel security connector object represents away to configure the
131  underlying transport security mechanism on the client side. */
132 
134 
136  grpc_security_connector base; /* requires is_client_side to be non 0. */
139  const char *host,
141  void *user_data);
142 };
143 
144 /* Checks that the host that will be set for a call is acceptable.
145  Implementations can choose do the check either synchronously or
146  asynchronously. In the first case, a successful call will return
147  GRPC_SECURITY_OK. In the asynchronous case, the call will return
148  GRPC_SECURITY_PENDING unless an error is detected early on. */
150  grpc_channel_security_connector *sc, const char *host,
151  grpc_security_check_cb cb, void *user_data);
152 
153 /* --- Creation security connectors. --- */
154 
155 /* For TESTING ONLY!
156  Creates a fake connector that emulates real channel security. */
158  grpc_credentials *request_metadata_creds, int call_host_check_is_async);
159 
160 /* For TESTING ONLY!
161  Creates a fake connector that emulates real server security. */
163 
164 /* Config for ssl clients. */
165 typedef struct {
166  unsigned char *pem_private_key;
168  unsigned char *pem_cert_chain;
170  unsigned char *pem_root_certs;
173 
174 /* Creates an SSL channel_security_connector.
175  - request_metadata_creds is the credentials object which metadata
176  will be sent with each request. This parameter can be NULL.
177  - config is the SSL config to be used for the SSL channel establishment.
178  - is_client should be 0 for a server or a non-0 value for a client.
179  - secure_peer_name is the secure peer name that should be checked in
180  grpc_channel_security_connector_check_peer. This parameter may be NULL in
181  which case the peer name will not be checked. Note that if this parameter
182  is not NULL, then, pem_root_certs should not be NULL either.
183  - sc is a pointer on the connector to be created.
184  This function returns GRPC_SECURITY_OK in case of success or a
185  specific error code otherwise.
186 */
188  grpc_credentials *request_metadata_creds, const grpc_ssl_config *config,
189  const char *target_name, const char *overridden_target_name,
191 
192 /* Gets the default ssl roots. */
193 size_t grpc_get_default_ssl_roots(const unsigned char **pem_root_certs);
194 
195 /* Config for ssl servers. */
196 typedef struct {
197  unsigned char **pem_private_keys;
199  unsigned char **pem_cert_chains;
202  unsigned char *pem_root_certs;
206 
207 /* Creates an SSL server_security_connector.
208  - config is the SSL config to be used for the SSL channel establishment.
209  - sc is a pointer on the connector to be created.
210  This function returns GRPC_SECURITY_OK in case of success or a
211  specific error code otherwise.
212 */
214  const grpc_ssl_server_config *config, grpc_security_connector **sc);
215 
216 /* Util. */
218  const char *name);
219 
220 /* Exposed for testing only. */
222 
223 #endif /* GRPC_INTERNAL_CORE_SECURITY_SECURITY_CONNECTOR_H */
Definition: security_context.h:49
Definition: security_connector.h:66
grpc_channel_security_connector * grpc_fake_channel_security_connector_create(grpc_credentials *request_metadata_creds, int call_host_check_is_async)
Definition: security_connector.c:295
int is_client_side
Definition: security_connector.h:78
unsigned char * pem_cert_chain
Definition: security_connector.h:168
size_t pem_private_key_size
Definition: security_connector.h:167
unsigned char * pem_private_key
Definition: security_connector.h:166
Definition: sync_generic.h:49
void(* grpc_security_check_cb)(void *user_data, grpc_security_status status)
Definition: security_connector.h:63
grpc_security_status grpc_ssl_server_security_connector_create(const grpc_ssl_server_config *config, grpc_security_connector **sc)
Definition: security_connector.c:623
An array of arguments that can be passed around.
Definition: grpc.h:113
gpr_refcount refcount
Definition: security_connector.h:77
grpc_security_connector base
Definition: security_connector.h:136
const char * url_scheme
Definition: security_connector.h:79
grpc_security_connector * grpc_security_connector_ref(grpc_security_connector *policy)
Definition: security_connector.c:136
const tsi_peer_property * tsi_peer_get_property_by_name(const tsi_peer *peer, const char *name)
Definition: security_connector.c:87
unsigned char ** pem_cert_chains
Definition: security_connector.h:199
grpc_security_status grpc_channel_security_connector_check_call_host(grpc_channel_security_connector *sc, const char *host, grpc_security_check_cb cb, void *user_data)
Definition: security_connector.c:120
size_t * pem_private_keys_sizes
Definition: security_connector.h:198
size_t * pem_cert_chains_sizes
Definition: security_connector.h:200
A single argument...
Definition: grpc.h:91
Definition: cmdline.c:47
grpc_security_status grpc_ssl_channel_security_connector_create(grpc_credentials *request_metadata_creds, const grpc_ssl_config *config, const char *target_name, const char *overridden_target_name, grpc_channel_security_connector **sc)
Definition: security_connector.c:544
unsigned char ** pem_private_keys
Definition: security_connector.h:197
void grpc_security_connector_unref(grpc_security_connector *policy)
Definition: security_connector.c:153
Definition: credentials.h:145
Definition: security_connector.h:46
Definition: transport_security_interface.h:192
grpc_credentials * request_metadata_creds
Definition: security_connector.h:137
size_t grpc_get_default_ssl_roots(const unsigned char **pem_root_certs)
Definition: security_connector.c:535
size_t pem_root_certs_size
Definition: security_connector.h:171
grpc_security_connector * grpc_security_connector_from_arg(const grpc_arg *arg)
Definition: security_connector.c:177
Definition: security_connector.h:196
grpc_arg grpc_security_connector_to_arg(grpc_security_connector *sc)
Definition: security_connector.c:167
Definition: security_connector.h:75
const grpc_security_connector_vtable * vtable
Definition: security_connector.h:76
Definition: security_connector.h:135
unsigned char * pem_root_certs
Definition: security_connector.h:170
grpc_security_status(* check_call_host)(grpc_channel_security_connector *sc, const char *host, grpc_security_check_cb cb, void *user_data)
Definition: security_connector.h:138
int force_client_auth
Definition: security_connector.h:204
Definition: security_connector.h:45
grpc_security_status grpc_security_connector_create_handshaker(grpc_security_connector *sc, tsi_handshaker **handshaker)
Definition: security_connector.c:104
Definition: security_connector.h:165
unsigned char * pem_root_certs
Definition: security_connector.h:202
grpc_security_status grpc_security_connector_check_peer(grpc_security_connector *sc, tsi_peer peer, grpc_security_check_cb cb, void *user_data)
Definition: security_connector.c:110
grpc_auth_context * tsi_ssl_peer_to_auth_context(const tsi_peer *peer)
Definition: security_connector.c:409
Definition: transport_security.h:86
size_t pem_root_certs_size
Definition: security_connector.h:203
grpc_auth_context * auth_context
Definition: security_connector.h:80
grpc_security_connector * grpc_fake_server_security_connector_create(void)
Definition: security_connector.c:311
grpc_security_status
Definition: security_connector.h:43
size_t num_key_cert_pairs
Definition: security_connector.h:201
size_t pem_cert_chain_size
Definition: security_connector.h:169
Definition: security_connector.h:44
Definition: transport_security_interface.h:184
grpc_security_connector * grpc_find_security_connector_in_args(const grpc_channel_args *args)
Definition: security_connector.c:187