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
grpc_security.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_GRPC_SECURITY_H
35 #define GRPC_GRPC_SECURITY_H
36
37 #include <grpc/grpc.h>
38 #include <grpc/status.h>
39
40 #ifdef __cplusplus
41 extern "C" {
42 #endif
43
44 /* --- grpc_credentials object. ---
45
46 A credentials object represents a way to authenticate a client. */
47
48 typedef struct grpc_credentials grpc_credentials;
49
50 /* Releases a credentials object.
51 The creator of the credentials object is responsible for its release. */
52 void grpc_credentials_release(grpc_credentials *creds);
53
54 /* Environment variable that points to the google default application
55 credentials json key or refresh token. Used in the
56 grpc_google_default_credentials_create function. */
57 #define GRPC_GOOGLE_CREDENTIALS_ENV_VAR "GOOGLE_APPLICATION_CREDENTIALS"
58
59 /* Creates default credentials to connect to a google gRPC service.
60 WARNING: Do NOT use this credentials to connect to a non-google service as
61 this could result in an oauth2 token leak. */
62 grpc_credentials *grpc_google_default_credentials_create(void);
63
64 /* Environment variable that points to the default SSL roots file. This file
65 must be a PEM encoded file with all the roots such as the one that can be
66 downloaded from https://pki.google.com/roots.pem. */
67 #define GRPC_DEFAULT_SSL_ROOTS_FILE_PATH_ENV_VAR \
68 "GRPC_DEFAULT_SSL_ROOTS_FILE_PATH"
69
70 /* Object that holds a private key / certificate chain pair in PEM format. */
71 typedef struct {
72 /* private_key is the NULL-terminated string containing the PEM encoding of
73 the client's private key. */
74 const char *private_key;
75
76 /* cert_chain is the NULL-terminated string containing the PEM encoding of
77 the client's certificate chain. */
78 const char *cert_chain;
79 } grpc_ssl_pem_key_cert_pair;
80
81 /* Creates an SSL credentials object.
82 - pem_roots_cert is the NULL-terminated string containing the PEM encoding
83 of the server root certificates. If this parameter is NULL, the
84 implementation will first try to dereference the file pointed by the
85 GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment variable, and if that fails,
86 get the roots from a well-known place on disk (in the grpc install
87 directory).
88 - pem_key_cert_pair is a pointer on the object containing client's private
89 key and certificate chain. This parameter can be NULL if the client does
90 not have such a key/cert pair. */
91 grpc_credentials *grpc_ssl_credentials_create(
92 const char *pem_root_certs, grpc_ssl_pem_key_cert_pair *pem_key_cert_pair);
93
94 /* Creates a composite credentials object. */
95 grpc_credentials *grpc_composite_credentials_create(grpc_credentials *creds1,
96 grpc_credentials *creds2);
97
98 /* Creates a compute engine credentials object.
99 WARNING: Do NOT use this credentials to connect to a non-google service as
100 this could result in an oauth2 token leak. */
101 grpc_credentials *grpc_compute_engine_credentials_create(void);
102
103 extern const gpr_timespec grpc_max_auth_token_lifetime;
104
105 /* Creates a service account credentials object. May return NULL if the input is
106 invalid.
107 WARNING: Do NOT use this credentials to connect to a non-google service as
108 this could result in an oauth2 token leak.
109 - json_key is the JSON key string containing the client's private key.
110 - scope is a space-delimited list of the requested permissions.
111 - token_lifetime is the lifetime of each token acquired through this service
112 account credentials. It should not exceed grpc_max_auth_token_lifetime
113 or will be cropped to this value. */
114 grpc_credentials *grpc_service_account_credentials_create(
115 const char *json_key, const char *scope, gpr_timespec token_lifetime);
116
117 /* Creates a JWT credentials object. May return NULL if the input is invalid.
118 - json_key is the JSON key string containing the client's private key.
119 - token_lifetime is the lifetime of each Json Web Token (JWT) created with
120 this credentials. It should not exceed grpc_max_auth_token_lifetime or
121 will be cropped to this value. */
122 grpc_credentials *grpc_service_account_jwt_access_credentials_create(
123 const char *json_key, gpr_timespec token_lifetime);
124
125 /* Creates an Oauth2 Refresh Token credentials object. May return NULL if the
126 input is invalid.
127 WARNING: Do NOT use this credentials to connect to a non-google service as
128 this could result in an oauth2 token leak.
129 - json_refresh_token is the JSON string containing the refresh token itself
130 along with a client_id and client_secret. */
131 grpc_credentials *grpc_refresh_token_credentials_create(
132 const char *json_refresh_token);
133
134 /* Creates an Oauth2 Access Token credentials with an access token that was
135 aquired by an out of band mechanism. */
136 grpc_credentials *grpc_access_token_credentials_create(
137 const char *access_token);
138
139 /* Creates an IAM credentials object. */
140 grpc_credentials *grpc_iam_credentials_create(const char *authorization_token,
141 const char *authority_selector);
142
143 /* --- Secure channel creation. --- */
144
145 /* The caller of the secure_channel_create functions may override the target
146 name used for SSL host name checking using this channel argument which is of
147 type GRPC_ARG_STRING. This *should* be used for testing only.
148 If this argument is not specified, the name used for SSL host name checking
149 will be the target parameter (assuming that the secure channel is an SSL
150 channel). If this parameter is specified and the underlying is not an SSL
151 channel, it will just be ignored. */
152 #define GRPC_SSL_TARGET_NAME_OVERRIDE_ARG "grpc.ssl_target_name_override"
153
154 /* Creates a secure channel using the passed-in credentials. */
155 grpc_channel *grpc_secure_channel_create(grpc_credentials *creds,
156 const char *target,
157 const grpc_channel_args *args);
158
159 /* --- grpc_server_credentials object. ---
160
161 A server credentials object represents a way to authenticate a server. */
162
163 typedef struct grpc_server_credentials grpc_server_credentials;
164
165 /* Releases a server_credentials object.
166 The creator of the server_credentials object is responsible for its release.
167 */
168 void grpc_server_credentials_release(grpc_server_credentials *creds);
169
170 /* Creates an SSL server_credentials object.
171 - pem_roots_cert is the NULL-terminated string containing the PEM encoding of
172 the client root certificates. This parameter may be NULL if the server does
173 not want the client to be authenticated with SSL.
174 - pem_key_cert_pairs is an array private key / certificate chains of the
175 server. This parameter cannot be NULL.
176 - num_key_cert_pairs indicates the number of items in the private_key_files
177 and cert_chain_files parameters. It should be at least 1.
178 - force_client_auth, if set to non-zero will force the client to authenticate
179 with an SSL cert. Note that this option is ignored if pem_root_certs is
180 NULL. */
181 grpc_server_credentials *grpc_ssl_server_credentials_create(
182 const char *pem_root_certs, grpc_ssl_pem_key_cert_pair *pem_key_cert_pairs,
183 size_t num_key_cert_pairs, int force_client_auth);
184
185 /* --- Server-side secure ports. --- */
186
187 /* Add a HTTP2 over an encrypted link over tcp listener.
188 Returns bound port number on success, 0 on failure.
189 REQUIRES: server not started */
190 int grpc_server_add_secure_http2_port(grpc_server *server, const char *addr,
191 grpc_server_credentials *creds);
192
193 /* --- Call specific credentials. --- */
194
195 /* Sets a credentials to a call. Can only be called on the client side before
196 grpc_call_start_batch. */
197 grpc_call_error grpc_call_set_credentials(grpc_call *call,
198 grpc_credentials *creds);
199
200 /* --- Authentication Context. --- */
201
202 /* TODO(jboeuf): Define some well-known property names. */
203
204 #define GRPC_TRANSPORT_SECURITY_TYPE_PROPERTY_NAME "transport_security_type"
205 #define GRPC_SSL_TRANSPORT_SECURITY_TYPE "ssl"
206
207 #define GRPC_X509_CN_PROPERTY_NAME "x509_common_name"
208 #define GRPC_X509_SAN_PROPERTY_NAME "x509_subject_alternative_name"
209
210 typedef struct grpc_auth_context grpc_auth_context;
211
212 typedef struct grpc_auth_property_iterator {
213 const grpc_auth_context *ctx;
214 size_t index;
215 const char *name;
216 } grpc_auth_property_iterator;
217
218 /* value, if not NULL, is guaranteed to be NULL terminated. */
219 typedef struct grpc_auth_property {
220 char *name;
221 char *value;
222 size_t value_length;
223 } grpc_auth_property;
224
225 /* Returns NULL when the iterator is at the end. */
226 const grpc_auth_property *grpc_auth_property_iterator_next(
227 grpc_auth_property_iterator *it);
228
229 /* Iterates over the auth context. */
230 grpc_auth_property_iterator grpc_auth_context_property_iterator(
231 const grpc_auth_context *ctx);
232
233 /* Gets the peer identity. Returns an empty iterator (first _next will return
234 NULL) if the peer is not authenticated. */
235 grpc_auth_property_iterator grpc_auth_context_peer_identity(
236 const grpc_auth_context *ctx);
237
238 /* Finds a property in the context. May return an empty iterator (first _next
239 will return NULL) if no property with this name was found in the context. */
240 grpc_auth_property_iterator grpc_auth_context_find_properties_by_name(
241 const grpc_auth_context *ctx, const char *name);
242
243 /* Gets the name of the property that indicates the peer identity. Will return
244 NULL if the peer is not authenticated. */
245 const char *grpc_auth_context_peer_identity_property_name(
246 const grpc_auth_context *ctx);
247
248 /* Returns 1 if the peer is authenticated, 0 otherwise. */
249 int grpc_auth_context_peer_is_authenticated(const grpc_auth_context *ctx);
250
251 /* Gets the auth context from the call. Caller needs to call
252 grpc_auth_context_release on the returned context. */
253 grpc_auth_context *grpc_call_auth_context(grpc_call *call);
254
255 /* Releases the auth context returned from grpc_call_auth_context. */
256 void grpc_auth_context_release(grpc_auth_context *context);
257
258 #ifdef __cplusplus
259 }
260 #endif
261
262 #endif /* GRPC_GRPC_SECURITY_H */
grpc_auth_context
Definition: security_context.h:49
grpc_server_add_secure_http2_port
int grpc_server_add_secure_http2_port(grpc_server *server, const char *addr, grpc_server_credentials *creds)
Definition: server_secure_chttp2.c:196
grpc_auth_property::value_length
size_t value_length
Definition: grpc_security.h:222
grpc_call_set_credentials
grpc_call_error grpc_call_set_credentials(grpc_call *call, grpc_credentials *creds)
Definition: security_context.c:47
grpc_secure_channel_create
grpc_channel * grpc_secure_channel_create(grpc_credentials *creds, const char *target, const grpc_channel_args *args)
Definition: secure_channel_create.c:185
grpc_credentials_release
void grpc_credentials_release(grpc_credentials *creds)
Definition: credentials.c:93
grpc_channel_args
An array of arguments that can be passed around.
Definition: grpc.h:113
grpc_channel
Definition: channel.c:61
grpc_auth_property::value
char * value
Definition: grpc_security.h:221
grpc_composite_credentials_create
grpc_credentials * grpc_composite_credentials_create(grpc_credentials *creds1, grpc_credentials *creds2)
Definition: credentials.c:1097
grpc_max_auth_token_lifetime
const gpr_timespec grpc_max_auth_token_lifetime
Definition: json_token.c:52
grpc_google_default_credentials_create
grpc_credentials * grpc_google_default_credentials_create(void)
Definition: google_default_credentials.c:164
grpc_ssl_pem_key_cert_pair::private_key
const char * private_key
Definition: grpc_security.h:74
grpc_auth_property_iterator_next
const grpc_auth_property * grpc_auth_property_iterator_next(grpc_auth_property_iterator *it)
Definition: security_context.c:193
grpc_auth_property::name
char * name
Definition: grpc_security.h:220
grpc_auth_property_iterator::ctx
const grpc_auth_context * ctx
Definition: grpc_security.h:213
grpc_auth_context_peer_identity_property_name
const char * grpc_auth_context_peer_identity_property_name(const grpc_auth_context *ctx)
Definition: security_context.c:175
grpc_auth_context_peer_is_authenticated
int grpc_auth_context_peer_is_authenticated(const grpc_auth_context *ctx)
Definition: security_context.c:180
grpc_ssl_credentials_create
grpc_credentials * grpc_ssl_credentials_create(const char *pem_root_certs, grpc_ssl_pem_key_cert_pair *pem_key_cert_pair)
Definition: credentials.c:294
grpc_server_credentials
Definition: credentials.h:216
grpc_credentials
Definition: credentials.h:145
grpc_auth_property_iterator::name
const char * name
Definition: grpc_security.h:215
grpc_call_error
grpc_call_error
Result of a grpc call.
Definition: grpc.h:156
grpc_auth_property_iterator::index
size_t index
Definition: grpc_security.h:214
grpc_access_token_credentials_create
grpc_credentials * grpc_access_token_credentials_create(const char *access_token)
Definition: credentials.c:864
grpc_iam_credentials_create
grpc_credentials * grpc_iam_credentials_create(const char *authorization_token, const char *authority_selector)
Definition: credentials.c:1205
grpc_auth_property_iterator
Definition: grpc_security.h:212
grpc_ssl_pem_key_cert_pair
Definition: grpc_security.h:71
grpc_auth_property_iterator
struct grpc_auth_property_iterator grpc_auth_property_iterator
grpc_refresh_token_credentials_create
grpc_credentials * grpc_refresh_token_credentials_create(const char *json_refresh_token)
Definition: credentials.c:762
grpc_ssl_pem_key_cert_pair::cert_chain
const char * cert_chain
Definition: grpc_security.h:78
grpc_service_account_credentials_create
grpc_credentials * grpc_service_account_credentials_create(const char *json_key, const char *scope, gpr_timespec token_lifetime)
Definition: credentials.c:689
grpc_auth_context_peer_identity
grpc_auth_property_iterator grpc_auth_context_peer_identity(const grpc_auth_context *ctx)
Definition: security_context.c:225
grpc_auth_property
Definition: grpc_security.h:219
grpc_compute_engine_credentials_create
grpc_credentials * grpc_compute_engine_credentials_create(void)
Definition: credentials.c:632
grpc_auth_property
struct grpc_auth_property grpc_auth_property
status.h
grpc_auth_context_property_iterator
grpc_auth_property_iterator grpc_auth_context_property_iterator(const grpc_auth_context *ctx)
Definition: security_context.c:185
grpc_service_account_jwt_access_credentials_create
grpc_credentials * grpc_service_account_jwt_access_credentials_create(const char *json_key, gpr_timespec token_lifetime)
Definition: credentials.c:426
grpc_call_auth_context
grpc_auth_context * grpc_call_auth_context(grpc_call *call)
Definition: security_context.c:72
gpr_timespec
Definition: time.h:60
grpc_server_credentials_release
void grpc_server_credentials_release(grpc_server_credentials *creds)
Definition: credentials.c:138
grpc_auth_context_find_properties_by_name
grpc_auth_property_iterator grpc_auth_context_find_properties_by_name(const grpc_auth_context *ctx, const char *name)
Definition: security_context.c:216
grpc_auth_context_release
void grpc_auth_context_release(grpc_auth_context *context)
Definition: security_context.c:84
grpc.h
grpc_call
Definition: call.c:143
grpc_ssl_server_credentials_create
grpc_server_credentials * grpc_ssl_server_credentials_create(const char *pem_root_certs, grpc_ssl_pem_key_cert_pair *pem_key_cert_pairs, size_t num_key_cert_pairs, int force_client_auth)
Definition: credentials.c:305
grpc_server
Definition: server.c:181