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_GRPC_SECURITY_H
20#define GRPC_GRPC_SECURITY_H
21
22#include <grpc/support/port_platform.h>
23
24#include <grpc/grpc.h>
25#include <grpc/grpc_security_constants.h>
26#include <grpc/status.h>
27
28#ifdef __cplusplus
29extern "C" {
30#endif
31
32/** --- Authentication Context. --- */
33
34typedef struct grpc_auth_context grpc_auth_context;
35
36typedef struct grpc_auth_property_iterator {
37 const grpc_auth_context* ctx;
38 size_t index;
39 const char* name;
40} grpc_auth_property_iterator;
41
42/** value, if not NULL, is guaranteed to be NULL terminated. */
43typedef struct grpc_auth_property {
44 char* name;
45 char* value;
46 size_t value_length;
47} grpc_auth_property;
48
49/** Returns NULL when the iterator is at the end. */
50GRPCAPI const grpc_auth_property* grpc_auth_property_iterator_next(
51 grpc_auth_property_iterator* it);
52
53/** Iterates over the auth context. */
54GRPCAPI grpc_auth_property_iterator
55grpc_auth_context_property_iterator(const grpc_auth_context* ctx);
56
57/** Gets the peer identity. Returns an empty iterator (first _next will return
58 NULL) if the peer is not authenticated. */
59GRPCAPI grpc_auth_property_iterator
60grpc_auth_context_peer_identity(const grpc_auth_context* ctx);
61
62/** Finds a property in the context. May return an empty iterator (first _next
63 will return NULL) if no property with this name was found in the context. */
64GRPCAPI grpc_auth_property_iterator grpc_auth_context_find_properties_by_name(
65 const grpc_auth_context* ctx, const char* name);
66
67/** Gets the name of the property that indicates the peer identity. Will return
68 NULL if the peer is not authenticated. */
69GRPCAPI const char* grpc_auth_context_peer_identity_property_name(
70 const grpc_auth_context* ctx);
71
72/** Returns 1 if the peer is authenticated, 0 otherwise. */
73GRPCAPI int grpc_auth_context_peer_is_authenticated(
74 const grpc_auth_context* ctx);
75
76/** Gets the auth context from the call. Caller needs to call
77 grpc_auth_context_release on the returned context. */
78GRPCAPI grpc_auth_context* grpc_call_auth_context(grpc_call* call);
79
80/** Releases the auth context returned from grpc_call_auth_context. */
81GRPCAPI void grpc_auth_context_release(grpc_auth_context* context);
82
83/** --
84 The following auth context methods should only be called by a server metadata
85 processor to set properties extracted from auth metadata.
86 -- */
87
88/** Add a property. */
89GRPCAPI void grpc_auth_context_add_property(grpc_auth_context* ctx,
90 const char* name, const char* value,
91 size_t value_length);
92
93/** Add a C string property. */
94GRPCAPI void grpc_auth_context_add_cstring_property(grpc_auth_context* ctx,
95 const char* name,
96 const char* value);
97
98/** Sets the property name. Returns 1 if successful or 0 in case of failure
99 (which means that no property with this name exists). */
100GRPCAPI int grpc_auth_context_set_peer_identity_property_name(
101 grpc_auth_context* ctx, const char* name);
102
103/** --- SSL Session Cache. ---
104
105 A SSL session cache object represents a way to cache client sessions
106 between connections. Only ticket-based resumption is supported. */
107
108typedef struct grpc_ssl_session_cache grpc_ssl_session_cache;
109
110/** Create LRU cache for client-side SSL sessions with the given capacity.
111 If capacity is < 1, a default capacity is used instead. */
112GRPCAPI grpc_ssl_session_cache* grpc_ssl_session_cache_create_lru(
113 size_t capacity);
114
115/** Destroy SSL session cache. */
116GRPCAPI void grpc_ssl_session_cache_destroy(grpc_ssl_session_cache* cache);
117
118/** Create a channel arg with the given cache object. */
119GRPCAPI grpc_arg
120grpc_ssl_session_cache_create_channel_arg(grpc_ssl_session_cache* cache);
121
122/** --- grpc_channel_credentials object. ---
123
124 A channel credentials object represents a way to authenticate a client on a
125 channel. */
126
127typedef struct grpc_channel_credentials grpc_channel_credentials;
128
129/** Releases a channel credentials object.
130 The creator of the credentials object is responsible for its release. */
131GRPCAPI void grpc_channel_credentials_release(grpc_channel_credentials* creds);
132
133/** Creates default credentials to connect to a google gRPC service.
134 WARNING: Do NOT use this credentials to connect to a non-google service as
135 this could result in an oauth2 token leak. The security level of the
136 resulting connection is GRPC_PRIVACY_AND_INTEGRITY. */
137GRPCAPI grpc_channel_credentials* grpc_google_default_credentials_create(void);
138
139/** Callback for getting the SSL roots override from the application.
140 In case of success, *pem_roots_certs must be set to a NULL terminated string
141 containing the list of PEM encoded root certificates. The ownership is passed
142 to the core and freed (laster by the core) with gpr_free.
143 If this function fails and GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment is
144 set to a valid path, it will override the roots specified this func */
145typedef grpc_ssl_roots_override_result (*grpc_ssl_roots_override_callback)(
146 char** pem_root_certs);
147
148/** Setup a callback to override the default TLS/SSL roots.
149 This function is not thread-safe and must be called at initialization time
150 before any ssl credentials are created to have the desired side effect.
151 If GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment is set to a valid path, the
152 callback will not be called. */
153GRPCAPI void grpc_set_ssl_roots_override_callback(
154 grpc_ssl_roots_override_callback cb);
155
156/** Object that holds a private key / certificate chain pair in PEM format. */
157typedef struct {
158 /** private_key is the NULL-terminated string containing the PEM encoding of
159 the client's private key. */
160 const char* private_key;
161
162 /** cert_chain is the NULL-terminated string containing the PEM encoding of
163 the client's certificate chain. */
164 const char* cert_chain;
165} grpc_ssl_pem_key_cert_pair;
166
167/** Deprecated in favor of grpc_ssl_verify_peer_options. It will be removed
168 after all of its call sites are migrated to grpc_ssl_verify_peer_options.
169 Object that holds additional peer-verification options on a secure
170 channel. */
171typedef struct {
172 /** If non-NULL this callback will be invoked with the expected
173 target_name, the peer's certificate (in PEM format), and whatever
174 userdata pointer is set below. If a non-zero value is returned by this
175 callback then it is treated as a verification failure. Invocation of
176 the callback is blocking, so any implementation should be light-weight.
177 */
178 int (*verify_peer_callback)(const char* target_name, const char* peer_pem,
179 void* userdata);
180 /** Arbitrary userdata that will be passed as the last argument to
181 verify_peer_callback. */
182 void* verify_peer_callback_userdata;
183 /** A destruct callback that will be invoked when the channel is being
184 cleaned up. The userdata argument will be passed to it. The intent is
185 to perform any cleanup associated with that userdata. */
186 void (*verify_peer_destruct)(void* userdata);
187} verify_peer_options;
188
189/** Object that holds additional peer-verification options on a secure
190 channel. */
191typedef struct {
192 /** If non-NULL this callback will be invoked with the expected
193 target_name, the peer's certificate (in PEM format), and whatever
194 userdata pointer is set below. If a non-zero value is returned by this
195 callback then it is treated as a verification failure. Invocation of
196 the callback is blocking, so any implementation should be light-weight.
197 */
198 int (*verify_peer_callback)(const char* target_name, const char* peer_pem,
199 void* userdata);
200 /** Arbitrary userdata that will be passed as the last argument to
201 verify_peer_callback. */
202 void* verify_peer_callback_userdata;
203 /** A destruct callback that will be invoked when the channel is being
204 cleaned up. The userdata argument will be passed to it. The intent is
205 to perform any cleanup associated with that userdata. */
206 void (*verify_peer_destruct)(void* userdata);
207} grpc_ssl_verify_peer_options;
208
209/** Deprecated in favor of grpc_ssl_server_credentials_create_ex. It will be
210 removed after all of its call sites are migrated to
211 grpc_ssl_server_credentials_create_ex. Creates an SSL credentials object.
212 The security level of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY.
213 - pem_root_certs is the NULL-terminated string containing the PEM encoding
214 of the server root certificates. If this parameter is NULL, the
215 implementation will first try to dereference the file pointed by the
216 GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment variable, and if that fails,
217 try to get the roots set by grpc_override_ssl_default_roots. Eventually,
218 if all these fail, it will try to get the roots from a well-known place on
219 disk (in the grpc install directory).
220
221 gRPC has implemented root cache if the underlying OpenSSL library supports
222 it. The gRPC root certificates cache is only applicable on the default
223 root certificates, which is used when this parameter is nullptr. If user
224 provides their own pem_root_certs, when creating an SSL credential object,
225 gRPC would not be able to cache it, and each subchannel will generate a
226 copy of the root store. So it is recommended to avoid providing large room
227 pem with pem_root_certs parameter to avoid excessive memory consumption,
228 particularly on mobile platforms such as iOS.
229 - pem_key_cert_pair is a pointer on the object containing client's private
230 key and certificate chain. This parameter can be NULL if the client does
231 not have such a key/cert pair.
232 - verify_options is an optional verify_peer_options object which holds
233 additional options controlling how peer certificates are verified. For
234 example, you can supply a callback which receives the peer's certificate
235 with which you can do additional verification. Can be NULL, in which
236 case verification will retain default behavior. Any settings in
237 verify_options are copied during this call, so the verify_options
238 object can be released afterwards. */
239GRPCAPI grpc_channel_credentials* grpc_ssl_credentials_create(
240 const char* pem_root_certs, grpc_ssl_pem_key_cert_pair* pem_key_cert_pair,
241 const verify_peer_options* verify_options, void* reserved);
242
243/* Creates an SSL credentials object.
244 The security level of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY.
245 - pem_root_certs is the NULL-terminated string containing the PEM encoding
246 of the server root certificates. If this parameter is NULL, the
247 implementation will first try to dereference the file pointed by the
248 GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment variable, and if that fails,
249 try to get the roots set by grpc_override_ssl_default_roots. Eventually,
250 if all these fail, it will try to get the roots from a well-known place on
251 disk (in the grpc install directory).
252
253 gRPC has implemented root cache if the underlying OpenSSL library supports
254 it. The gRPC root certificates cache is only applicable on the default
255 root certificates, which is used when this parameter is nullptr. If user
256 provides their own pem_root_certs, when creating an SSL credential object,
257 gRPC would not be able to cache it, and each subchannel will generate a
258 copy of the root store. So it is recommended to avoid providing large room
259 pem with pem_root_certs parameter to avoid excessive memory consumption,
260 particularly on mobile platforms such as iOS.
261 - pem_key_cert_pair is a pointer on the object containing client's private
262 key and certificate chain. This parameter can be NULL if the client does
263 not have such a key/cert pair.
264 - verify_options is an optional verify_peer_options object which holds
265 additional options controlling how peer certificates are verified. For
266 example, you can supply a callback which receives the peer's certificate
267 with which you can do additional verification. Can be NULL, in which
268 case verification will retain default behavior. Any settings in
269 verify_options are copied during this call, so the verify_options
270 object can be released afterwards. */
271GRPCAPI grpc_channel_credentials* grpc_ssl_credentials_create_ex(
272 const char* pem_root_certs, grpc_ssl_pem_key_cert_pair* pem_key_cert_pair,
273 const grpc_ssl_verify_peer_options* verify_options, void* reserved);
274
275/** --- grpc_call_credentials object.
276
277 A call credentials object represents a way to authenticate on a particular
278 call. These credentials can be composed with a channel credentials object
279 so that they are sent with every call on this channel. */
280
281typedef struct grpc_call_credentials grpc_call_credentials;
282
283/** Releases a call credentials object.
284 The creator of the credentials object is responsible for its release. */
285GRPCAPI void grpc_call_credentials_release(grpc_call_credentials* creds);
286
287/** Creates a composite channel credentials object. The security level of
288 * resulting connection is determined by channel_creds. */
289GRPCAPI grpc_channel_credentials* grpc_composite_channel_credentials_create(
290 grpc_channel_credentials* channel_creds, grpc_call_credentials* call_creds,
291 void* reserved);
292
293/** Creates a composite call credentials object. */
294GRPCAPI grpc_call_credentials* grpc_composite_call_credentials_create(
295 grpc_call_credentials* creds1, grpc_call_credentials* creds2,
296 void* reserved);
297
298/** Creates a compute engine credentials object for connecting to Google.
299 WARNING: Do NOT use this credentials to connect to a non-google service as
300 this could result in an oauth2 token leak. */
301GRPCAPI grpc_call_credentials* grpc_google_compute_engine_credentials_create(
302 void* reserved);
303
304GRPCAPI gpr_timespec grpc_max_auth_token_lifetime(void);
305
306/** Creates a JWT credentials object. May return NULL if the input is invalid.
307 - json_key is the JSON key string containing the client's private key.
308 - token_lifetime is the lifetime of each Json Web Token (JWT) created with
309 this credentials. It should not exceed grpc_max_auth_token_lifetime or
310 will be cropped to this value. */
311GRPCAPI grpc_call_credentials*
312grpc_service_account_jwt_access_credentials_create(const char* json_key,
313 gpr_timespec token_lifetime,
314 void* reserved);
315
316/** Creates an Oauth2 Refresh Token credentials object for connecting to Google.
317 May return NULL if the input is invalid.
318 WARNING: Do NOT use this credentials to connect to a non-google service as
319 this could result in an oauth2 token leak.
320 - json_refresh_token is the JSON string containing the refresh token itself
321 along with a client_id and client_secret. */
322GRPCAPI grpc_call_credentials* grpc_google_refresh_token_credentials_create(
323 const char* json_refresh_token, void* reserved);
324
325/** Creates an Oauth2 Access Token credentials with an access token that was
326 acquired by an out of band mechanism. */
327GRPCAPI grpc_call_credentials* grpc_access_token_credentials_create(
328 const char* access_token, void* reserved);
329
330/** Creates an IAM credentials object for connecting to Google. */
331GRPCAPI grpc_call_credentials* grpc_google_iam_credentials_create(
332 const char* authorization_token, const char* authority_selector,
333 void* reserved);
334
335/** Options for creating STS Oauth Token Exchange credentials following the IETF
336 draft https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16.
337 Optional fields may be set to NULL or empty string. It is the responsibility
338 of the caller to ensure that the subject and actor tokens are refreshed on
339 disk at the specified paths. This API is used for experimental purposes for
340 now and may change in the future. */
341typedef struct {
342 const char* token_exchange_service_uri; /* Required. */
343 const char* resource; /* Optional. */
344 const char* audience; /* Optional. */
345 const char* scope; /* Optional. */
346 const char* requested_token_type; /* Optional. */
347 const char* subject_token_path; /* Required. */
348 const char* subject_token_type; /* Required. */
349 const char* actor_token_path; /* Optional. */
350 const char* actor_token_type; /* Optional. */
351} grpc_sts_credentials_options;
352
353/** Creates an STS credentials following the STS Token Exchanged specifed in the
354 IETF draft https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16.
355 This API is used for experimental purposes for now and may change in the
356 future. */
357GRPCAPI grpc_call_credentials* grpc_sts_credentials_create(
358 const grpc_sts_credentials_options* options, void* reserved);
359
360/** Callback function to be called by the metadata credentials plugin
361 implementation when the metadata is ready.
362 - user_data is the opaque pointer that was passed in the get_metadata method
363 of the grpc_metadata_credentials_plugin (see below).
364 - creds_md is an array of credentials metadata produced by the plugin. It
365 may be set to NULL in case of an error.
366 - num_creds_md is the number of items in the creds_md array.
367 - status must be GRPC_STATUS_OK in case of success or another specific error
368 code otherwise.
369 - error_details contains details about the error if any. In case of success
370 it should be NULL and will be otherwise ignored. */
371typedef void (*grpc_credentials_plugin_metadata_cb)(
372 void* user_data, const grpc_metadata* creds_md, size_t num_creds_md,
373 grpc_status_code status, const char* error_details);
374
375/** Context that can be used by metadata credentials plugin in order to create
376 auth related metadata. */
377typedef struct {
378 /** The fully qualifed service url. */
379 const char* service_url;
380
381 /** The method name of the RPC being called (not fully qualified).
382 The fully qualified method name can be built from the service_url:
383 full_qualified_method_name = ctx->service_url + '/' + ctx->method_name. */
384 const char* method_name;
385
386 /** The auth_context of the channel which gives the server's identity. */
387 const grpc_auth_context* channel_auth_context;
388
389 /** Reserved for future use. */
390 void* reserved;
391} grpc_auth_metadata_context;
392
393/** Maximum number of metadata entries returnable by a credentials plugin via
394 a synchronous return. */
395#define GRPC_METADATA_CREDENTIALS_PLUGIN_SYNC_MAX 4
396
397/** grpc_metadata_credentials plugin is an API user provided structure used to
398 create grpc_credentials objects that can be set on a channel (composed) or
399 a call. See grpc_credentials_metadata_create_from_plugin below.
400 The grpc client stack will call the get_metadata method of the plugin for
401 every call in scope for the credentials created from it. */
402typedef struct {
403 /** The implementation of this method has to be non-blocking, but can
404 be performed synchronously or asynchronously.
405
406 If processing occurs synchronously, returns non-zero and populates
407 creds_md, num_creds_md, status, and error_details. In this case,
408 the caller takes ownership of the entries in creds_md and of
409 error_details. Note that if the plugin needs to return more than
410 GRPC_METADATA_CREDENTIALS_PLUGIN_SYNC_MAX entries in creds_md, it must
411 return asynchronously.
412
413 If processing occurs asynchronously, returns zero and invokes \a cb
414 when processing is completed. \a user_data will be passed as the
415 first parameter of the callback. NOTE: \a cb MUST be invoked in a
416 different thread, not from the thread in which \a get_metadata() is
417 invoked.
418
419 \a context is the information that can be used by the plugin to create
420 auth metadata. */
421 int (*get_metadata)(
422 void* state, grpc_auth_metadata_context context,
423 grpc_credentials_plugin_metadata_cb cb, void* user_data,
424 grpc_metadata creds_md[GRPC_METADATA_CREDENTIALS_PLUGIN_SYNC_MAX],
425 size_t* num_creds_md, grpc_status_code* status,
426 const char** error_details);
427
428 /** Destroys the plugin state. */
429 void (*destroy)(void* state);
430
431 /** State that will be set as the first parameter of the methods above. */
432 void* state;
433
434 /** Type of credentials that this plugin is implementing. */
435 const char* type;
436} grpc_metadata_credentials_plugin;
437
438/** Creates a credentials object from a plugin with a specified minimum security
439 * level. */
440GRPCAPI grpc_call_credentials* grpc_metadata_credentials_create_from_plugin(
441 grpc_metadata_credentials_plugin plugin,
442 grpc_security_level min_security_level, void* reserved);
443
444/** --- Secure channel creation. --- */
445
446/** Creates a secure channel using the passed-in credentials. Additional
447 channel level configuration MAY be provided by grpc_channel_args, though
448 the expectation is that most clients will want to simply pass NULL. The
449 user data in 'args' need only live through the invocation of this function.
450 However, if any args of the 'pointer' type are passed, then the referenced
451 vtable must be maintained by the caller until grpc_channel_destroy
452 terminates. See grpc_channel_args definition for more on this. */
453GRPCAPI grpc_channel* grpc_secure_channel_create(
454 grpc_channel_credentials* creds, const char* target,
455 const grpc_channel_args* args, void* reserved);
456
457/** --- grpc_server_credentials object. ---
458
459 A server credentials object represents a way to authenticate a server. */
460
461typedef struct grpc_server_credentials grpc_server_credentials;
462
463/** Releases a server_credentials object.
464 The creator of the server_credentials object is responsible for its release.
465 */
466GRPCAPI void grpc_server_credentials_release(grpc_server_credentials* creds);
467
468/** Server certificate config object holds the server's public certificates and
469 associated private keys, as well as any CA certificates needed for client
470 certificate validation (if applicable). Create using
471 grpc_ssl_server_certificate_config_create(). */
472typedef struct grpc_ssl_server_certificate_config
473 grpc_ssl_server_certificate_config;
474
475/** Creates a grpc_ssl_server_certificate_config object.
476 - pem_roots_cert is the NULL-terminated string containing the PEM encoding of
477 the client root certificates. This parameter may be NULL if the server does
478 not want the client to be authenticated with SSL.
479 - pem_key_cert_pairs is an array private key / certificate chains of the
480 server. This parameter cannot be NULL.
481 - num_key_cert_pairs indicates the number of items in the private_key_files
482 and cert_chain_files parameters. It must be at least 1.
483 - It is the caller's responsibility to free this object via
484 grpc_ssl_server_certificate_config_destroy(). */
485GRPCAPI grpc_ssl_server_certificate_config*
486grpc_ssl_server_certificate_config_create(
487 const char* pem_root_certs,
488 const grpc_ssl_pem_key_cert_pair* pem_key_cert_pairs,
489 size_t num_key_cert_pairs);
490
491/** Destroys a grpc_ssl_server_certificate_config object. */
492GRPCAPI void grpc_ssl_server_certificate_config_destroy(
493 grpc_ssl_server_certificate_config* config);
494
495/** Callback to retrieve updated SSL server certificates, private keys, and
496 trusted CAs (for client authentication).
497 - user_data parameter, if not NULL, contains opaque data to be used by the
498 callback.
499 - Use grpc_ssl_server_certificate_config_create to create the config.
500 - The caller assumes ownership of the config. */
501typedef grpc_ssl_certificate_config_reload_status (
502 *grpc_ssl_server_certificate_config_callback)(
503 void* user_data, grpc_ssl_server_certificate_config** config);
504
505/** Deprecated in favor of grpc_ssl_server_credentials_create_ex.
506 Creates an SSL server_credentials object.
507 - pem_roots_cert is the NULL-terminated string containing the PEM encoding of
508 the client root certificates. This parameter may be NULL if the server does
509 not want the client to be authenticated with SSL.
510 - pem_key_cert_pairs is an array private key / certificate chains of the
511 server. This parameter cannot be NULL.
512 - num_key_cert_pairs indicates the number of items in the private_key_files
513 and cert_chain_files parameters. It should be at least 1.
514 - force_client_auth, if set to non-zero will force the client to authenticate
515 with an SSL cert. Note that this option is ignored if pem_root_certs is
516 NULL. */
517GRPCAPI grpc_server_credentials* grpc_ssl_server_credentials_create(
518 const char* pem_root_certs, grpc_ssl_pem_key_cert_pair* pem_key_cert_pairs,
519 size_t num_key_cert_pairs, int force_client_auth, void* reserved);
520
521/** Deprecated in favor of grpc_ssl_server_credentials_create_with_options.
522 Same as grpc_ssl_server_credentials_create method except uses
523 grpc_ssl_client_certificate_request_type enum to support more ways to
524 authenticate client certificates.*/
525GRPCAPI grpc_server_credentials* grpc_ssl_server_credentials_create_ex(
526 const char* pem_root_certs, grpc_ssl_pem_key_cert_pair* pem_key_cert_pairs,
527 size_t num_key_cert_pairs,
528 grpc_ssl_client_certificate_request_type client_certificate_request,
529 void* reserved);
530
531typedef struct grpc_ssl_server_credentials_options
532 grpc_ssl_server_credentials_options;
533
534/** Creates an options object using a certificate config. Use this method when
535 the certificates and keys of the SSL server will not change during the
536 server's lifetime.
537 - Takes ownership of the certificate_config parameter. */
538GRPCAPI grpc_ssl_server_credentials_options*
539grpc_ssl_server_credentials_create_options_using_config(
540 grpc_ssl_client_certificate_request_type client_certificate_request,
541 grpc_ssl_server_certificate_config* certificate_config);
542
543/** Creates an options object using a certificate config fetcher. Use this
544 method to reload the certificates and keys of the SSL server without
545 interrupting the operation of the server. Initial certificate config will be
546 fetched during server initialization.
547 - user_data parameter, if not NULL, contains opaque data which will be passed
548 to the fetcher (see definition of
549 grpc_ssl_server_certificate_config_callback). */
550GRPCAPI grpc_ssl_server_credentials_options*
551grpc_ssl_server_credentials_create_options_using_config_fetcher(
552 grpc_ssl_client_certificate_request_type client_certificate_request,
553 grpc_ssl_server_certificate_config_callback cb, void* user_data);
554
555/** Destroys a grpc_ssl_server_credentials_options object. */
556GRPCAPI void grpc_ssl_server_credentials_options_destroy(
557 grpc_ssl_server_credentials_options* options);
558
559/** Creates an SSL server_credentials object using the provided options struct.
560 - Takes ownership of the options parameter. */
561GRPCAPI grpc_server_credentials*
562grpc_ssl_server_credentials_create_with_options(
563 grpc_ssl_server_credentials_options* options);
564
565/** --- Server-side secure ports. --- */
566
567/** Add a HTTP2 over an encrypted link over tcp listener.
568 Returns bound port number on success, 0 on failure.
569 REQUIRES: server not started */
570GRPCAPI int grpc_server_add_secure_http2_port(grpc_server* server,
571 const char* addr,
572 grpc_server_credentials* creds);
573
574/** --- Call specific credentials. --- */
575
576/** Sets a credentials to a call. Can only be called on the client side before
577 grpc_call_start_batch. */
578GRPCAPI grpc_call_error grpc_call_set_credentials(grpc_call* call,
579 grpc_call_credentials* creds);
580
581/** --- Auth Metadata Processing --- */
582
583/** Callback function that is called when the metadata processing is done.
584 - Consumed metadata will be removed from the set of metadata available on the
585 call. consumed_md may be NULL if no metadata has been consumed.
586 - Response metadata will be set on the response. response_md may be NULL.
587 - status is GRPC_STATUS_OK for success or a specific status for an error.
588 Common error status for auth metadata processing is either
589 GRPC_STATUS_UNAUTHENTICATED in case of an authentication failure or
590 GRPC_STATUS PERMISSION_DENIED in case of an authorization failure.
591 - error_details gives details about the error. May be NULL. */
592typedef void (*grpc_process_auth_metadata_done_cb)(
593 void* user_data, const grpc_metadata* consumed_md, size_t num_consumed_md,
594 const grpc_metadata* response_md, size_t num_response_md,
595 grpc_status_code status, const char* error_details);
596
597/** Pluggable server-side metadata processor object. */
598typedef struct {
599 /** The context object is read/write: it contains the properties of the
600 channel peer and it is the job of the process function to augment it with
601 properties derived from the passed-in metadata.
602 The lifetime of these objects is guaranteed until cb is invoked. */
603 void (*process)(void* state, grpc_auth_context* context,
604 const grpc_metadata* md, size_t num_md,
605 grpc_process_auth_metadata_done_cb cb, void* user_data);
606 void (*destroy)(void* state);
607 void* state;
608} grpc_auth_metadata_processor;
609
610GRPCAPI void grpc_server_credentials_set_auth_metadata_processor(
611 grpc_server_credentials* creds, grpc_auth_metadata_processor processor);
612
613/** --- ALTS channel/server credentials --- **/
614
615/**
616 * Main interface for ALTS credentials options. The options will contain
617 * information that will be passed from grpc to TSI layer such as RPC protocol
618 * versions. ALTS client (channel) and server credentials will have their own
619 * implementation of this interface. The APIs listed in this header are
620 * thread-compatible. It is used for experimental purpose for now and subject
621 * to change.
622 */
623typedef struct grpc_alts_credentials_options grpc_alts_credentials_options;
624
625/**
626 * This method creates a grpc ALTS credentials client options instance.
627 * It is used for experimental purpose for now and subject to change.
628 */
629GRPCAPI grpc_alts_credentials_options*
630grpc_alts_credentials_client_options_create(void);
631
632/**
633 * This method creates a grpc ALTS credentials server options instance.
634 * It is used for experimental purpose for now and subject to change.
635 */
636GRPCAPI grpc_alts_credentials_options*
637grpc_alts_credentials_server_options_create(void);
638
639/**
640 * This method adds a target service account to grpc client's ALTS credentials
641 * options instance. It is used for experimental purpose for now and subject
642 * to change.
643 *
644 * - options: grpc ALTS credentials options instance.
645 * - service_account: service account of target endpoint.
646 */
647GRPCAPI void grpc_alts_credentials_client_options_add_target_service_account(
648 grpc_alts_credentials_options* options, const char* service_account);
649
650/**
651 * This method destroys a grpc_alts_credentials_options instance by
652 * de-allocating all of its occupied memory. It is used for experimental purpose
653 * for now and subject to change.
654 *
655 * - options: a grpc_alts_credentials_options instance that needs to be
656 * destroyed.
657 */
658GRPCAPI void grpc_alts_credentials_options_destroy(
659 grpc_alts_credentials_options* options);
660
661/**
662 * This method creates an ALTS channel credential object. The security
663 * level of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY.
664 * It is used for experimental purpose for now and subject to change.
665 *
666 * - options: grpc ALTS credentials options instance for client.
667 *
668 * It returns the created ALTS channel credential object.
669 */
670GRPCAPI grpc_channel_credentials* grpc_alts_credentials_create(
671 const grpc_alts_credentials_options* options);
672
673/**
674 * This method creates an ALTS server credential object. It is used for
675 * experimental purpose for now and subject to change.
676 *
677 * - options: grpc ALTS credentials options instance for server.
678 *
679 * It returns the created ALTS server credential object.
680 */
681GRPCAPI grpc_server_credentials* grpc_alts_server_credentials_create(
682 const grpc_alts_credentials_options* options);
683
684/** --- Local channel/server credentials --- **/
685
686/**
687 * This method creates a local channel credential object. The security level
688 * of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY for UDS and
689 * GRPC_SECURITY_NONE for LOCAL_TCP. It is used for experimental purpose
690 * for now and subject to change.
691 *
692 * - type: local connection type
693 *
694 * It returns the created local channel credential object.
695 */
696GRPCAPI grpc_channel_credentials* grpc_local_credentials_create(
697 grpc_local_connect_type type);
698
699/**
700 * This method creates a local server credential object. It is used for
701 * experimental purpose for now and subject to change.
702 *
703 * - type: local connection type
704 *
705 * It returns the created local server credential object.
706 */
707GRPCAPI grpc_server_credentials* grpc_local_server_credentials_create(
708 grpc_local_connect_type type);
709
710/** --- TLS channel/server credentials ---
711 * It is used for experimental purpose for now and subject to change. */
712
713/** Config for TLS key materials. It is used for
714 * experimental purpose for now and subject to change. */
715typedef struct grpc_tls_key_materials_config grpc_tls_key_materials_config;
716
717/** Config for TLS credential reload. It is used for
718 * experimental purpose for now and subject to change. */
719typedef struct grpc_tls_credential_reload_config
720 grpc_tls_credential_reload_config;
721
722/** Config for TLS server authorization check. It is used for
723 * experimental purpose for now and subject to change. */
724typedef struct grpc_tls_server_authorization_check_config
725 grpc_tls_server_authorization_check_config;
726
727/** TLS credentials options. It is used for
728 * experimental purpose for now and subject to change. */
729typedef struct grpc_tls_credentials_options grpc_tls_credentials_options;
730
731/** Create an empty TLS credentials options. It is used for
732 * experimental purpose for now and subject to change. */
733GRPCAPI grpc_tls_credentials_options* grpc_tls_credentials_options_create(void);
734
735/** Set grpc_ssl_client_certificate_request_type field in credentials options
736 with the provided type. options should not be NULL.
737 It returns 1 on success and 0 on failure. It is used for
738 experimental purpose for now and subject to change. */
739GRPCAPI int grpc_tls_credentials_options_set_cert_request_type(
740 grpc_tls_credentials_options* options,
741 grpc_ssl_client_certificate_request_type type);
742
743/** Set grpc_tls_server_verification_option field in credentials options
744 with the provided server_verification_option. options should not be NULL.
745 This should be called only on the client side.
746 If grpc_tls_server_verification_option is not
747 GRPC_TLS_SERVER_VERIFICATION, use of a customer server
748 authorization check (grpc_tls_server_authorization_check_config)
749 will be mandatory.
750 It returns 1 on success and 0 on failure. It is used for
751 experimental purpose for now and subject to change. */
752GRPCAPI int grpc_tls_credentials_options_set_server_verification_option(
753 grpc_tls_credentials_options* options,
754 grpc_tls_server_verification_option server_verification_option);
755
756/** Set grpc_tls_key_materials_config field in credentials options
757 with the provided config struct whose ownership is transferred.
758 Both parameters should not be NULL.
759 It returns 1 on success and 0 on failure. It is used for
760 experimental purpose for now and subject to change. */
761GRPCAPI int grpc_tls_credentials_options_set_key_materials_config(
762 grpc_tls_credentials_options* options,
763 grpc_tls_key_materials_config* config);
764
765/** Set grpc_tls_credential_reload_config field in credentials options
766 with the provided config struct whose ownership is transferred.
767 Both parameters should not be NULL.
768 It returns 1 on success and 0 on failure. It is used for
769 experimental purpose for now and subject to change. */
770GRPCAPI int grpc_tls_credentials_options_set_credential_reload_config(
771 grpc_tls_credentials_options* options,
772 grpc_tls_credential_reload_config* config);
773
774/** Set grpc_tls_server_authorization_check_config field in credentials options
775 with the provided config struct whose ownership is transferred.
776 Both parameters should not be NULL.
777 It returns 1 on success and 0 on failure. It is used for
778 experimental purpose for now and subject to change. */
779GRPCAPI int grpc_tls_credentials_options_set_server_authorization_check_config(
780 grpc_tls_credentials_options* options,
781 grpc_tls_server_authorization_check_config* config);
782
783/** --- TLS key materials config. ---
784 It is used for experimental purpose for now and subject to change. */
785
786/** Create an empty grpc_tls_key_materials_config instance.
787 * It is used for experimental purpose for now and subject to change. */
788GRPCAPI grpc_tls_key_materials_config* grpc_tls_key_materials_config_create(
789 void);
790
791/** Set grpc_tls_key_materials_config instance with provided a TLS certificate.
792 config will take the ownership of pem_root_certs and pem_key_cert_pairs.
793 It's valid for the caller to provide nullptr pem_root_certs, in which case
794 the gRPC-provided root cert will be used. pem_key_cert_pairs should not be
795 NULL. It returns 1 on success and 0 on failure. It is used for
796 experimental purpose for now and subject to change.
797 */
798GRPCAPI int grpc_tls_key_materials_config_set_key_materials(
799 grpc_tls_key_materials_config* config, const char* pem_root_certs,
800 const grpc_ssl_pem_key_cert_pair** pem_key_cert_pairs,
801 size_t num_key_cert_pairs);
802
803/** Set grpc_tls_key_materials_config instance with a provided version number,
804 which is used to keep track of the version of key materials.
805 It returns 1 on success and 0 on failure. It is used for
806 experimental purpose for now and subject to change.
807 */
808GRPCAPI int grpc_tls_key_materials_config_set_version(
809 grpc_tls_key_materials_config* config, int version);
810
811/** Get the version number of a grpc_tls_key_materials_config instance.
812 It returns the version number on success and -1 on failure.
813 It is used for experimental purpose for now and subject to change.
814 */
815GRPCAPI int grpc_tls_key_materials_config_get_version(
816 grpc_tls_key_materials_config* config);
817
818/** --- TLS credential reload config. ---
819 It is used for experimental purpose for now and subject to change.*/
820
821typedef struct grpc_tls_credential_reload_arg grpc_tls_credential_reload_arg;
822
823/** A callback function provided by gRPC to handle the result of credential
824 reload. It is used when schedule API is implemented asynchronously and
825 serves to bring the control back to grpc C core. It is used for
826 experimental purpose for now and subject to change. */
827typedef void (*grpc_tls_on_credential_reload_done_cb)(
828 grpc_tls_credential_reload_arg* arg);
829
830/** A struct containing all information necessary to schedule/cancel a
831 credential reload request.
832 - cb and cb_user_data represent a gRPC-provided
833 callback and an argument passed to it.
834 - key_materials_config is an in/output parameter containing currently
835 used/newly reloaded credentials. If credential reload does not result
836 in a new credential, key_materials_config should not be modified.
837 - status and error_details are used to hold information about
838 errors occurred when a credential reload request is scheduled/cancelled.
839 - config is a pointer to the unique grpc_tls_credential_reload_config
840 instance that this argument corresponds to.
841 - context is a pointer to a wrapped language implementation of this
842 grpc_tls_credential_reload_arg instance.
843 - destroy_context is a pointer to a caller-provided method that cleans
844 up any data associated with the context pointer.
845 It is used for experimental purposes for now and subject to change.
846*/
847struct grpc_tls_credential_reload_arg {
848 grpc_tls_on_credential_reload_done_cb cb;
849 void* cb_user_data;
850 grpc_tls_key_materials_config* key_materials_config;
851 grpc_ssl_certificate_config_reload_status status;
852 const char* error_details;
853 grpc_tls_credential_reload_config* config;
854 void* context;
855 void (*destroy_context)(void* ctx);
856};
857
858/** Create a grpc_tls_credential_reload_config instance.
859 - config_user_data is config-specific, read-only user data
860 that works for all channels created with a credential using the config.
861 - schedule is a pointer to an application-provided callback used to invoke
862 credential reload API. The implementation of this method has to be
863 non-blocking, but can be performed synchronously or asynchronously.
864 1) If processing occurs synchronously, it populates arg->key_materials,
865 arg->status, and arg->error_details and returns zero.
866 2) If processing occurs asynchronously, it returns a non-zero value.
867 The application then invokes arg->cb when processing is completed. Note
868 that arg->cb cannot be invoked before schedule API returns.
869 - cancel is a pointer to an application-provided callback used to cancel
870 a credential reload request scheduled via an asynchronous schedule API.
871 arg is used to pinpoint an exact reloading request to be cancelled.
872 The operation may not have any effect if the request has already been
873 processed.
874 - destruct is a pointer to an application-provided callback used to clean up
875 any data associated with the config.
876 It is used for experimental purpose for now and subject to change.
877*/
878GRPCAPI grpc_tls_credential_reload_config*
879grpc_tls_credential_reload_config_create(
880 const void* config_user_data,
881 int (*schedule)(void* config_user_data,
882 grpc_tls_credential_reload_arg* arg),
883 void (*cancel)(void* config_user_data, grpc_tls_credential_reload_arg* arg),
884 void (*destruct)(void* config_user_data));
885
886/** --- TLS server authorization check config. ---
887 * It is used for experimental purpose for now and subject to change. */
888
889typedef struct grpc_tls_server_authorization_check_arg
890 grpc_tls_server_authorization_check_arg;
891
892/** callback function provided by gRPC used to handle the result of server
893 authorization check. It is used when schedule API is implemented
894 asynchronously, and serves to bring the control back to gRPC C core. It is
895 used for experimental purpose for now and subject to change. */
896typedef void (*grpc_tls_on_server_authorization_check_done_cb)(
897 grpc_tls_server_authorization_check_arg* arg);
898
899/** A struct containing all information necessary to schedule/cancel a server
900 authorization check request.
901 - cb and cb_user_data represent a gRPC-provided callback and an argument
902 passed to it.
903 - success will store the result of server authorization check. That is,
904 if success returns a non-zero value, it means the authorization check
905 passes and if returning zero, it means the check fails.
906 - target_name is the name of an endpoint the channel is connecting to.
907 - peer_cert represents a complete certificate chain including both
908 signing and leaf certificates.
909 - status and error_details contain information
910 about errors occurred when a server authorization check request is
911 scheduled/cancelled.
912 - config is a pointer to the unique
913 grpc_tls_server_authorization_check_config instance that this argument
914 corresponds to.
915 - context is a pointer to a wrapped language implementation of this
916 grpc_tls_server_authorization_check_arg instance.
917 - destroy_context is a pointer to a caller-provided method that cleans
918 up any data associated with the context pointer.
919 It is used for experimental purpose for now and subject to change.
920*/
921struct grpc_tls_server_authorization_check_arg {
922 grpc_tls_on_server_authorization_check_done_cb cb;
923 void* cb_user_data;
924 int success;
925 const char* target_name;
926 const char* peer_cert;
927 const char* peer_cert_full_chain;
928 grpc_status_code status;
929 const char* error_details;
930 grpc_tls_server_authorization_check_config* config;
931 void* context;
932 void (*destroy_context)(void* ctx);
933};
934
935/** Create a grpc_tls_server_authorization_check_config instance.
936 - config_user_data is config-specific, read-only user data
937 that works for all channels created with a credential using the config.
938 - schedule is a pointer to an application-provided callback used to invoke
939 server authorization check API. The implementation of this method has to
940 be non-blocking, but can be performed synchronously or asynchronously.
941 1)If processing occurs synchronously, it populates arg->result,
942 arg->status, and arg->error_details and returns zero.
943 2) If processing occurs asynchronously, it returns a non-zero value. The
944 application then invokes arg->cb when processing is completed. Note that
945 arg->cb cannot be invoked before schedule API returns.
946 - cancel is a pointer to an application-provided callback used to cancel a
947 server authorization check request scheduled via an asynchronous schedule
948 API. arg is used to pinpoint an exact check request to be cancelled. The
949 operation may not have any effect if the request has already been
950 processed.
951 - destruct is a pointer to an application-provided callback used to clean up
952 any data associated with the config.
953 It is used for experimental purpose for now and subject to change.
954*/
955GRPCAPI grpc_tls_server_authorization_check_config*
956grpc_tls_server_authorization_check_config_create(
957 const void* config_user_data,
958 int (*schedule)(void* config_user_data,
959 grpc_tls_server_authorization_check_arg* arg),
960 void (*cancel)(void* config_user_data,
961 grpc_tls_server_authorization_check_arg* arg),
962 void (*destruct)(void* config_user_data));
963
964/**
965 * This method creates a TLS channel credential object.
966 * It takes ownership of the options parameter. The security level
967 * of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY.
968 *
969 * - options: grpc TLS credentials options instance.
970 *
971 * It returns the created credential object.
972 *
973 * It is used for experimental purpose for now and subject
974 * to change.
975 */
976
977grpc_channel_credentials* grpc_tls_credentials_create(
978 grpc_tls_credentials_options* options);
979
980/**
981 * This method creates a TLS server credential object.
982 * It takes ownership of the options parameter.
983 *
984 * - options: grpc TLS credentials options instance.
985 *
986 * It returns the created credential object.
987 *
988 * It is used for experimental purpose for now and subject
989 * to change.
990 */
991grpc_server_credentials* grpc_tls_server_credentials_create(
992 grpc_tls_credentials_options* options);
993
994#ifdef __cplusplus
995}
996#endif
997
998#endif /* GRPC_GRPC_SECURITY_H */
999