GRPC Core 0.10.0.0

- Main Page
- Data Structures
- Files

- File List
- Globals

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>
38 #include "src/core/iomgr/endpoint.h"
39 #include "src/core/tsi/transport_security_interface.h"
40
41 /* --- status enum. --- */
42
43 typedef enum {
44 GRPC_SECURITY_OK = 0,
45 GRPC_SECURITY_PENDING,
46 GRPC_SECURITY_ERROR
47 } grpc_security_status;
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
59 typedef struct grpc_security_connector grpc_security_connector;
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);
68 grpc_security_status (*create_handshaker)(grpc_security_connector *sc,
69 tsi_handshaker **handshaker);
70 grpc_security_status (*check_peer)(grpc_security_connector *sc, tsi_peer peer,
71 grpc_security_check_cb cb,
72 void *user_data);
73 } grpc_security_connector_vtable;
74
75 struct grpc_security_connector {
76 const grpc_security_connector_vtable *vtable;
77 gpr_refcount refcount;
78 int is_client_side;
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))
89 grpc_security_connector *grpc_security_connector_ref(
90 grpc_security_connector *policy, const char *file, int line,
91 const char *reason);
92 void grpc_security_connector_unref(grpc_security_connector *policy,
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))
98 grpc_security_connector *grpc_security_connector_ref(
99 grpc_security_connector *policy);
100 void grpc_security_connector_unref(grpc_security_connector *policy);
101 #endif
102
103 /* Handshake creation. */
104 grpc_security_status grpc_security_connector_create_handshaker(
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 */
114 grpc_security_status grpc_security_connector_check_peer(
115 grpc_security_connector *sc, tsi_peer peer, grpc_security_check_cb cb,
116 void *user_data);
117
118 /* Util to encapsulate the connector in a channel arg. */
119 grpc_arg grpc_security_connector_to_arg(grpc_security_connector *sc);
120
121 /* Util to get the connector from a channel arg. */
122 grpc_security_connector *grpc_security_connector_from_arg(const grpc_arg *arg);
123
124 /* Util to find the connector from channel args. */
125 grpc_security_connector *grpc_find_security_connector_in_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
133 typedef struct grpc_channel_security_connector grpc_channel_security_connector;
134
135 struct grpc_channel_security_connector {
136 grpc_security_connector base; /* requires is_client_side to be non 0. */
137 grpc_credentials *request_metadata_creds;
138 grpc_security_status (*check_call_host)(grpc_channel_security_connector *sc,
139 const char *host,
140 grpc_security_check_cb cb,
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. */
149 grpc_security_status grpc_channel_security_connector_check_call_host(
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. */
157 grpc_channel_security_connector *grpc_fake_channel_security_connector_create(
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. */
162 grpc_security_connector *grpc_fake_server_security_connector_create(void);
163
164 /* Config for ssl clients. */
165 typedef struct {
166 unsigned char *pem_private_key;
167 size_t pem_private_key_size;
168 unsigned char *pem_cert_chain;
169 size_t pem_cert_chain_size;
170 unsigned char *pem_root_certs;
171 size_t pem_root_certs_size;
172 } grpc_ssl_config;
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 */
187 grpc_security_status grpc_ssl_channel_security_connector_create(
188 grpc_credentials *request_metadata_creds, const grpc_ssl_config *config,
189 const char *target_name, const char *overridden_target_name,
190 grpc_channel_security_connector **sc);
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;
198 size_t *pem_private_keys_sizes;
199 unsigned char **pem_cert_chains;
200 size_t *pem_cert_chains_sizes;
201 size_t num_key_cert_pairs;
202 unsigned char *pem_root_certs;
203 size_t pem_root_certs_size;
204 int force_client_auth;
205 } grpc_ssl_server_config;
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 */
213 grpc_security_status grpc_ssl_server_security_connector_create(
214 const grpc_ssl_server_config *config, grpc_security_connector **sc);
215
216 /* Util. */
217 const tsi_peer_property *tsi_peer_get_property_by_name(const tsi_peer *peer,
218 const char *name);
219
220 /* Exposed for testing only. */
221 grpc_auth_context *tsi_ssl_peer_to_auth_context(const tsi_peer *peer);
222
223 #endif /* GRPC_INTERNAL_CORE_SECURITY_SECURITY_CONNECTOR_H */
grpc_auth_context
Definition: security_context.h:49
grpc_security_connector_vtable
Definition: security_connector.h:66
grpc_fake_channel_security_connector_create
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
grpc_security_connector::is_client_side
int is_client_side
Definition: security_connector.h:78
grpc_ssl_config::pem_cert_chain
unsigned char * pem_cert_chain
Definition: security_connector.h:168
grpc_ssl_config::pem_private_key_size
size_t pem_private_key_size
Definition: security_connector.h:167
grpc_ssl_config::pem_private_key
unsigned char * pem_private_key
Definition: security_connector.h:166
gpr_refcount
Definition: sync_generic.h:49
grpc_security_check_cb
void(* grpc_security_check_cb)(void *user_data, grpc_security_status status)
Definition: security_connector.h:63
grpc_ssl_server_security_connector_create
grpc_security_status grpc_ssl_server_security_connector_create(const grpc_ssl_server_config *config, grpc_security_connector **sc)
Definition: security_connector.c:623
grpc_channel_args
An array of arguments that can be passed around.
Definition: grpc.h:113
grpc_security_connector::refcount
gpr_refcount refcount
Definition: security_connector.h:77
grpc_channel_security_connector::base
grpc_security_connector base
Definition: security_connector.h:136
grpc_security_connector::url_scheme
const char * url_scheme
Definition: security_connector.h:79
grpc_security_connector_ref
grpc_security_connector * grpc_security_connector_ref(grpc_security_connector *policy)
Definition: security_connector.c:136
tsi_peer_get_property_by_name
const tsi_peer_property * tsi_peer_get_property_by_name(const tsi_peer *peer, const char *name)
Definition: security_connector.c:87
grpc_ssl_server_config::pem_cert_chains
unsigned char ** pem_cert_chains
Definition: security_connector.h:199
transport_security_interface.h
grpc_channel_security_connector_check_call_host
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
grpc_ssl_server_config::pem_private_keys_sizes
size_t * pem_private_keys_sizes
Definition: security_connector.h:198
grpc_ssl_server_config::pem_cert_chains_sizes
size_t * pem_cert_chains_sizes
Definition: security_connector.h:200
grpc_arg
A single argument...
Definition: grpc.h:91
arg
Definition: cmdline.c:47
grpc_ssl_channel_security_connector_create
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
grpc_security.h
grpc_ssl_server_config::pem_private_keys
unsigned char ** pem_private_keys
Definition: security_connector.h:197
grpc_security_connector_unref
void grpc_security_connector_unref(grpc_security_connector *policy)
Definition: security_connector.c:153
grpc_credentials
Definition: credentials.h:145
GRPC_SECURITY_ERROR
Definition: security_connector.h:46
tsi_peer
Definition: transport_security_interface.h:192
grpc_channel_security_connector::request_metadata_creds
grpc_credentials * request_metadata_creds
Definition: security_connector.h:137
grpc_get_default_ssl_roots
size_t grpc_get_default_ssl_roots(const unsigned char **pem_root_certs)
Definition: security_connector.c:535
grpc_ssl_config::pem_root_certs_size
size_t pem_root_certs_size
Definition: security_connector.h:171
grpc_security_connector_from_arg
grpc_security_connector * grpc_security_connector_from_arg(const grpc_arg *arg)
Definition: security_connector.c:177
grpc_ssl_server_config
Definition: security_connector.h:196
grpc_security_connector_to_arg
grpc_arg grpc_security_connector_to_arg(grpc_security_connector *sc)
Definition: security_connector.c:167
grpc_security_connector
Definition: security_connector.h:75
grpc_security_connector::vtable
const grpc_security_connector_vtable * vtable
Definition: security_connector.h:76
grpc_channel_security_connector
Definition: security_connector.h:135
grpc_ssl_config::pem_root_certs
unsigned char * pem_root_certs
Definition: security_connector.h:170
grpc_channel_security_connector::check_call_host
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
grpc_ssl_server_config::force_client_auth
int force_client_auth
Definition: security_connector.h:204
GRPC_SECURITY_PENDING
Definition: security_connector.h:45
grpc_security_connector_create_handshaker
grpc_security_status grpc_security_connector_create_handshaker(grpc_security_connector *sc, tsi_handshaker **handshaker)
Definition: security_connector.c:104
grpc_ssl_config
Definition: security_connector.h:165
grpc_ssl_server_config::pem_root_certs
unsigned char * pem_root_certs
Definition: security_connector.h:202
grpc_security_connector_check_peer
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
endpoint.h
tsi_ssl_peer_to_auth_context
grpc_auth_context * tsi_ssl_peer_to_auth_context(const tsi_peer *peer)
Definition: security_connector.c:409
tsi_handshaker
Definition: transport_security.h:86
grpc_ssl_server_config::pem_root_certs_size
size_t pem_root_certs_size
Definition: security_connector.h:203
grpc_security_connector::auth_context
grpc_auth_context * auth_context
Definition: security_connector.h:80
grpc_fake_server_security_connector_create
grpc_security_connector * grpc_fake_server_security_connector_create(void)
Definition: security_connector.c:311
grpc_security_status
grpc_security_status
Definition: security_connector.h:43
grpc_ssl_server_config::num_key_cert_pairs
size_t num_key_cert_pairs
Definition: security_connector.h:201
grpc_ssl_config::pem_cert_chain_size
size_t pem_cert_chain_size
Definition: security_connector.h:169
GRPC_SECURITY_OK
Definition: security_connector.h:44
tsi_peer_property
Definition: transport_security_interface.h:184
grpc_find_security_connector_in_args
grpc_security_connector * grpc_find_security_connector_in_args(const grpc_channel_args *args)
Definition: security_connector.c:187