3 * Copyright 2015 gRPC authors.
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
9 * http://www.apache.org/licenses/LICENSE-2.0
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.
19 #ifndef GRPC_GRPC_SECURITY_H
20 #define GRPC_GRPC_SECURITY_H
22 #include <grpc/support/port_platform.h>
24 #include <grpc/grpc.h>
25 #include <grpc/grpc_security_constants.h>
26 #include <grpc/status.h>
32 /** --- Authentication Context. --- */
34 typedef struct grpc_auth_context grpc_auth_context;
36 typedef struct grpc_auth_property_iterator {
37 const grpc_auth_context* ctx;
40 } grpc_auth_property_iterator;
42 /** value, if not NULL, is guaranteed to be NULL terminated. */
43 typedef struct grpc_auth_property {
49 /** Returns NULL when the iterator is at the end. */
50 GRPCAPI const grpc_auth_property* grpc_auth_property_iterator_next(
51 grpc_auth_property_iterator* it);
53 /** Iterates over the auth context. */
54 GRPCAPI grpc_auth_property_iterator
55 grpc_auth_context_property_iterator(const grpc_auth_context* ctx);
57 /** Gets the peer identity. Returns an empty iterator (first _next will return
58 NULL) if the peer is not authenticated. */
59 GRPCAPI grpc_auth_property_iterator
60 grpc_auth_context_peer_identity(const grpc_auth_context* ctx);
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. */
64 GRPCAPI grpc_auth_property_iterator grpc_auth_context_find_properties_by_name(
65 const grpc_auth_context* ctx, const char* name);
67 /** Gets the name of the property that indicates the peer identity. Will return
68 NULL if the peer is not authenticated. */
69 GRPCAPI const char* grpc_auth_context_peer_identity_property_name(
70 const grpc_auth_context* ctx);
72 /** Returns 1 if the peer is authenticated, 0 otherwise. */
73 GRPCAPI int grpc_auth_context_peer_is_authenticated(
74 const grpc_auth_context* ctx);
76 /** Gets the auth context from the call. Caller needs to call
77 grpc_auth_context_release on the returned context. */
78 GRPCAPI grpc_auth_context* grpc_call_auth_context(grpc_call* call);
80 /** Releases the auth context returned from grpc_call_auth_context. */
81 GRPCAPI void grpc_auth_context_release(grpc_auth_context* context);
84 The following auth context methods should only be called by a server metadata
85 processor to set properties extracted from auth metadata.
88 /** Add a property. */
89 GRPCAPI void grpc_auth_context_add_property(grpc_auth_context* ctx,
90 const char* name, const char* value,
93 /** Add a C string property. */
94 GRPCAPI void grpc_auth_context_add_cstring_property(grpc_auth_context* ctx,
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). */
100 GRPCAPI int grpc_auth_context_set_peer_identity_property_name(
101 grpc_auth_context* ctx, const char* name);
103 /** --- SSL Session Cache. ---
105 A SSL session cache object represents a way to cache client sessions
106 between connections. Only ticket-based resumption is supported. */
108 typedef struct grpc_ssl_session_cache grpc_ssl_session_cache;
110 /** Create LRU cache for client-side SSL sessions with the given capacity.
111 If capacity is < 1, a default capacity is used instead. */
112 GRPCAPI grpc_ssl_session_cache* grpc_ssl_session_cache_create_lru(
115 /** Destroy SSL session cache. */
116 GRPCAPI void grpc_ssl_session_cache_destroy(grpc_ssl_session_cache* cache);
118 /** Create a channel arg with the given cache object. */
120 grpc_ssl_session_cache_create_channel_arg(grpc_ssl_session_cache* cache);
122 /** --- grpc_call_credentials object.
124 A call credentials object represents a way to authenticate on a particular
125 call. These credentials can be composed with a channel credentials object
126 so that they are sent with every call on this channel. */
128 typedef struct grpc_call_credentials grpc_call_credentials;
130 /** Releases a call credentials object.
131 The creator of the credentials object is responsible for its release. */
132 GRPCAPI void grpc_call_credentials_release(grpc_call_credentials* creds);
134 /** --- grpc_channel_credentials object. ---
136 A channel credentials object represents a way to authenticate a client on a
139 typedef struct grpc_channel_credentials grpc_channel_credentials;
141 /** Releases a channel credentials object.
142 The creator of the credentials object is responsible for its release. */
143 GRPCAPI void grpc_channel_credentials_release(grpc_channel_credentials* creds);
145 /** Creates default credentials to connect to a google gRPC service.
146 WARNING: Do NOT use this credentials to connect to a non-google service as
147 this could result in an oauth2 token leak. The security level of the
148 resulting connection is GRPC_PRIVACY_AND_INTEGRITY.
150 If specified, the supplied call credentials object will be attached to the
151 returned channel credentials object. The call_credentials object must remain
152 valid throughout the lifetime of the returned grpc_channel_credentials
153 object. It is expected that the call credentials object was generated
154 according to the Application Default Credentials mechanism and asserts the
155 identity of the default service account of the machine. Supplying any other
156 sort of call credential will result in undefined behavior, up to and
157 including the sudden and unexpected failure of RPCs.
159 If nullptr is supplied, the returned channel credentials object will use a
160 call credentials object based on the Application Default Credentials
163 GRPCAPI grpc_channel_credentials* grpc_google_default_credentials_create(
164 grpc_call_credentials* call_credentials);
166 /** Callback for getting the SSL roots override from the application.
167 In case of success, *pem_roots_certs must be set to a NULL terminated string
168 containing the list of PEM encoded root certificates. The ownership is passed
169 to the core and freed (laster by the core) with gpr_free.
170 If this function fails and GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment is
171 set to a valid path, it will override the roots specified this func */
172 typedef grpc_ssl_roots_override_result (*grpc_ssl_roots_override_callback)(
173 char** pem_root_certs);
175 /** Setup a callback to override the default TLS/SSL roots.
176 This function is not thread-safe and must be called at initialization time
177 before any ssl credentials are created to have the desired side effect.
178 If GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment is set to a valid path, the
179 callback will not be called. */
180 GRPCAPI void grpc_set_ssl_roots_override_callback(
181 grpc_ssl_roots_override_callback cb);
183 /** Object that holds a private key / certificate chain pair in PEM format. */
185 /** private_key is the NULL-terminated string containing the PEM encoding of
186 the client's private key. */
187 const char* private_key;
189 /** cert_chain is the NULL-terminated string containing the PEM encoding of
190 the client's certificate chain. */
191 const char* cert_chain;
192 } grpc_ssl_pem_key_cert_pair;
194 /** Deprecated in favor of grpc_ssl_verify_peer_options. It will be removed
195 after all of its call sites are migrated to grpc_ssl_verify_peer_options.
196 Object that holds additional peer-verification options on a secure
199 /** If non-NULL this callback will be invoked with the expected
200 target_name, the peer's certificate (in PEM format), and whatever
201 userdata pointer is set below. If a non-zero value is returned by this
202 callback then it is treated as a verification failure. Invocation of
203 the callback is blocking, so any implementation should be light-weight.
205 int (*verify_peer_callback)(const char* target_name, const char* peer_pem,
207 /** Arbitrary userdata that will be passed as the last argument to
208 verify_peer_callback. */
209 void* verify_peer_callback_userdata;
210 /** A destruct callback that will be invoked when the channel is being
211 cleaned up. The userdata argument will be passed to it. The intent is
212 to perform any cleanup associated with that userdata. */
213 void (*verify_peer_destruct)(void* userdata);
214 } verify_peer_options;
216 /** Object that holds additional peer-verification options on a secure
219 /** If non-NULL this callback will be invoked with the expected
220 target_name, the peer's certificate (in PEM format), and whatever
221 userdata pointer is set below. If a non-zero value is returned by this
222 callback then it is treated as a verification failure. Invocation of
223 the callback is blocking, so any implementation should be light-weight.
225 int (*verify_peer_callback)(const char* target_name, const char* peer_pem,
227 /** Arbitrary userdata that will be passed as the last argument to
228 verify_peer_callback. */
229 void* verify_peer_callback_userdata;
230 /** A destruct callback that will be invoked when the channel is being
231 cleaned up. The userdata argument will be passed to it. The intent is
232 to perform any cleanup associated with that userdata. */
233 void (*verify_peer_destruct)(void* userdata);
234 } grpc_ssl_verify_peer_options;
236 /** Deprecated in favor of grpc_ssl_server_credentials_create_ex. It will be
237 removed after all of its call sites are migrated to
238 grpc_ssl_server_credentials_create_ex. Creates an SSL credentials object.
239 The security level of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY.
240 - pem_root_certs is the NULL-terminated string containing the PEM encoding
241 of the server root certificates. If this parameter is NULL, the
242 implementation will first try to dereference the file pointed by the
243 GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment variable, and if that fails,
244 try to get the roots set by grpc_override_ssl_default_roots. Eventually,
245 if all these fail, it will try to get the roots from a well-known place on
246 disk (in the grpc install directory).
248 gRPC has implemented root cache if the underlying OpenSSL library supports
249 it. The gRPC root certificates cache is only applicable on the default
250 root certificates, which is used when this parameter is nullptr. If user
251 provides their own pem_root_certs, when creating an SSL credential object,
252 gRPC would not be able to cache it, and each subchannel will generate a
253 copy of the root store. So it is recommended to avoid providing large room
254 pem with pem_root_certs parameter to avoid excessive memory consumption,
255 particularly on mobile platforms such as iOS.
256 - pem_key_cert_pair is a pointer on the object containing client's private
257 key and certificate chain. This parameter can be NULL if the client does
258 not have such a key/cert pair.
259 - verify_options is an optional verify_peer_options object which holds
260 additional options controlling how peer certificates are verified. For
261 example, you can supply a callback which receives the peer's certificate
262 with which you can do additional verification. Can be NULL, in which
263 case verification will retain default behavior. Any settings in
264 verify_options are copied during this call, so the verify_options
265 object can be released afterwards. */
266 GRPCAPI grpc_channel_credentials* grpc_ssl_credentials_create(
267 const char* pem_root_certs, grpc_ssl_pem_key_cert_pair* pem_key_cert_pair,
268 const verify_peer_options* verify_options, void* reserved);
270 /* Creates an SSL credentials object.
271 The security level of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY.
272 - pem_root_certs is the NULL-terminated string containing the PEM encoding
273 of the server root certificates. If this parameter is NULL, the
274 implementation will first try to dereference the file pointed by the
275 GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment variable, and if that fails,
276 try to get the roots set by grpc_override_ssl_default_roots. Eventually,
277 if all these fail, it will try to get the roots from a well-known place on
278 disk (in the grpc install directory).
280 gRPC has implemented root cache if the underlying OpenSSL library supports
281 it. The gRPC root certificates cache is only applicable on the default
282 root certificates, which is used when this parameter is nullptr. If user
283 provides their own pem_root_certs, when creating an SSL credential object,
284 gRPC would not be able to cache it, and each subchannel will generate a
285 copy of the root store. So it is recommended to avoid providing large room
286 pem with pem_root_certs parameter to avoid excessive memory consumption,
287 particularly on mobile platforms such as iOS.
288 - pem_key_cert_pair is a pointer on the object containing client's private
289 key and certificate chain. This parameter can be NULL if the client does
290 not have such a key/cert pair.
291 - verify_options is an optional verify_peer_options object which holds
292 additional options controlling how peer certificates are verified. For
293 example, you can supply a callback which receives the peer's certificate
294 with which you can do additional verification. Can be NULL, in which
295 case verification will retain default behavior. Any settings in
296 verify_options are copied during this call, so the verify_options
297 object can be released afterwards. */
298 GRPCAPI grpc_channel_credentials* grpc_ssl_credentials_create_ex(
299 const char* pem_root_certs, grpc_ssl_pem_key_cert_pair* pem_key_cert_pair,
300 const grpc_ssl_verify_peer_options* verify_options, void* reserved);
302 /** Creates a composite channel credentials object. The security level of
303 * resulting connection is determined by channel_creds. */
304 GRPCAPI grpc_channel_credentials* grpc_composite_channel_credentials_create(
305 grpc_channel_credentials* channel_creds, grpc_call_credentials* call_creds,
308 /** --- composite credentials. */
310 /** Creates a composite call credentials object. */
311 GRPCAPI grpc_call_credentials* grpc_composite_call_credentials_create(
312 grpc_call_credentials* creds1, grpc_call_credentials* creds2,
315 /** Creates a compute engine credentials object for connecting to Google.
316 WARNING: Do NOT use this credentials to connect to a non-google service as
317 this could result in an oauth2 token leak. */
318 GRPCAPI grpc_call_credentials* grpc_google_compute_engine_credentials_create(
321 GRPCAPI gpr_timespec grpc_max_auth_token_lifetime(void);
323 /** Creates a JWT credentials object. May return NULL if the input is invalid.
324 - json_key is the JSON key string containing the client's private key.
325 - token_lifetime is the lifetime of each Json Web Token (JWT) created with
326 this credentials. It should not exceed grpc_max_auth_token_lifetime or
327 will be cropped to this value. */
328 GRPCAPI grpc_call_credentials*
329 grpc_service_account_jwt_access_credentials_create(const char* json_key,
330 gpr_timespec token_lifetime,
333 /** Builds External Account credentials.
334 - json_string is the JSON string containing the credentials options.
335 - scopes_string contains the scopes to be binded with the credentials.
336 This API is used for experimental purposes for now and may change in the
338 GRPCAPI grpc_call_credentials* grpc_external_account_credentials_create(
339 const char* json_string, const char* scopes_string);
341 /** Creates an Oauth2 Refresh Token credentials object for connecting to Google.
342 May return NULL if the input is invalid.
343 WARNING: Do NOT use this credentials to connect to a non-google service as
344 this could result in an oauth2 token leak.
345 - json_refresh_token is the JSON string containing the refresh token itself
346 along with a client_id and client_secret. */
347 GRPCAPI grpc_call_credentials* grpc_google_refresh_token_credentials_create(
348 const char* json_refresh_token, void* reserved);
350 /** Creates an Oauth2 Access Token credentials with an access token that was
351 acquired by an out of band mechanism. */
352 GRPCAPI grpc_call_credentials* grpc_access_token_credentials_create(
353 const char* access_token, void* reserved);
355 /** Creates an IAM credentials object for connecting to Google. */
356 GRPCAPI grpc_call_credentials* grpc_google_iam_credentials_create(
357 const char* authorization_token, const char* authority_selector,
360 /** Options for creating STS Oauth Token Exchange credentials following the IETF
361 draft https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16.
362 Optional fields may be set to NULL or empty string. It is the responsibility
363 of the caller to ensure that the subject and actor tokens are refreshed on
364 disk at the specified paths. This API is used for experimental purposes for
365 now and may change in the future. */
367 const char* token_exchange_service_uri; /* Required. */
368 const char* resource; /* Optional. */
369 const char* audience; /* Optional. */
370 const char* scope; /* Optional. */
371 const char* requested_token_type; /* Optional. */
372 const char* subject_token_path; /* Required. */
373 const char* subject_token_type; /* Required. */
374 const char* actor_token_path; /* Optional. */
375 const char* actor_token_type; /* Optional. */
376 } grpc_sts_credentials_options;
378 /** Creates an STS credentials following the STS Token Exchanged specifed in the
379 IETF draft https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16.
380 This API is used for experimental purposes for now and may change in the
382 GRPCAPI grpc_call_credentials* grpc_sts_credentials_create(
383 const grpc_sts_credentials_options* options, void* reserved);
385 /** Callback function to be called by the metadata credentials plugin
386 implementation when the metadata is ready.
387 - user_data is the opaque pointer that was passed in the get_metadata method
388 of the grpc_metadata_credentials_plugin (see below).
389 - creds_md is an array of credentials metadata produced by the plugin. It
390 may be set to NULL in case of an error.
391 - num_creds_md is the number of items in the creds_md array.
392 - status must be GRPC_STATUS_OK in case of success or another specific error
394 - error_details contains details about the error if any. In case of success
395 it should be NULL and will be otherwise ignored. */
396 typedef void (*grpc_credentials_plugin_metadata_cb)(
397 void* user_data, const grpc_metadata* creds_md, size_t num_creds_md,
398 grpc_status_code status, const char* error_details);
400 /** Context that can be used by metadata credentials plugin in order to create
401 auth related metadata. */
403 /** The fully qualifed service url. */
404 const char* service_url;
406 /** The method name of the RPC being called (not fully qualified).
407 The fully qualified method name can be built from the service_url:
408 full_qualified_method_name = ctx->service_url + '/' + ctx->method_name. */
409 const char* method_name;
411 /** The auth_context of the channel which gives the server's identity. */
412 const grpc_auth_context* channel_auth_context;
414 /** Reserved for future use. */
416 } grpc_auth_metadata_context;
418 /** Performs a deep copy from \a from to \a to. **/
419 GRPCAPI void grpc_auth_metadata_context_copy(grpc_auth_metadata_context* from,
420 grpc_auth_metadata_context* to);
422 /** Releases internal resources held by \a context. **/
423 GRPCAPI void grpc_auth_metadata_context_reset(
424 grpc_auth_metadata_context* context);
426 /** Maximum number of metadata entries returnable by a credentials plugin via
427 a synchronous return. */
428 #define GRPC_METADATA_CREDENTIALS_PLUGIN_SYNC_MAX 4
430 /** grpc_metadata_credentials plugin is an API user provided structure used to
431 create grpc_credentials objects that can be set on a channel (composed) or
432 a call. See grpc_credentials_metadata_create_from_plugin below.
433 The grpc client stack will call the get_metadata method of the plugin for
434 every call in scope for the credentials created from it. */
436 /** The implementation of this method has to be non-blocking, but can
437 be performed synchronously or asynchronously.
439 If processing occurs synchronously, returns non-zero and populates
440 creds_md, num_creds_md, status, and error_details. In this case,
441 the caller takes ownership of the entries in creds_md and of
442 error_details. Note that if the plugin needs to return more than
443 GRPC_METADATA_CREDENTIALS_PLUGIN_SYNC_MAX entries in creds_md, it must
444 return asynchronously.
446 If processing occurs asynchronously, returns zero and invokes \a cb
447 when processing is completed. \a user_data will be passed as the
448 first parameter of the callback. NOTE: \a cb MUST be invoked in a
449 different thread, not from the thread in which \a get_metadata() is
452 \a context is the information that can be used by the plugin to create
455 void* state, grpc_auth_metadata_context context,
456 grpc_credentials_plugin_metadata_cb cb, void* user_data,
457 grpc_metadata creds_md[GRPC_METADATA_CREDENTIALS_PLUGIN_SYNC_MAX],
458 size_t* num_creds_md, grpc_status_code* status,
459 const char** error_details);
461 /** Implements debug string of the given plugin. This method returns an
462 * allocated string that the caller needs to free using gpr_free() */
463 char* (*debug_string)(void* state);
465 /** Destroys the plugin state. */
466 void (*destroy)(void* state);
468 /** State that will be set as the first parameter of the methods above. */
471 /** Type of credentials that this plugin is implementing. */
473 } grpc_metadata_credentials_plugin;
475 /** Creates a credentials object from a plugin with a specified minimum security
477 GRPCAPI grpc_call_credentials* grpc_metadata_credentials_create_from_plugin(
478 grpc_metadata_credentials_plugin plugin,
479 grpc_security_level min_security_level, void* reserved);
481 /** --- Secure channel creation. --- */
483 /** Creates a secure channel using the passed-in credentials. Additional
484 channel level configuration MAY be provided by grpc_channel_args, though
485 the expectation is that most clients will want to simply pass NULL. The
486 user data in 'args' need only live through the invocation of this function.
487 However, if any args of the 'pointer' type are passed, then the referenced
488 vtable must be maintained by the caller until grpc_channel_destroy
489 terminates. See grpc_channel_args definition for more on this. */
490 GRPCAPI grpc_channel* grpc_secure_channel_create(
491 grpc_channel_credentials* creds, const char* target,
492 const grpc_channel_args* args, void* reserved);
494 /** --- grpc_server_credentials object. ---
496 A server credentials object represents a way to authenticate a server. */
498 typedef struct grpc_server_credentials grpc_server_credentials;
500 /** Releases a server_credentials object.
501 The creator of the server_credentials object is responsible for its release.
503 GRPCAPI void grpc_server_credentials_release(grpc_server_credentials* creds);
505 /** Server certificate config object holds the server's public certificates and
506 associated private keys, as well as any CA certificates needed for client
507 certificate validation (if applicable). Create using
508 grpc_ssl_server_certificate_config_create(). */
509 typedef struct grpc_ssl_server_certificate_config
510 grpc_ssl_server_certificate_config;
512 /** Creates a grpc_ssl_server_certificate_config object.
513 - pem_roots_cert is the NULL-terminated string containing the PEM encoding of
514 the client root certificates. This parameter may be NULL if the server does
515 not want the client to be authenticated with SSL.
516 - pem_key_cert_pairs is an array private key / certificate chains of the
517 server. This parameter cannot be NULL.
518 - num_key_cert_pairs indicates the number of items in the private_key_files
519 and cert_chain_files parameters. It must be at least 1.
520 - It is the caller's responsibility to free this object via
521 grpc_ssl_server_certificate_config_destroy(). */
522 GRPCAPI grpc_ssl_server_certificate_config*
523 grpc_ssl_server_certificate_config_create(
524 const char* pem_root_certs,
525 const grpc_ssl_pem_key_cert_pair* pem_key_cert_pairs,
526 size_t num_key_cert_pairs);
528 /** Destroys a grpc_ssl_server_certificate_config object. */
529 GRPCAPI void grpc_ssl_server_certificate_config_destroy(
530 grpc_ssl_server_certificate_config* config);
532 /** Callback to retrieve updated SSL server certificates, private keys, and
533 trusted CAs (for client authentication).
534 - user_data parameter, if not NULL, contains opaque data to be used by the
536 - Use grpc_ssl_server_certificate_config_create to create the config.
537 - The caller assumes ownership of the config. */
538 typedef grpc_ssl_certificate_config_reload_status (
539 *grpc_ssl_server_certificate_config_callback)(
540 void* user_data, grpc_ssl_server_certificate_config** config);
542 /** Deprecated in favor of grpc_ssl_server_credentials_create_ex.
543 Creates an SSL server_credentials object.
544 - pem_roots_cert is the NULL-terminated string containing the PEM encoding of
545 the client root certificates. This parameter may be NULL if the server does
546 not want the client to be authenticated with SSL.
547 - pem_key_cert_pairs is an array private key / certificate chains of the
548 server. This parameter cannot be NULL.
549 - num_key_cert_pairs indicates the number of items in the private_key_files
550 and cert_chain_files parameters. It should be at least 1.
551 - force_client_auth, if set to non-zero will force the client to authenticate
552 with an SSL cert. Note that this option is ignored if pem_root_certs is
554 GRPCAPI grpc_server_credentials* grpc_ssl_server_credentials_create(
555 const char* pem_root_certs, grpc_ssl_pem_key_cert_pair* pem_key_cert_pairs,
556 size_t num_key_cert_pairs, int force_client_auth, void* reserved);
558 /** Deprecated in favor of grpc_ssl_server_credentials_create_with_options.
559 Same as grpc_ssl_server_credentials_create method except uses
560 grpc_ssl_client_certificate_request_type enum to support more ways to
561 authenticate client certificates.*/
562 GRPCAPI grpc_server_credentials* grpc_ssl_server_credentials_create_ex(
563 const char* pem_root_certs, grpc_ssl_pem_key_cert_pair* pem_key_cert_pairs,
564 size_t num_key_cert_pairs,
565 grpc_ssl_client_certificate_request_type client_certificate_request,
568 typedef struct grpc_ssl_server_credentials_options
569 grpc_ssl_server_credentials_options;
571 /** Creates an options object using a certificate config. Use this method when
572 the certificates and keys of the SSL server will not change during the
574 - Takes ownership of the certificate_config parameter. */
575 GRPCAPI grpc_ssl_server_credentials_options*
576 grpc_ssl_server_credentials_create_options_using_config(
577 grpc_ssl_client_certificate_request_type client_certificate_request,
578 grpc_ssl_server_certificate_config* certificate_config);
580 /** Creates an options object using a certificate config fetcher. Use this
581 method to reload the certificates and keys of the SSL server without
582 interrupting the operation of the server. Initial certificate config will be
583 fetched during server initialization.
584 - user_data parameter, if not NULL, contains opaque data which will be passed
585 to the fetcher (see definition of
586 grpc_ssl_server_certificate_config_callback). */
587 GRPCAPI grpc_ssl_server_credentials_options*
588 grpc_ssl_server_credentials_create_options_using_config_fetcher(
589 grpc_ssl_client_certificate_request_type client_certificate_request,
590 grpc_ssl_server_certificate_config_callback cb, void* user_data);
592 /** Destroys a grpc_ssl_server_credentials_options object. */
593 GRPCAPI void grpc_ssl_server_credentials_options_destroy(
594 grpc_ssl_server_credentials_options* options);
596 /** Creates an SSL server_credentials object using the provided options struct.
597 - Takes ownership of the options parameter. */
598 GRPCAPI grpc_server_credentials*
599 grpc_ssl_server_credentials_create_with_options(
600 grpc_ssl_server_credentials_options* options);
602 /** --- Server-side secure ports. --- */
604 /** Add a HTTP2 over an encrypted link over tcp listener.
605 Returns bound port number on success, 0 on failure.
606 REQUIRES: server not started */
607 GRPCAPI int grpc_server_add_secure_http2_port(grpc_server* server,
609 grpc_server_credentials* creds);
611 /** --- Call specific credentials. --- */
613 /** Sets a credentials to a call. Can only be called on the client side before
614 grpc_call_start_batch. */
615 GRPCAPI grpc_call_error grpc_call_set_credentials(grpc_call* call,
616 grpc_call_credentials* creds);
618 /** --- Auth Metadata Processing --- */
620 /** Callback function that is called when the metadata processing is done.
621 - Consumed metadata will be removed from the set of metadata available on the
622 call. consumed_md may be NULL if no metadata has been consumed.
623 - Response metadata will be set on the response. response_md may be NULL.
624 - status is GRPC_STATUS_OK for success or a specific status for an error.
625 Common error status for auth metadata processing is either
626 GRPC_STATUS_UNAUTHENTICATED in case of an authentication failure or
627 GRPC_STATUS PERMISSION_DENIED in case of an authorization failure.
628 - error_details gives details about the error. May be NULL. */
629 typedef void (*grpc_process_auth_metadata_done_cb)(
630 void* user_data, const grpc_metadata* consumed_md, size_t num_consumed_md,
631 const grpc_metadata* response_md, size_t num_response_md,
632 grpc_status_code status, const char* error_details);
634 /** Pluggable server-side metadata processor object. */
636 /** The context object is read/write: it contains the properties of the
637 channel peer and it is the job of the process function to augment it with
638 properties derived from the passed-in metadata.
639 The lifetime of these objects is guaranteed until cb is invoked. */
640 void (*process)(void* state, grpc_auth_context* context,
641 const grpc_metadata* md, size_t num_md,
642 grpc_process_auth_metadata_done_cb cb, void* user_data);
643 void (*destroy)(void* state);
645 } grpc_auth_metadata_processor;
647 GRPCAPI void grpc_server_credentials_set_auth_metadata_processor(
648 grpc_server_credentials* creds, grpc_auth_metadata_processor processor);
650 /** --- ALTS channel/server credentials --- **/
653 * Main interface for ALTS credentials options. The options will contain
654 * information that will be passed from grpc to TSI layer such as RPC protocol
655 * versions. ALTS client (channel) and server credentials will have their own
656 * implementation of this interface. The APIs listed in this header are
657 * thread-compatible. It is used for experimental purpose for now and subject
660 typedef struct grpc_alts_credentials_options grpc_alts_credentials_options;
663 * This method creates a grpc ALTS credentials client options instance.
664 * It is used for experimental purpose for now and subject to change.
666 GRPCAPI grpc_alts_credentials_options*
667 grpc_alts_credentials_client_options_create(void);
670 * This method creates a grpc ALTS credentials server options instance.
671 * It is used for experimental purpose for now and subject to change.
673 GRPCAPI grpc_alts_credentials_options*
674 grpc_alts_credentials_server_options_create(void);
677 * This method adds a target service account to grpc client's ALTS credentials
678 * options instance. It is used for experimental purpose for now and subject
681 * - options: grpc ALTS credentials options instance.
682 * - service_account: service account of target endpoint.
684 GRPCAPI void grpc_alts_credentials_client_options_add_target_service_account(
685 grpc_alts_credentials_options* options, const char* service_account);
688 * This method destroys a grpc_alts_credentials_options instance by
689 * de-allocating all of its occupied memory. It is used for experimental purpose
690 * for now and subject to change.
692 * - options: a grpc_alts_credentials_options instance that needs to be
695 GRPCAPI void grpc_alts_credentials_options_destroy(
696 grpc_alts_credentials_options* options);
699 * This method creates an ALTS channel credential object. The security
700 * level of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY.
701 * It is used for experimental purpose for now and subject to change.
703 * - options: grpc ALTS credentials options instance for client.
705 * It returns the created ALTS channel credential object.
707 GRPCAPI grpc_channel_credentials* grpc_alts_credentials_create(
708 const grpc_alts_credentials_options* options);
711 * This method creates an ALTS server credential object. It is used for
712 * experimental purpose for now and subject to change.
714 * - options: grpc ALTS credentials options instance for server.
716 * It returns the created ALTS server credential object.
718 GRPCAPI grpc_server_credentials* grpc_alts_server_credentials_create(
719 const grpc_alts_credentials_options* options);
721 /** --- Local channel/server credentials --- **/
724 * This method creates a local channel credential object. The security level
725 * of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY for UDS and
726 * GRPC_SECURITY_NONE for LOCAL_TCP. It is used for experimental purpose
727 * for now and subject to change.
729 * - type: local connection type
731 * It returns the created local channel credential object.
733 GRPCAPI grpc_channel_credentials* grpc_local_credentials_create(
734 grpc_local_connect_type type);
737 * This method creates a local server credential object. It is used for
738 * experimental purpose for now and subject to change.
740 * - type: local connection type
742 * It returns the created local server credential object.
744 GRPCAPI grpc_server_credentials* grpc_local_server_credentials_create(
745 grpc_local_connect_type type);
747 /** --- TLS channel/server credentials ---
748 * It is used for experimental purpose for now and subject to change. */
750 /** Struct for indicating errors. It is used for
751 * experimental purpose for now and subject to change. */
752 typedef struct grpc_tls_error_details grpc_tls_error_details;
754 /** Config for TLS server authorization check. It is used for
755 * experimental purpose for now and subject to change. */
756 typedef struct grpc_tls_server_authorization_check_config
757 grpc_tls_server_authorization_check_config;
760 * A struct that can be specified by callers to configure underlying TLS
761 * behaviors. It is used for experimental purpose for now and subject to change.
763 typedef struct grpc_tls_credentials_options grpc_tls_credentials_options;
766 * A struct provides ways to gain credential data that will be used in the TLS
767 * handshake. It is used for experimental purpose for now and subject to change.
769 typedef struct grpc_tls_certificate_provider grpc_tls_certificate_provider;
772 * A struct that stores the credential data presented to the peer in handshake
773 * to show local identity. It is used for experimental purpose for now and
776 typedef struct grpc_tls_identity_pairs grpc_tls_identity_pairs;
779 * Creates a grpc_tls_identity_pairs that stores a list of identity credential
780 * data, including identity private key and identity certificate chain. It is
781 * used for experimental purpose for now and subject to change.
783 GRPCAPI grpc_tls_identity_pairs* grpc_tls_identity_pairs_create();
786 * Adds a identity private key and a identity certificate chain to
787 * grpc_tls_identity_pairs. This function will make an internal copy of
788 * |private_key| and |cert_chain|. It is used for experimental purpose for now
789 * and subject to change.
791 GRPCAPI void grpc_tls_identity_pairs_add_pair(grpc_tls_identity_pairs* pairs,
792 const char* private_key,
793 const char* cert_chain);
796 * Destroys a grpc_tls_identity_pairs object. If this object is passed to a
797 * provider initiation function, the ownership is transferred so this function
798 * doesn't need to be called. Otherwise the creator of the
799 * grpc_tls_identity_pairs object is responsible for its destruction. It is
800 * used for experimental purpose for now and subject to change.
802 GRPCAPI void grpc_tls_identity_pairs_destroy(grpc_tls_identity_pairs* pairs);
805 * Creates a grpc_tls_certificate_provider that will load credential data from
806 * static string during initialization. This provider will always return the
807 * same cert data for all cert names.
808 * root_certificate and pem_key_cert_pairs can be nullptr, indicating the
809 * corresponding credential data is not needed.
810 * This function will make a copy of |root_certificate|.
811 * The ownership of |pem_key_cert_pairs| is transferred.
812 * It is used for experimental purpose for now and subject to change.
814 GRPCAPI grpc_tls_certificate_provider*
815 grpc_tls_certificate_provider_static_data_create(
816 const char* root_certificate, grpc_tls_identity_pairs* pem_key_cert_pairs);
819 * Creates a grpc_tls_certificate_provider that will watch the credential
820 * changes on the file system. This provider will always return the up-to-date
821 * cert data for all the cert names callers set through
822 * |grpc_tls_credentials_options|. Note that this API only supports one key-cert
823 * file and hence one set of identity key-cert pair, so SNI(Server Name
824 * Indication) is not supported.
825 * - private_key_path is the file path of the private key. This must be set if
826 * |identity_certificate_path| is set. Otherwise, it could be null if no
827 * identity credentials are needed.
828 * - identity_certificate_path is the file path of the identity certificate
829 * chain. This must be set if |private_key_path| is set. Otherwise, it could
830 * be null if no identity credentials are needed.
831 * - root_cert_path is the file path to the root certificate bundle. This
832 * may be null if no root certs are needed.
833 * - refresh_interval_sec is the refreshing interval that we will check the
835 * It does not take ownership of parameters.
836 * It is used for experimental purpose for now and subject to change.
838 GRPCAPI grpc_tls_certificate_provider*
839 grpc_tls_certificate_provider_file_watcher_create(
840 const char* private_key_path, const char* identity_certificate_path,
841 const char* root_cert_path, unsigned int refresh_interval_sec);
844 * Releases a grpc_tls_certificate_provider object. The creator of the
845 * grpc_tls_certificate_provider object is responsible for its release. It is
846 * used for experimental purpose for now and subject to change.
848 GRPCAPI void grpc_tls_certificate_provider_release(
849 grpc_tls_certificate_provider* provider);
852 * Creates an grpc_tls_credentials_options.
853 * It is used for experimental purpose for now and subject to change.
855 GRPCAPI grpc_tls_credentials_options* grpc_tls_credentials_options_create(void);
858 * Sets the options of whether to request and verify client certs. This should
859 * be called only on the server side. It is used for experimental purpose for
860 * now and subject to change.
862 GRPCAPI void grpc_tls_credentials_options_set_cert_request_type(
863 grpc_tls_credentials_options* options,
864 grpc_ssl_client_certificate_request_type type);
867 * Sets the options of whether to choose certain checks, e.g. certificate check,
868 * hostname check, etc. This should be called only on the client side. If
869 * |server_verification_option| is not GRPC_TLS_SERVER_VERIFICATION, use of a
870 * custom authorization check (grpc_tls_server_authorization_check_config) is
871 * mandatory. It is used for experimental purpose for now and subject to change.
873 GRPCAPI void grpc_tls_credentials_options_set_server_verification_option(
874 grpc_tls_credentials_options* options,
875 grpc_tls_server_verification_option server_verification_option);
878 * Sets the credential provider in the options.
879 * The |options| will implicitly take a new ref to the |provider|.
880 * It is used for experimental purpose for now and subject to change.
882 GRPCAPI void grpc_tls_credentials_options_set_certificate_provider(
883 grpc_tls_credentials_options* options,
884 grpc_tls_certificate_provider* provider);
887 * If set, gRPC stack will keep watching the root certificates with
888 * name |root_cert_name|.
889 * If this is not set on the client side, we will use the root certificates
890 * stored in the default system location, since client side must provide root
891 * certificates in TLS.
892 * If this is not set on the server side, we will not watch any root certificate
893 * updates, and assume no root certificates needed for the server(single-side
894 * TLS). Default root certs on the server side is not supported.
895 * It is used for experimental purpose for now and subject to change.
897 GRPCAPI void grpc_tls_credentials_options_watch_root_certs(
898 grpc_tls_credentials_options* options);
901 * Sets the name of the root certificates being watched.
902 * If not set, We will use a default empty string as the root certificate name.
903 * It is used for experimental purpose for now and subject to change.
905 GRPCAPI void grpc_tls_credentials_options_set_root_cert_name(
906 grpc_tls_credentials_options* options, const char* root_cert_name);
909 * If set, gRPC stack will keep watching the identity key-cert pairs
910 * with name |identity_cert_name|.
911 * This is required on the server side, and optional on the client side.
912 * It is used for experimental purpose for now and subject to change.
914 GRPCAPI void grpc_tls_credentials_options_watch_identity_key_cert_pairs(
915 grpc_tls_credentials_options* options);
918 * Sets the name of the identity certificates being watched.
919 * If not set, We will use a default empty string as the identity certificate
920 * name. It is used for experimental purpose for now and subject to change.
922 GRPCAPI void grpc_tls_credentials_options_set_identity_cert_name(
923 grpc_tls_credentials_options* options, const char* identity_cert_name);
926 * Sets the configuration for a custom authorization check performed at the end
927 * of the handshake. The |options| will implicitly take a new ref to the
929 * It is used for experimental purpose for now and subject to change.
931 GRPCAPI void grpc_tls_credentials_options_set_server_authorization_check_config(
932 grpc_tls_credentials_options* options,
933 grpc_tls_server_authorization_check_config* config);
935 /** --- TLS server authorization check config. ---
936 * It is used for experimental purpose for now and subject to change. */
938 typedef struct grpc_tls_server_authorization_check_arg
939 grpc_tls_server_authorization_check_arg;
941 /** callback function provided by gRPC used to handle the result of server
942 authorization check. It is used when schedule API is implemented
943 asynchronously, and serves to bring the control back to gRPC C core. It is
944 used for experimental purpose for now and subject to change. */
945 typedef void (*grpc_tls_on_server_authorization_check_done_cb)(
946 grpc_tls_server_authorization_check_arg* arg);
948 /** A struct containing all information necessary to schedule/cancel a server
949 authorization check request.
950 - cb and cb_user_data represent a gRPC-provided callback and an argument
952 - success will store the result of server authorization check. That is,
953 if success returns a non-zero value, it means the authorization check
954 passes and if returning zero, it means the check fails.
955 - target_name is the name of an endpoint the channel is connecting to.
956 - peer_cert represents a complete certificate chain including both
957 signing and leaf certificates.
958 - \a subject_alternative_names is an array of size
959 \a subject_alternative_names_size consisting of pointers to strings.
960 - status and error_details contain information
961 about errors occurred when a server authorization check request is
963 - config is a pointer to the unique
964 grpc_tls_server_authorization_check_config instance that this argument
966 - context is a pointer to a wrapped language implementation of this
967 grpc_tls_server_authorization_check_arg instance.
968 - destroy_context is a pointer to a caller-provided method that cleans
969 up any data associated with the context pointer.
970 It is used for experimental purpose for now and subject to change.
972 struct grpc_tls_server_authorization_check_arg {
973 grpc_tls_on_server_authorization_check_done_cb cb;
976 const char* target_name;
977 const char* peer_cert;
978 const char* peer_cert_full_chain;
979 char** subject_alternative_names;
980 size_t subject_alternative_names_size;
981 grpc_status_code status;
982 grpc_tls_error_details* error_details;
983 grpc_tls_server_authorization_check_config* config;
985 void (*destroy_context)(void* ctx);
988 /** Create a grpc_tls_server_authorization_check_config instance.
989 - config_user_data is config-specific, read-only user data
990 that works for all channels created with a credential using the config.
991 - schedule is a pointer to an application-provided callback used to invoke
992 server authorization check API. The implementation of this method has to
993 be non-blocking, but can be performed synchronously or asynchronously.
994 1)If processing occurs synchronously, it populates arg->result,
995 arg->status, and arg->error_details and returns zero.
996 2) If processing occurs asynchronously, it returns a non-zero value. The
997 application then invokes arg->cb when processing is completed. Note that
998 arg->cb cannot be invoked before schedule API returns.
999 - cancel is a pointer to an application-provided callback used to cancel a
1000 server authorization check request scheduled via an asynchronous schedule
1001 API. arg is used to pinpoint an exact check request to be cancelled. The
1002 operation may not have any effect if the request has already been
1004 - destruct is a pointer to an application-provided callback used to clean up
1005 any data associated with the config.
1006 It is used for experimental purpose for now and subject to change.
1008 GRPCAPI grpc_tls_server_authorization_check_config*
1009 grpc_tls_server_authorization_check_config_create(
1010 const void* config_user_data,
1011 int (*schedule)(void* config_user_data,
1012 grpc_tls_server_authorization_check_arg* arg),
1013 void (*cancel)(void* config_user_data,
1014 grpc_tls_server_authorization_check_arg* arg),
1015 void (*destruct)(void* config_user_data));
1018 * Releases a grpc_tls_server_authorization_check_config object. The creator of
1019 * the grpc_tls_server_authorization_check_config object is responsible for its
1020 * release. It is used for experimental purpose for now and subject to change.
1022 GRPCAPI void grpc_tls_server_authorization_check_config_release(
1023 grpc_tls_server_authorization_check_config* config);
1026 * Creates a TLS channel credential object based on the
1027 * grpc_tls_credentials_options specified by callers. The
1028 * grpc_channel_credentials will take the ownership of the |options|. The
1029 * security level of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY. It
1030 * is used for experimental purpose for now and subject to change.
1032 grpc_channel_credentials* grpc_tls_credentials_create(
1033 grpc_tls_credentials_options* options);
1036 * Creates a TLS server credential object based on the
1037 * grpc_tls_credentials_options specified by callers. The
1038 * grpc_server_credentials will take the ownership of the |options|. It
1039 * is used for experimental purpose for now and subject to change.
1041 grpc_server_credentials* grpc_tls_server_credentials_create(
1042 grpc_tls_credentials_options* options);
1045 * EXPERIMENTAL API - Subject to change
1047 * This method creates an insecure channel credentials object.
1049 grpc_channel_credentials* grpc_insecure_credentials_create();
1052 * EXPERIMENTAL API - Subject to change
1054 * This method creates an insecure server credentials object.
1056 grpc_server_credentials* grpc_insecure_server_credentials_create();
1059 * EXPERIMENTAL API - Subject to change
1061 * This method creates an xDS channel credentials object.
1063 * Creating a channel with credentials of this type indicates that the channel
1064 * should get credentials configuration from the xDS control plane.
1066 * \a fallback_credentials are used if the channel target does not have the
1067 * 'xds:///' scheme or if the xDS control plane does not provide information on
1068 * how to fetch credentials dynamically. Does NOT take ownership of the \a
1069 * fallback_credentials. (Internally takes a ref to the object.)
1071 GRPCAPI grpc_channel_credentials* grpc_xds_credentials_create(
1072 grpc_channel_credentials* fallback_credentials);
1075 * EXPERIMENTAL API - Subject to change
1077 * This method creates an xDS server credentials object.
1079 * \a fallback_credentials are used if the xDS control plane does not provide
1080 * information on how to fetch credentials dynamically.
1082 * Does NOT take ownership of the \a fallback_credentials. (Internally takes
1083 * a ref to the object.)
1085 GRPCAPI grpc_server_credentials* grpc_xds_server_credentials_create(
1086 grpc_server_credentials* fallback_credentials);
1092 #endif /* GRPC_GRPC_SECURITY_H */