GRPC Core  0.11.0.0
 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 
49 
50 /* Releases a credentials object.
51  The creator of the credentials object is responsible for its release. */
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. */
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;
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. */
92  const char *pem_root_certs, grpc_ssl_pem_key_cert_pair *pem_key_cert_pair,
93  void *reserved);
94 
95 /* Creates a composite credentials object. */
97  grpc_credentials *creds2,
98  void *reserved);
99 
100 /* Creates a compute engine credentials object for connecting to Google.
101  WARNING: Do NOT use this credentials to connect to a non-google service as
102  this could result in an oauth2 token leak. */
104 
106 
107 /* Creates a JWT credentials object. May return NULL if the input is invalid.
108  - json_key is the JSON key string containing the client's private key.
109  - token_lifetime is the lifetime of each Json Web Token (JWT) created with
110  this credentials. It should not exceed grpc_max_auth_token_lifetime or
111  will be cropped to this value. */
113  const char *json_key, gpr_timespec token_lifetime, void *reserved);
114 
115 /* Creates an Oauth2 Refresh Token credentials object for connecting to Google.
116  May return NULL if the input is invalid.
117  WARNING: Do NOT use this credentials to connect to a non-google service as
118  this could result in an oauth2 token leak.
119  - json_refresh_token is the JSON string containing the refresh token itself
120  along with a client_id and client_secret. */
122  const char *json_refresh_token, void *reserved);
123 
124 /* Creates an Oauth2 Access Token credentials with an access token that was
125  aquired by an out of band mechanism. */
127  const char *access_token, void *reserved);
128 
129 /* Creates an IAM credentials object for connecting to Google. */
131  const char *authorization_token, const char *authority_selector,
132  void *reserved);
133 
134 /* --- Secure channel creation. --- */
135 
136 /* Creates a secure channel using the passed-in credentials. */
138  const char *target,
139  const grpc_channel_args *args,
140  void *reserved);
141 
142 /* --- grpc_server_credentials object. ---
143 
144  A server credentials object represents a way to authenticate a server. */
145 
147 
148 /* Releases a server_credentials object.
149  The creator of the server_credentials object is responsible for its release.
150  */
152 
153 /* Creates an SSL server_credentials object.
154  - pem_roots_cert is the NULL-terminated string containing the PEM encoding of
155  the client root certificates. This parameter may be NULL if the server does
156  not want the client to be authenticated with SSL.
157  - pem_key_cert_pairs is an array private key / certificate chains of the
158  server. This parameter cannot be NULL.
159  - num_key_cert_pairs indicates the number of items in the private_key_files
160  and cert_chain_files parameters. It should be at least 1.
161  - force_client_auth, if set to non-zero will force the client to authenticate
162  with an SSL cert. Note that this option is ignored if pem_root_certs is
163  NULL. */
165  const char *pem_root_certs, grpc_ssl_pem_key_cert_pair *pem_key_cert_pairs,
166  size_t num_key_cert_pairs, int force_client_auth, void *reserved);
167 
168 /* --- Server-side secure ports. --- */
169 
170 /* Add a HTTP2 over an encrypted link over tcp listener.
171  Returns bound port number on success, 0 on failure.
172  REQUIRES: server not started */
173 int grpc_server_add_secure_http2_port(grpc_server *server, const char *addr,
174  grpc_server_credentials *creds);
175 
176 /* --- Call specific credentials. --- */
177 
178 /* Sets a credentials to a call. Can only be called on the client side before
179  grpc_call_start_batch. */
181  grpc_credentials *creds);
182 
183 /* --- Authentication Context. --- */
184 
185 #define GRPC_TRANSPORT_SECURITY_TYPE_PROPERTY_NAME "transport_security_type"
186 #define GRPC_SSL_TRANSPORT_SECURITY_TYPE "ssl"
187 
188 #define GRPC_X509_CN_PROPERTY_NAME "x509_common_name"
189 #define GRPC_X509_SAN_PROPERTY_NAME "x509_subject_alternative_name"
190 
192 
195  size_t index;
196  const char *name;
198 
199 /* value, if not NULL, is guaranteed to be NULL terminated. */
200 typedef struct grpc_auth_property {
201  char *name;
202  char *value;
203  size_t value_length;
205 
206 /* Returns NULL when the iterator is at the end. */
209 
210 /* Iterates over the auth context. */
212  const grpc_auth_context *ctx);
213 
214 /* Gets the peer identity. Returns an empty iterator (first _next will return
215  NULL) if the peer is not authenticated. */
217  const grpc_auth_context *ctx);
218 
219 /* Finds a property in the context. May return an empty iterator (first _next
220  will return NULL) if no property with this name was found in the context. */
222  const grpc_auth_context *ctx, const char *name);
223 
224 /* Gets the name of the property that indicates the peer identity. Will return
225  NULL if the peer is not authenticated. */
227  const grpc_auth_context *ctx);
228 
229 /* Returns 1 if the peer is authenticated, 0 otherwise. */
231 
232 /* Gets the auth context from the call. Caller needs to call
233  grpc_auth_context_release on the returned context. */
235 
236 /* Releases the auth context returned from grpc_call_auth_context. */
238 
239 /* --
240  The following auth context methods should only be called by a server metadata
241  processor to set properties extracted from auth metadata.
242  -- */
243 
244 /* Add a property. */
245 void grpc_auth_context_add_property(grpc_auth_context *ctx, const char *name,
246  const char *value, size_t value_length);
247 
248 /* Add a C string property. */
250  const char *name,
251  const char *value);
252 
253 /* Sets the property name. Returns 1 if successful or 0 in case of failure
254  (which means that no property with this name exists). */
256  const char *name);
257 
258 /* --- Auth Metadata Processing --- */
259 
260 /* Callback function that is called when the metadata processing is done.
261  - Consumed metadata will be removed from the set of metadata available on the
262  call. consumed_md may be NULL if no metadata has been consumed.
263  - Response metadata will be set on the response. response_md may be NULL.
264  - status is GRPC_STATUS_OK for success or a specific status for an error.
265  Common error status for auth metadata processing is either
266  GRPC_STATUS_UNAUTHENTICATED in case of an authentication failure or
267  GRPC_STATUS PERMISSION_DENIED in case of an authorization failure.
268  - error_details gives details about the error. May be NULL. */
270  void *user_data, const grpc_metadata *consumed_md, size_t num_consumed_md,
271  const grpc_metadata *response_md, size_t num_response_md,
272  grpc_status_code status, const char *error_details);
273 
274 /* Pluggable server-side metadata processor object. */
275 typedef struct {
276  /* The context object is read/write: it contains the properties of the
277  channel peer and it is the job of the process function to augment it with
278  properties derived from the passed-in metadata.
279  The lifetime of these objects is guaranteed until cb is invoked. */
280  void (*process)(void *state, grpc_auth_context *context,
281  const grpc_metadata *md, size_t num_md,
282  grpc_process_auth_metadata_done_cb cb, void *user_data);
283  void (*destroy)(void *state);
284  void *state;
286 
289 
290 #ifdef __cplusplus
291 }
292 #endif
293 
294 #endif /* GRPC_GRPC_SECURITY_H */
int grpc_auth_context_set_peer_identity_property_name(grpc_auth_context *ctx, const char *name)
Definition: security_context.c:180
Definition: security_context.h:52
const char * value
Definition: hpack_table.c:44
void(* grpc_process_auth_metadata_done_cb)(void *user_data, const grpc_metadata *consumed_md, size_t num_consumed_md, const grpc_metadata *response_md, size_t num_response_md, grpc_status_code status, const char *error_details)
Definition: grpc_security.h:269
grpc_credentials * grpc_google_refresh_token_credentials_create(const char *json_refresh_token, void *reserved)
Definition: credentials.c:726
int grpc_server_add_secure_http2_port(grpc_server *server, const char *addr, grpc_server_credentials *creds)
Definition: server_secure_chttp2.c:204
size_t value_length
Definition: grpc_security.h:203
grpc_call_error grpc_call_set_credentials(grpc_call *call, grpc_credentials *creds)
Definition: security_context.c:47
void grpc_credentials_release(grpc_credentials *creds)
Definition: credentials.c:96
An array of arguments that can be passed around.
Definition: grpc.h:111
Definition: channel.c:62
char * value
Definition: grpc_security.h:202
const gpr_timespec grpc_max_auth_token_lifetime
Definition: json_token.c:52
void grpc_server_credentials_set_auth_metadata_processor(grpc_server_credentials *creds, grpc_auth_metadata_processor processor)
Definition: credentials.c:172
grpc_credentials * grpc_google_default_credentials_create(void)
Definition: google_default_credentials.c:168
grpc_credentials * grpc_composite_credentials_create(grpc_credentials *creds1, grpc_credentials *creds2, void *reserved)
Definition: credentials.c:1061
void grpc_auth_context_add_property(grpc_auth_context *ctx, const char *name, const char *value, size_t value_length)
Definition: security_context.c:255
const char * private_key
Definition: grpc_security.h:74
const grpc_auth_property * grpc_auth_property_iterator_next(grpc_auth_property_iterator *it)
Definition: security_context.c:206
void * state
Definition: grpc_security.h:284
grpc_credentials * grpc_service_account_jwt_access_credentials_create(const char *json_key, gpr_timespec token_lifetime, void *reserved)
Definition: credentials.c:456
char * name
Definition: grpc_security.h:201
grpc_credentials * grpc_ssl_credentials_create(const char *pem_root_certs, grpc_ssl_pem_key_cert_pair *pem_key_cert_pair, void *reserved)
Definition: credentials.c:321
const grpc_auth_context * ctx
Definition: grpc_security.h:194
const char * grpc_auth_context_peer_identity_property_name(const grpc_auth_context *ctx)
Definition: security_context.c:175
int grpc_auth_context_peer_is_authenticated(const grpc_auth_context *ctx)
Definition: security_context.c:194
Definition: credentials.h:220
Definition: credentials.h:145
const char * name
Definition: grpc_security.h:196
grpc_call_error
Result of a grpc call.
Definition: grpc.h:162
size_t index
Definition: grpc_security.h:195
Definition: grpc_security.h:193
void grpc_auth_context_add_cstring_property(grpc_auth_context *ctx, const char *name, const char *value)
Definition: security_context.c:267
Definition: grpc_security.h:71
A single metadata element.
Definition: grpc.h:207
struct grpc_auth_property_iterator grpc_auth_property_iterator
const char * cert_chain
Definition: grpc_security.h:78
grpc_auth_property_iterator grpc_auth_context_peer_identity(const grpc_auth_context *ctx)
Definition: security_context.c:238
Definition: grpc_security.h:275
Definition: grpc_security.h:200
grpc_credentials * grpc_access_token_credentials_create(const char *access_token, void *reserved)
Definition: credentials.c:827
struct grpc_auth_property grpc_auth_property
grpc_channel * grpc_secure_channel_create(grpc_credentials *creds, const char *target, const grpc_channel_args *args, void *reserved)
Definition: secure_channel_create.c:186
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, void *reserved)
Definition: credentials.c:334
grpc_credentials * grpc_google_compute_engine_credentials_create(void *reserved)
Definition: credentials.c:662
grpc_auth_property_iterator grpc_auth_context_property_iterator(const grpc_auth_context *ctx)
Definition: security_context.c:198
grpc_auth_context * grpc_call_auth_context(grpc_call *call)
Definition: security_context.c:72
Definition: time.h:63
grpc_status_code
Definition: status.h:41
void grpc_server_credentials_release(grpc_server_credentials *creds)
Definition: credentials.c:159
grpc_auth_property_iterator grpc_auth_context_find_properties_by_name(const grpc_auth_context *ctx, const char *name)
Definition: security_context.c:229
void grpc_auth_context_release(grpc_auth_context *context)
Definition: security_context.c:84
Definition: call.c:144
grpc_credentials * grpc_google_iam_credentials_create(const char *authorization_token, const char *authority_selector, void *reserved)
Definition: credentials.c:1170
Definition: server.c:181