1 /* 2 * 3 * Copyright 2024 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_CREDENTIALS_H 20 #define GRPC_CREDENTIALS_H 21 22 #include <grpc/grpc.h> 23 #include <grpc/grpc_security_constants.h> 24 #include <grpc/support/port_platform.h> 25 #include <stdbool.h> 26 27 #ifdef __cplusplus 28 extern "C" { 29 #endif 30 31 /** --- grpc_call_credentials object --- 32 33 A call credentials object represents a way to authenticate on a particular 34 call. These credentials can be composed with a channel credentials object 35 so that they are sent with every call on this channel. */ 36 37 typedef struct grpc_call_credentials grpc_call_credentials; 38 typedef struct grpc_auth_context grpc_auth_context; 39 40 /** Creates a JWT credentials object. May return NULL if the input is invalid. 41 - json_key is the JSON key string containing the client's private key. 42 - token_lifetime is the lifetime of each Json Web Token (JWT) created with 43 this credentials. It should not exceed grpc_max_auth_token_lifetime or 44 will be cropped to this value. */ 45 GRPCAPI grpc_call_credentials* 46 grpc_service_account_jwt_access_credentials_create(const char* json_key, 47 gpr_timespec token_lifetime, 48 void* reserved); 49 50 /** Builds External Account credentials. 51 - json_string is the JSON string containing the credentials options. 52 - scopes_string contains the scopes to be binded with the credentials. 53 This API is used for experimental purposes for now and may change in the 54 future. */ 55 GRPCAPI grpc_call_credentials* grpc_external_account_credentials_create( 56 const char* json_string, const char* scopes_string); 57 58 /** Creates an Oauth2 Refresh Token credentials object for connecting to Google. 59 May return NULL if the input is invalid. 60 WARNING: Do NOT use this credentials to connect to a non-google service as 61 this could result in an oauth2 token leak. 62 - json_refresh_token is the JSON string containing the refresh token itself 63 along with a client_id and client_secret. */ 64 GRPCAPI grpc_call_credentials* grpc_google_refresh_token_credentials_create( 65 const char* json_refresh_token, void* reserved); 66 67 /** Creates an Oauth2 Access Token credentials with an access token that was 68 acquired by an out of band mechanism. */ 69 GRPCAPI grpc_call_credentials* grpc_access_token_credentials_create( 70 const char* access_token, void* reserved); 71 72 /** Creates an IAM credentials object for connecting to Google. */ 73 GRPCAPI grpc_call_credentials* grpc_google_iam_credentials_create( 74 const char* authorization_token, const char* authority_selector, 75 void* reserved); 76 77 /** Options for creating STS Oauth Token Exchange credentials following the IETF 78 draft https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16. 79 Optional fields may be set to NULL or empty string. It is the responsibility 80 of the caller to ensure that the subject and actor tokens are refreshed on 81 disk at the specified paths. This API is used for experimental purposes for 82 now and may change in the future. */ 83 typedef struct { 84 const char* token_exchange_service_uri; /* Required. */ 85 const char* resource; /* Optional. */ 86 const char* audience; /* Optional. */ 87 const char* scope; /* Optional. */ 88 const char* requested_token_type; /* Optional. */ 89 const char* subject_token_path; /* Required. */ 90 const char* subject_token_type; /* Required. */ 91 const char* actor_token_path; /* Optional. */ 92 const char* actor_token_type; /* Optional. */ 93 } grpc_sts_credentials_options; 94 95 /** Creates an STS credentials following the STS Token Exchanged specified in 96 the IETF draft 97 https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16. This API is 98 used for experimental purposes for now and may change in the future. */ 99 GRPCAPI grpc_call_credentials* grpc_sts_credentials_create( 100 const grpc_sts_credentials_options* options, void* reserved); 101 102 /** Context that can be used by metadata credentials plugin in order to create 103 auth related metadata. */ 104 typedef struct { 105 /** The fully qualified service url. */ 106 const char* service_url; 107 108 /** The method name of the RPC being called (not fully qualified). 109 The fully qualified method name can be built from the service_url: 110 full_qualified_method_name = ctx->service_url + '/' + ctx->method_name. */ 111 const char* method_name; 112 113 /** The auth_context of the channel which gives the server's identity. */ 114 const grpc_auth_context* channel_auth_context; 115 116 /** Reserved for future use. */ 117 void* reserved; 118 } grpc_auth_metadata_context; 119 120 /** Performs a deep copy from \a from to \a to. **/ 121 GRPCAPI void grpc_auth_metadata_context_copy(grpc_auth_metadata_context* from, 122 grpc_auth_metadata_context* to); 123 124 /** Releases internal resources held by \a context. **/ 125 GRPCAPI void grpc_auth_metadata_context_reset( 126 grpc_auth_metadata_context* context); 127 128 /** Callback function to be called by the metadata credentials plugin 129 implementation when the metadata is ready. 130 - user_data is the opaque pointer that was passed in the get_metadata method 131 of the grpc_metadata_credentials_plugin (see below). 132 - creds_md is an array of credentials metadata produced by the plugin. It 133 may be set to NULL in case of an error. 134 - num_creds_md is the number of items in the creds_md array. 135 - status must be GRPC_STATUS_OK in case of success or another specific error 136 code otherwise. 137 - error_details contains details about the error if any. In case of success 138 it should be NULL and will be otherwise ignored. */ 139 typedef void (*grpc_credentials_plugin_metadata_cb)( 140 void* user_data, const grpc_metadata* creds_md, size_t num_creds_md, 141 grpc_status_code status, const char* error_details); 142 143 /** Maximum number of metadata entries returnable by a credentials plugin via 144 a synchronous return. */ 145 #define GRPC_METADATA_CREDENTIALS_PLUGIN_SYNC_MAX 4 146 147 /** grpc_metadata_credentials plugin is an API user provided structure used to 148 create grpc_credentials objects that can be set on a channel (composed) or 149 a call. See grpc_credentials_metadata_create_from_plugin below. 150 The grpc client stack will call the get_metadata method of the plugin for 151 every call in scope for the credentials created from it. */ 152 typedef struct { 153 /** The implementation of this method has to be non-blocking, but can 154 be performed synchronously or asynchronously. 155 156 If processing occurs synchronously, returns non-zero and populates 157 creds_md, num_creds_md, status, and error_details. In this case, 158 the caller takes ownership of the entries in creds_md and of 159 error_details. Note that if the plugin needs to return more than 160 GRPC_METADATA_CREDENTIALS_PLUGIN_SYNC_MAX entries in creds_md, it must 161 return asynchronously. 162 163 If processing occurs asynchronously, returns zero and invokes \a cb 164 when processing is completed. \a user_data will be passed as the 165 first parameter of the callback. NOTE: \a cb MUST be invoked in a 166 different thread, not from the thread in which \a get_metadata() is 167 invoked. 168 169 \a context is the information that can be used by the plugin to create 170 auth metadata. */ 171 int (*get_metadata)( 172 void* state, grpc_auth_metadata_context context, 173 grpc_credentials_plugin_metadata_cb cb, void* user_data, 174 grpc_metadata creds_md[GRPC_METADATA_CREDENTIALS_PLUGIN_SYNC_MAX], 175 size_t* num_creds_md, grpc_status_code* status, 176 const char** error_details); 177 178 /** Implements debug string of the given plugin. This method returns an 179 * allocated string that the caller needs to free using gpr_free() */ 180 char* (*debug_string)(void* state); 181 182 /** Destroys the plugin state. */ 183 void (*destroy)(void* state); 184 185 /** State that will be set as the first parameter of the methods above. */ 186 void* state; 187 188 /** Type of credentials that this plugin is implementing. */ 189 const char* type; 190 } grpc_metadata_credentials_plugin; 191 192 /** Creates a credentials object from a plugin with a specified minimum security 193 * level. */ 194 GRPCAPI grpc_call_credentials* grpc_metadata_credentials_create_from_plugin( 195 grpc_metadata_credentials_plugin plugin, 196 grpc_security_level min_security_level, void* reserved); 197 198 /** --- channel credentials --- */ 199 200 /** Releases a call credentials object. 201 The creator of the credentials object is responsible for its release. */ 202 GRPCAPI void grpc_call_credentials_release(grpc_call_credentials* creds); 203 204 /** Creates default credentials to connect to a google gRPC service. 205 WARNING: Do NOT use this credentials to connect to a non-google service as 206 this could result in an oauth2 token leak. The security level of the 207 resulting connection is GRPC_PRIVACY_AND_INTEGRITY. 208 209 If specified, the supplied call credentials object will be attached to the 210 returned channel credentials object. The call_credentials object must remain 211 valid throughout the lifetime of the returned grpc_channel_credentials 212 object. It is expected that the call credentials object was generated 213 according to the Application Default Credentials mechanism and asserts the 214 identity of the default service account of the machine. Supplying any other 215 sort of call credential will result in undefined behavior, up to and 216 including the sudden and unexpected failure of RPCs. 217 218 If nullptr is supplied, the returned channel credentials object will use a 219 call credentials object based on the Application Default Credentials 220 mechanism. 221 */ 222 GRPCAPI grpc_channel_credentials* grpc_google_default_credentials_create( 223 grpc_call_credentials* call_credentials); 224 225 /** Server certificate config object holds the server's public certificates and 226 associated private keys, as well as any CA certificates needed for client 227 certificate validation (if applicable). Create using 228 grpc_ssl_server_certificate_config_create(). */ 229 typedef struct grpc_ssl_server_certificate_config 230 grpc_ssl_server_certificate_config; 231 232 /** Object that holds a private key / certificate chain pair in PEM format. */ 233 typedef struct { 234 /** private_key is the NULL-terminated string containing the PEM encoding of 235 the client's private key. */ 236 const char* private_key; 237 238 /** cert_chain is the NULL-terminated string containing the PEM encoding of 239 the client's certificate chain. */ 240 const char* cert_chain; 241 } grpc_ssl_pem_key_cert_pair; 242 243 /** Creates a grpc_ssl_server_certificate_config object. 244 - pem_roots_cert is the NULL-terminated string containing the PEM encoding of 245 the client root certificates. This parameter may be NULL if the server does 246 not want the client to be authenticated with SSL. 247 - pem_key_cert_pairs is an array private key / certificate chains of the 248 server. This parameter cannot be NULL. 249 - num_key_cert_pairs indicates the number of items in the private_key_files 250 and cert_chain_files parameters. It must be at least 1. 251 - It is the caller's responsibility to free this object via 252 grpc_ssl_server_certificate_config_destroy(). */ 253 GRPCAPI grpc_ssl_server_certificate_config* 254 grpc_ssl_server_certificate_config_create( 255 const char* pem_root_certs, 256 const grpc_ssl_pem_key_cert_pair* pem_key_cert_pairs, 257 size_t num_key_cert_pairs); 258 259 /** Destroys a grpc_ssl_server_certificate_config object. */ 260 GRPCAPI void grpc_ssl_server_certificate_config_destroy( 261 grpc_ssl_server_certificate_config* config); 262 263 /** Callback to retrieve updated SSL server certificates, private keys, and 264 trusted CAs (for client authentication). 265 - user_data parameter, if not NULL, contains opaque data to be used by the 266 callback. 267 - Use grpc_ssl_server_certificate_config_create to create the config. 268 - The caller assumes ownership of the config. */ 269 typedef grpc_ssl_certificate_config_reload_status ( 270 *grpc_ssl_server_certificate_config_callback)( 271 void* user_data, grpc_ssl_server_certificate_config** config); 272 273 /** Deprecated in favor of grpc_ssl_verify_peer_options. It will be removed 274 after all of its call sites are migrated to grpc_ssl_verify_peer_options. 275 Object that holds additional peer-verification options on a secure 276 channel. */ 277 typedef struct { 278 /** If non-NULL this callback will be invoked with the expected 279 target_name, the peer's certificate (in PEM format), and whatever 280 userdata pointer is set below. If a non-zero value is returned by this 281 callback then it is treated as a verification failure. Invocation of 282 the callback is blocking, so any implementation should be light-weight. 283 */ 284 int (*verify_peer_callback)(const char* target_name, const char* peer_pem, 285 void* userdata); 286 /** Arbitrary userdata that will be passed as the last argument to 287 verify_peer_callback. */ 288 void* verify_peer_callback_userdata; 289 /** A destruct callback that will be invoked when the channel is being 290 cleaned up. The userdata argument will be passed to it. The intent is 291 to perform any cleanup associated with that userdata. */ 292 void (*verify_peer_destruct)(void* userdata); 293 } verify_peer_options; 294 295 /** Object that holds additional peer-verification options on a secure 296 channel. */ 297 typedef struct { 298 /** If non-NULL this callback will be invoked with the expected 299 target_name, the peer's certificate (in PEM format), and whatever 300 userdata pointer is set below. If a non-zero value is returned by this 301 callback then it is treated as a verification failure. Invocation of 302 the callback is blocking, so any implementation should be light-weight. 303 */ 304 int (*verify_peer_callback)(const char* target_name, const char* peer_pem, 305 void* userdata); 306 /** Arbitrary userdata that will be passed as the last argument to 307 verify_peer_callback. */ 308 void* verify_peer_callback_userdata; 309 /** A destruct callback that will be invoked when the channel is being 310 cleaned up. The userdata argument will be passed to it. The intent is 311 to perform any cleanup associated with that userdata. */ 312 void (*verify_peer_destruct)(void* userdata); 313 } grpc_ssl_verify_peer_options; 314 315 /** Deprecated in favor of grpc_ssl_server_credentials_create_ex. It will be 316 removed after all of its call sites are migrated to 317 grpc_ssl_server_credentials_create_ex. Creates an SSL credentials object. 318 The security level of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY. 319 - pem_root_certs is the NULL-terminated string containing the PEM encoding 320 of the server root certificates. If this parameter is NULL, the 321 implementation will first try to dereference the file pointed by the 322 GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment variable, and if that fails, 323 try to get the roots set by grpc_override_ssl_default_roots. Eventually, 324 if all these fail, it will try to get the roots from a well-known place on 325 disk (in the grpc install directory). 326 327 gRPC has implemented root cache if the underlying OpenSSL library supports 328 it. The gRPC root certificates cache is only applicable on the default 329 root certificates, which is used when this parameter is nullptr. If user 330 provides their own pem_root_certs, when creating an SSL credential object, 331 gRPC would not be able to cache it, and each subchannel will generate a 332 copy of the root store. So it is recommended to avoid providing large room 333 pem with pem_root_certs parameter to avoid excessive memory consumption, 334 particularly on mobile platforms such as iOS. 335 - pem_key_cert_pair is a pointer on the object containing client's private 336 key and certificate chain. This parameter can be NULL if the client does 337 not have such a key/cert pair. 338 - verify_options is an optional verify_peer_options object which holds 339 additional options controlling how peer certificates are verified. For 340 example, you can supply a callback which receives the peer's certificate 341 with which you can do additional verification. Can be NULL, in which 342 case verification will retain default behavior. Any settings in 343 verify_options are copied during this call, so the verify_options 344 object can be released afterwards. */ 345 GRPCAPI grpc_channel_credentials* grpc_ssl_credentials_create( 346 const char* pem_root_certs, grpc_ssl_pem_key_cert_pair* pem_key_cert_pair, 347 const verify_peer_options* verify_options, void* reserved); 348 349 /* Creates an SSL credentials object. 350 The security level of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY. 351 - pem_root_certs is the NULL-terminated string containing the PEM encoding 352 of the server root certificates. If this parameter is NULL, the 353 implementation will first try to dereference the file pointed by the 354 GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment variable, and if that fails, 355 try to get the roots set by grpc_override_ssl_default_roots. Eventually, 356 if all these fail, it will try to get the roots from a well-known place on 357 disk (in the grpc install directory). 358 359 gRPC has implemented root cache if the underlying OpenSSL library supports 360 it. The gRPC root certificates cache is only applicable on the default 361 root certificates, which is used when this parameter is nullptr. If user 362 provides their own pem_root_certs, when creating an SSL credential object, 363 gRPC would not be able to cache it, and each subchannel will generate a 364 copy of the root store. So it is recommended to avoid providing large room 365 pem with pem_root_certs parameter to avoid excessive memory consumption, 366 particularly on mobile platforms such as iOS. 367 - pem_key_cert_pair is a pointer on the object containing client's private 368 key and certificate chain. This parameter can be NULL if the client does 369 not have such a key/cert pair. 370 - verify_options is an optional verify_peer_options object which holds 371 additional options controlling how peer certificates are verified. For 372 example, you can supply a callback which receives the peer's certificate 373 with which you can do additional verification. Can be NULL, in which 374 case verification will retain default behavior. Any settings in 375 verify_options are copied during this call, so the verify_options 376 object can be released afterwards. */ 377 GRPCAPI grpc_channel_credentials* grpc_ssl_credentials_create_ex( 378 const char* pem_root_certs, grpc_ssl_pem_key_cert_pair* pem_key_cert_pair, 379 const grpc_ssl_verify_peer_options* verify_options, void* reserved); 380 381 /** --- server credentials --- */ 382 383 /** Deprecated in favor of grpc_ssl_server_credentials_create_ex. 384 Creates an SSL server_credentials object. 385 - pem_roots_cert is the NULL-terminated string containing the PEM encoding of 386 the client root certificates. This parameter may be NULL if the server does 387 not want the client to be authenticated with SSL. 388 - pem_key_cert_pairs is an array private key / certificate chains of the 389 server. This parameter cannot be NULL. 390 - num_key_cert_pairs indicates the number of items in the private_key_files 391 and cert_chain_files parameters. It should be at least 1. 392 - force_client_auth, if set to non-zero will force the client to authenticate 393 with an SSL cert. Note that this option is ignored if pem_root_certs is 394 NULL. */ 395 GRPCAPI grpc_server_credentials* grpc_ssl_server_credentials_create( 396 const char* pem_root_certs, grpc_ssl_pem_key_cert_pair* pem_key_cert_pairs, 397 size_t num_key_cert_pairs, int force_client_auth, void* reserved); 398 399 /** Deprecated in favor of grpc_ssl_server_credentials_create_with_options. 400 Same as grpc_ssl_server_credentials_create method except uses 401 grpc_ssl_client_certificate_request_type enum to support more ways to 402 authenticate client certificates.*/ 403 GRPCAPI grpc_server_credentials* grpc_ssl_server_credentials_create_ex( 404 const char* pem_root_certs, grpc_ssl_pem_key_cert_pair* pem_key_cert_pairs, 405 size_t num_key_cert_pairs, 406 grpc_ssl_client_certificate_request_type client_certificate_request, 407 void* reserved); 408 409 typedef struct grpc_ssl_server_credentials_options 410 grpc_ssl_server_credentials_options; 411 412 /** Creates an options object using a certificate config. Use this method when 413 the certificates and keys of the SSL server will not change during the 414 server's lifetime. 415 - Takes ownership of the certificate_config parameter. */ 416 GRPCAPI grpc_ssl_server_credentials_options* 417 grpc_ssl_server_credentials_create_options_using_config( 418 grpc_ssl_client_certificate_request_type client_certificate_request, 419 grpc_ssl_server_certificate_config* certificate_config); 420 421 /** Creates an options object using a certificate config fetcher. Use this 422 method to reload the certificates and keys of the SSL server without 423 interrupting the operation of the server. Initial certificate config will be 424 fetched during server initialization. 425 - user_data parameter, if not NULL, contains opaque data which will be passed 426 to the fetcher (see definition of 427 grpc_ssl_server_certificate_config_callback). */ 428 GRPCAPI grpc_ssl_server_credentials_options* 429 grpc_ssl_server_credentials_create_options_using_config_fetcher( 430 grpc_ssl_client_certificate_request_type client_certificate_request, 431 grpc_ssl_server_certificate_config_callback cb, void* user_data); 432 433 /** Destroys a grpc_ssl_server_credentials_options object. */ 434 GRPCAPI void grpc_ssl_server_credentials_options_destroy( 435 grpc_ssl_server_credentials_options* options); 436 437 /** Creates an SSL server_credentials object using the provided options struct. 438 - Takes ownership of the options parameter. */ 439 GRPCAPI grpc_server_credentials* 440 grpc_ssl_server_credentials_create_with_options( 441 grpc_ssl_server_credentials_options* options); 442 443 /** --- Auth Metadata Processing --- */ 444 445 /** Callback function that is called when the metadata processing is done. 446 - Consumed metadata will be removed from the set of metadata available on the 447 call. consumed_md may be NULL if no metadata has been consumed. 448 - Response metadata will be set on the response. response_md may be NULL. 449 - status is GRPC_STATUS_OK for success or a specific status for an error. 450 Common error status for auth metadata processing is either 451 GRPC_STATUS_UNAUTHENTICATED in case of an authentication failure or 452 GRPC_STATUS PERMISSION_DENIED in case of an authorization failure. 453 - error_details gives details about the error. May be NULL. */ 454 typedef void (*grpc_process_auth_metadata_done_cb)( 455 void* user_data, const grpc_metadata* consumed_md, size_t num_consumed_md, 456 const grpc_metadata* response_md, size_t num_response_md, 457 grpc_status_code status, const char* error_details); 458 459 /** Pluggable server-side metadata processor object. */ 460 typedef struct { 461 /** The context object is read/write: it contains the properties of the 462 channel peer and it is the job of the process function to augment it with 463 properties derived from the passed-in metadata. 464 The lifetime of these objects is guaranteed until cb is invoked. */ 465 void (*process)(void* state, grpc_auth_context* context, 466 const grpc_metadata* md, size_t num_md, 467 grpc_process_auth_metadata_done_cb cb, void* user_data); 468 void (*destroy)(void* state); 469 void* state; 470 } grpc_auth_metadata_processor; 471 472 GRPCAPI void grpc_server_credentials_set_auth_metadata_processor( 473 grpc_server_credentials* creds, grpc_auth_metadata_processor processor); 474 475 /** --- composite credentials --- */ 476 477 /** Creates a composite call credentials object. */ 478 GRPCAPI grpc_call_credentials* grpc_composite_call_credentials_create( 479 grpc_call_credentials* creds1, grpc_call_credentials* creds2, 480 void* reserved); 481 482 /** Creates a compute engine credentials object for connecting to Google. 483 WARNING: Do NOT use this credentials to connect to a non-google service as 484 this could result in an oauth2 token leak. */ 485 GRPCAPI grpc_call_credentials* grpc_google_compute_engine_credentials_create( 486 void* reserved); 487 488 /** Creates a composite channel credentials object. The security level of 489 * resulting connection is determined by channel_creds. */ 490 GRPCAPI grpc_channel_credentials* grpc_composite_channel_credentials_create( 491 grpc_channel_credentials* channel_creds, grpc_call_credentials* call_creds, 492 void* reserved); 493 494 /** --- ALTS channel/server credentials --- **/ 495 496 /** 497 * Main interface for ALTS credentials options. The options will contain 498 * information that will be passed from grpc to TSI layer such as RPC protocol 499 * versions. ALTS client (channel) and server credentials will have their own 500 * implementation of this interface. The APIs listed in this header are 501 * thread-compatible. It is used for experimental purpose for now and subject 502 * to change. 503 */ 504 typedef struct grpc_alts_credentials_options grpc_alts_credentials_options; 505 506 /** 507 * This method creates a grpc ALTS credentials client options instance. 508 * It is used for experimental purpose for now and subject to change. 509 */ 510 GRPCAPI grpc_alts_credentials_options* 511 grpc_alts_credentials_client_options_create(void); 512 513 /** 514 * This method creates a grpc ALTS credentials server options instance. 515 * It is used for experimental purpose for now and subject to change. 516 */ 517 GRPCAPI grpc_alts_credentials_options* 518 grpc_alts_credentials_server_options_create(void); 519 520 /** 521 * This method adds a target service account to grpc client's ALTS credentials 522 * options instance. It is used for experimental purpose for now and subject 523 * to change. 524 * 525 * - options: grpc ALTS credentials options instance. 526 * - service_account: service account of target endpoint. 527 */ 528 GRPCAPI void grpc_alts_credentials_client_options_add_target_service_account( 529 grpc_alts_credentials_options* options, const char* service_account); 530 531 /** 532 * This method destroys a grpc_alts_credentials_options instance by 533 * de-allocating all of its occupied memory. It is used for experimental purpose 534 * for now and subject to change. 535 * 536 * - options: a grpc_alts_credentials_options instance that needs to be 537 * destroyed. 538 */ 539 GRPCAPI void grpc_alts_credentials_options_destroy( 540 grpc_alts_credentials_options* options); 541 542 /** 543 * This method creates an ALTS channel credential object. The security 544 * level of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY. 545 * It is used for experimental purpose for now and subject to change. 546 * 547 * - options: grpc ALTS credentials options instance for client. 548 * 549 * It returns the created ALTS channel credential object. 550 */ 551 GRPCAPI grpc_channel_credentials* grpc_alts_credentials_create( 552 const grpc_alts_credentials_options* options); 553 554 /** 555 * This method creates an ALTS server credential object. It is used for 556 * experimental purpose for now and subject to change. 557 * 558 * - options: grpc ALTS credentials options instance for server. 559 * 560 * It returns the created ALTS server credential object. 561 */ 562 GRPCAPI grpc_server_credentials* grpc_alts_server_credentials_create( 563 const grpc_alts_credentials_options* options); 564 565 /** 566 * EXPERIMENTAL API - Subject to change 567 * 568 * A struct that can be specified by callers to configure underlying TLS 569 * behaviors. 570 */ 571 typedef struct grpc_tls_credentials_options grpc_tls_credentials_options; 572 573 /** --- TLS channel/server credentials --- 574 * It is used for experimental purpose for now and subject to change. */ 575 576 /** 577 * EXPERIMENTAL API - Subject to change 578 * 579 * A struct provides ways to gain credential data that will be used in the TLS 580 * handshake. 581 */ 582 typedef struct grpc_tls_certificate_provider grpc_tls_certificate_provider; 583 584 /** 585 * EXPERIMENTAL API - Subject to change 586 * 587 * A struct that stores the credential data presented to the peer in handshake 588 * to show local identity. 589 */ 590 typedef struct grpc_tls_identity_pairs grpc_tls_identity_pairs; 591 592 /** 593 * EXPERIMENTAL API - Subject to change 594 * 595 * Creates a grpc_tls_identity_pairs that stores a list of identity credential 596 * data, including identity private key and identity certificate chain. 597 */ 598 GRPCAPI grpc_tls_identity_pairs* grpc_tls_identity_pairs_create(); 599 600 /** 601 * EXPERIMENTAL API - Subject to change 602 * 603 * Adds a identity private key and a identity certificate chain to 604 * grpc_tls_identity_pairs. This function will make an internal copy of 605 * |private_key| and |cert_chain|. 606 */ 607 GRPCAPI void grpc_tls_identity_pairs_add_pair(grpc_tls_identity_pairs* pairs, 608 const char* private_key, 609 const char* cert_chain); 610 611 /** 612 * EXPERIMENTAL API - Subject to change 613 * 614 * Destroys a grpc_tls_identity_pairs object. If this object is passed to a 615 * provider initiation function, the ownership is transferred so this function 616 * doesn't need to be called. Otherwise the creator of the 617 * grpc_tls_identity_pairs object is responsible for its destruction. 618 */ 619 GRPCAPI void grpc_tls_identity_pairs_destroy(grpc_tls_identity_pairs* pairs); 620 621 /** 622 * EXPERIMENTAL API - Subject to change 623 * 624 * Creates a grpc_tls_certificate_provider that will load credential data from 625 * static string during initialization. This provider will always return the 626 * same cert data for all cert names. 627 * root_certificate and pem_key_cert_pairs can be nullptr, indicating the 628 * corresponding credential data is not needed. 629 * This function will make a copy of |root_certificate|. 630 * The ownership of |pem_key_cert_pairs| is transferred. 631 */ 632 GRPCAPI grpc_tls_certificate_provider* 633 grpc_tls_certificate_provider_static_data_create( 634 const char* root_certificate, grpc_tls_identity_pairs* pem_key_cert_pairs); 635 636 /** 637 * EXPERIMENTAL API - Subject to change 638 * 639 * Creates a grpc_tls_certificate_provider that will watch the credential 640 * changes on the file system. This provider will always return the up-to-date 641 * cert data for all the cert names callers set through 642 * |grpc_tls_credentials_options|. Note that this API only supports one key-cert 643 * file and hence one set of identity key-cert pair, so SNI(Server Name 644 * Indication) is not supported. 645 * - private_key_path is the file path of the private key. This must be set if 646 * |identity_certificate_path| is set. Otherwise, it could be null if no 647 * identity credentials are needed. 648 * - identity_certificate_path is the file path of the identity certificate 649 * chain. This must be set if |private_key_path| is set. Otherwise, it could 650 * be null if no identity credentials are needed. 651 * - root_cert_path is the file path to the root certificate bundle. This 652 * may be null if no root certs are needed. 653 * - refresh_interval_sec is the refreshing interval that we will check the 654 * files for updates. 655 * It does not take ownership of parameters. 656 */ 657 GRPCAPI grpc_tls_certificate_provider* 658 grpc_tls_certificate_provider_file_watcher_create( 659 const char* private_key_path, const char* identity_certificate_path, 660 const char* root_cert_path, unsigned int refresh_interval_sec); 661 662 /** 663 * EXPERIMENTAL API - Subject to change 664 * 665 * Releases a grpc_tls_certificate_provider object. The creator of the 666 * grpc_tls_certificate_provider object is responsible for its release. 667 */ 668 GRPCAPI void grpc_tls_certificate_provider_release( 669 grpc_tls_certificate_provider* provider); 670 671 /** 672 * EXPERIMENTAL API - Subject to change 673 * 674 * The read-only request information exposed in a verification call. 675 * Callers should not directly manage the ownership of it. We will make sure it 676 * is always available inside verify() or cancel() call, and will destroy the 677 * object at the end of custom verification. 678 */ 679 typedef struct grpc_tls_custom_verification_check_request { 680 /* The target name of the server when the client initiates the connection. */ 681 /* This field will be nullptr if on the server side. */ 682 const char* target_name; 683 /* The information contained in the certificate chain sent from the peer. */ 684 struct peer_info { 685 /* The Common Name field on the peer leaf certificate. */ 686 const char* common_name; 687 /* The list of Subject Alternative Names on the peer leaf certificate. */ 688 struct san_names { 689 char** uri_names; 690 size_t uri_names_size; 691 char** dns_names; 692 size_t dns_names_size; 693 char** email_names; 694 size_t email_names_size; 695 char** ip_names; 696 size_t ip_names_size; 697 } san_names; 698 /* The raw peer leaf certificate. */ 699 const char* peer_cert; 700 /* The raw peer certificate chain. Note that it is not always guaranteed to 701 * get the peer full chain. For more, please refer to 702 * GRPC_X509_PEM_CERT_CHAIN_PROPERTY_NAME defined in file 703 * grpc_security_constants.h. 704 * TODO(ZhenLian): Consider fixing this in the future. */ 705 const char* peer_cert_full_chain; 706 /* The verified root cert subject. 707 * This value will only be filled if the cryptographic peer certificate 708 * verification was successful */ 709 const char* verified_root_cert_subject; 710 } peer_info; 711 } grpc_tls_custom_verification_check_request; 712 713 /** 714 * EXPERIMENTAL API - Subject to change 715 * 716 * A callback function provided by gRPC as a parameter of the |verify| function 717 * in grpc_tls_certificate_verifier_external. If |verify| is expected to be run 718 * asynchronously, the implementer of |verify| will need to invoke this callback 719 * with |callback_arg| and proper verification status at the end to bring the 720 * control back to gRPC C core. 721 */ 722 typedef void (*grpc_tls_on_custom_verification_check_done_cb)( 723 grpc_tls_custom_verification_check_request* request, void* callback_arg, 724 grpc_status_code status, const char* error_details); 725 726 /** 727 * EXPERIMENTAL API - Subject to change 728 * 729 * The internal verifier type that will be used inside core. 730 */ 731 typedef struct grpc_tls_certificate_verifier grpc_tls_certificate_verifier; 732 733 /** 734 * EXPERIMENTAL API - Subject to change 735 * 736 * A struct containing all the necessary functions a custom external verifier 737 * needs to implement to be able to be converted to an internal verifier. 738 */ 739 typedef struct grpc_tls_certificate_verifier_external { 740 void* user_data; 741 /** 742 * A function pointer containing the verification logic that will be 743 * performed after the TLS handshake is done. It could be processed 744 * synchronously or asynchronously. 745 * - If expected to be processed synchronously, the implementer should 746 * populate the verification result through |sync_status| and 747 * |sync_error_details|, and then return true. 748 * - If expected to be processed asynchronously, the implementer should return 749 * false immediately, and then in the asynchronous thread invoke |callback| 750 * with the verification result. The implementer MUST NOT invoke the async 751 * |callback| in the same thread before |verify| returns, otherwise it can 752 * lead to deadlocks. 753 * 754 * user_data: any argument that is passed in the user_data of 755 * grpc_tls_certificate_verifier_external during construction time 756 * can be retrieved later here. 757 * request: request information exposed to the function implementer. 758 * callback: the callback that the function implementer needs to invoke, if 759 * return a non-zero value. It is usually invoked when the 760 * asynchronous verification is done, and serves to bring the 761 * control back to gRPC. 762 * callback_arg: A pointer to the internal ExternalVerifier instance. This is 763 * mainly used as an argument in |callback|, if want to invoke 764 * |callback| in async mode. 765 * sync_status: indicates if a connection should be allowed. This should only 766 * be used if the verification check is done synchronously. 767 * sync_error_details: the error generated while verifying a connection. This 768 * should only be used if the verification check is done 769 * synchronously. the implementation must allocate the 770 * error string via gpr_malloc() or gpr_strdup(). 771 * return: return 0 if |verify| is expected to be executed asynchronously, 772 * otherwise return a non-zero value. 773 */ 774 int (*verify)(void* user_data, 775 grpc_tls_custom_verification_check_request* request, 776 grpc_tls_on_custom_verification_check_done_cb callback, 777 void* callback_arg, grpc_status_code* sync_status, 778 char** sync_error_details); 779 /** 780 * A function pointer that cleans up the caller-specified resources when the 781 * verifier is still running but the whole connection got cancelled. This 782 * could happen when the verifier is doing some async operations, and the 783 * whole handshaker object got destroyed because of connection time limit is 784 * reached, or any other reasons. In such cases, function implementers might 785 * want to be notified, and properly clean up some resources. 786 * 787 * user_data: any argument that is passed in the user_data of 788 * grpc_tls_certificate_verifier_external during construction time 789 * can be retrieved later here. 790 * request: request information exposed to the function implementer. It will 791 * be the same request object that was passed to verify(), and it 792 * tells the cancel() which request to cancel. 793 */ 794 void (*cancel)(void* user_data, 795 grpc_tls_custom_verification_check_request* request); 796 /** 797 * A function pointer that does some additional destruction work when the 798 * verifier is destroyed. This is used when the caller wants to associate some 799 * objects to the lifetime of external_verifier, and destroy them when 800 * external_verifier got destructed. For example, in C++, the class containing 801 * user-specified callback functions should not be destroyed before 802 * external_verifier, since external_verifier will invoke them while being 803 * used. 804 * Note that the caller MUST delete the grpc_tls_certificate_verifier_external 805 * object itself in this function, otherwise it will cause memory leaks. That 806 * also means the user_data has to carries at least a self pointer, for the 807 * callers to later delete it in destruct(). 808 * 809 * user_data: any argument that is passed in the user_data of 810 * grpc_tls_certificate_verifier_external during construction time 811 * can be retrieved later here. 812 */ 813 void (*destruct)(void* user_data); 814 } grpc_tls_certificate_verifier_external; 815 816 /** 817 * EXPERIMENTAL API - Subject to change 818 * 819 * Converts an external verifier to an internal verifier. 820 * Note that we will not take the ownership of the external_verifier. Callers 821 * will need to delete external_verifier in its own destruct function. 822 */ 823 grpc_tls_certificate_verifier* grpc_tls_certificate_verifier_external_create( 824 grpc_tls_certificate_verifier_external* external_verifier); 825 826 /** 827 * EXPERIMENTAL API - Subject to change 828 * 829 * Factory function for an internal verifier that won't perform any 830 * post-handshake verification. Note: using this solely without any other 831 * authentication mechanisms on the peer identity will leave your applications 832 * to the MITM(Man-In-The-Middle) attacks. Users should avoid doing so in 833 * production environments. 834 */ 835 grpc_tls_certificate_verifier* grpc_tls_certificate_verifier_no_op_create(); 836 837 /** 838 * EXPERIMENTAL API - Subject to change 839 * 840 * Factory function for an internal verifier that will do the default hostname 841 * check. 842 */ 843 grpc_tls_certificate_verifier* grpc_tls_certificate_verifier_host_name_create(); 844 845 /** 846 * EXPERIMENTAL API - Subject to change 847 * 848 * Releases a grpc_tls_certificate_verifier object. The creator of the 849 * grpc_tls_certificate_verifier object is responsible for its release. 850 */ 851 void grpc_tls_certificate_verifier_release( 852 grpc_tls_certificate_verifier* verifier); 853 854 /** 855 * EXPERIMENTAL API - Subject to change 856 * 857 * Performs the verification logic of an internal verifier. 858 * This is typically used when composing the internal verifiers as part of the 859 * custom verification. 860 * If |grpc_tls_certificate_verifier_verify| returns true, inspect the 861 * verification result through request->status and request->error_details. 862 * Otherwise, inspect through the parameter of |callback|. 863 */ 864 int grpc_tls_certificate_verifier_verify( 865 grpc_tls_certificate_verifier* verifier, 866 grpc_tls_custom_verification_check_request* request, 867 grpc_tls_on_custom_verification_check_done_cb callback, void* callback_arg, 868 grpc_status_code* sync_status, char** sync_error_details); 869 870 /** 871 * EXPERIMENTAL API - Subject to change 872 * 873 * Performs the cancellation logic of an internal verifier. 874 * This is typically used when composing the internal verifiers as part of the 875 * custom verification. 876 */ 877 void grpc_tls_certificate_verifier_cancel( 878 grpc_tls_certificate_verifier* verifier, 879 grpc_tls_custom_verification_check_request* request); 880 881 /** 882 * EXPERIMENTAL API - Subject to change 883 * 884 * Creates an grpc_tls_credentials_options. 885 */ 886 GRPCAPI grpc_tls_credentials_options* grpc_tls_credentials_options_create(void); 887 888 /** 889 * EXPERIMENTAL API - Subject to change 890 * 891 * Creates a TLS channel credential object based on the 892 * grpc_tls_credentials_options specified by callers. The 893 * grpc_channel_credentials will take the ownership of the |options|. The 894 * security level of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY. 895 */ 896 grpc_channel_credentials* grpc_tls_credentials_create( 897 grpc_tls_credentials_options* options); 898 899 /** 900 * EXPERIMENTAL API - Subject to change 901 * 902 * Creates a TLS server credential object based on the 903 * grpc_tls_credentials_options specified by callers. The 904 * grpc_server_credentials will take the ownership of the |options|. 905 */ 906 grpc_server_credentials* grpc_tls_server_credentials_create( 907 grpc_tls_credentials_options* options); 908 909 /** 910 * EXPERIMENTAL API - Subject to change 911 * 912 * Sets the minimum TLS version that will be negotiated during the TLS 913 * handshake. If not set, the underlying SSL library will set it to TLS v1.2. 914 */ 915 GRPCAPI void grpc_tls_credentials_options_set_min_tls_version( 916 grpc_tls_credentials_options* options, grpc_tls_version min_tls_version); 917 918 /** 919 * EXPERIMENTAL API - Subject to change 920 * 921 * Sets the maximum TLS version that will be negotiated during the TLS 922 * handshake. If not set, the underlying SSL library will set it to TLS v1.3. 923 */ 924 GRPCAPI void grpc_tls_credentials_options_set_max_tls_version( 925 grpc_tls_credentials_options* options, grpc_tls_version max_tls_version); 926 927 /** 928 * EXPERIMENTAL API - Subject to change 929 * 930 * Copies a grpc_tls_credentials_options. 931 */ 932 GRPCAPI grpc_tls_credentials_options* grpc_tls_credentials_options_copy( 933 grpc_tls_credentials_options* options); 934 935 /** 936 * EXPERIMENTAL API - Subject to change 937 * 938 * Destroys a grpc_tls_credentials_options. 939 */ 940 GRPCAPI void grpc_tls_credentials_options_destroy( 941 grpc_tls_credentials_options* options); 942 943 /** 944 * EXPERIMENTAL API - Subject to change 945 * 946 * A struct provides ways to gain credential data that will be used in the TLS 947 * handshake. 948 */ 949 typedef struct grpc_tls_certificate_provider grpc_tls_certificate_provider; 950 951 /** 952 * EXPERIMENTAL API - Subject to change 953 * 954 * Sets the credential provider in the options. 955 * The |options| will implicitly take a new ref to the |provider|. 956 */ 957 GRPCAPI void grpc_tls_credentials_options_set_certificate_provider( 958 grpc_tls_credentials_options* options, 959 grpc_tls_certificate_provider* provider); 960 961 /** 962 * EXPERIMENTAL API - Subject to change 963 * 964 * If set, gRPC stack will keep watching the root certificates with 965 * name |root_cert_name|. 966 * If this is not set on the client side, we will use the root certificates 967 * stored in the default system location, since client side must provide root 968 * certificates in TLS. 969 * If this is not set on the server side, we will not watch any root certificate 970 * updates, and assume no root certificates needed for the server(single-side 971 * TLS). Default root certs on the server side is not supported. 972 */ 973 GRPCAPI void grpc_tls_credentials_options_watch_root_certs( 974 grpc_tls_credentials_options* options); 975 976 /** 977 * EXPERIMENTAL API - Subject to change 978 * 979 * Sets the name of the root certificates being watched. 980 * If not set, We will use a default empty string as the root certificate name. 981 */ 982 GRPCAPI void grpc_tls_credentials_options_set_root_cert_name( 983 grpc_tls_credentials_options* options, const char* root_cert_name); 984 985 /** 986 * EXPERIMENTAL API - Subject to change 987 * 988 * If set, gRPC stack will keep watching the identity key-cert pairs 989 * with name |identity_cert_name|. 990 * This is required on the server side, and optional on the client side. 991 */ 992 GRPCAPI void grpc_tls_credentials_options_watch_identity_key_cert_pairs( 993 grpc_tls_credentials_options* options); 994 995 /** 996 * EXPERIMENTAL API - Subject to change 997 * 998 * Sets the name of the identity certificates being watched. 999 * If not set, We will use a default empty string as the identity certificate 1000 * name. 1001 */ 1002 GRPCAPI void grpc_tls_credentials_options_set_identity_cert_name( 1003 grpc_tls_credentials_options* options, const char* identity_cert_name); 1004 1005 /** 1006 * EXPERIMENTAL API - Subject to change 1007 * 1008 * Sets the options of whether to request and/or verify client certs. This shall 1009 * only be called on the server side. 1010 */ 1011 GRPCAPI void grpc_tls_credentials_options_set_cert_request_type( 1012 grpc_tls_credentials_options* options, 1013 grpc_ssl_client_certificate_request_type type); 1014 1015 /** Deprecated in favor of grpc_tls_credentials_options_set_crl_provider. The 1016 * crl provider interface provides a significantly more flexible approach to 1017 * using CRLs. See gRFC A69 for details. 1018 * EXPERIMENTAL API - Subject to change 1019 * 1020 * If set, gRPC will read all hashed x.509 CRL files in the directory and 1021 * enforce the CRL files on all TLS handshakes. Only supported for OpenSSL 1022 * version > 1.1. 1023 * It is used for experimental purpose for now and subject to change. 1024 */ 1025 GRPCAPI void grpc_tls_credentials_options_set_crl_directory( 1026 grpc_tls_credentials_options* options, const char* crl_directory); 1027 1028 /** 1029 * EXPERIMENTAL API - Subject to change 1030 * 1031 * Sets the options of whether to verify server certs on the client side. 1032 * Passing in a non-zero value indicates verifying the certs. 1033 */ 1034 GRPCAPI void grpc_tls_credentials_options_set_verify_server_cert( 1035 grpc_tls_credentials_options* options, int verify_server_cert); 1036 1037 /** 1038 * EXPERIMENTAL API - Subject to change 1039 * 1040 * Sets whether or not a TLS server should send a list of CA names in the 1041 * ServerHello. This list of CA names is read from the server's trust bundle, so 1042 * that the client can use this list as a hint to know which certificate it 1043 * should send to the server. 1044 * 1045 * WARNING: This API is extremely dangerous and should not be used. If the 1046 * server's trust bundle is too large, then the TLS server will be unable to 1047 * form a ServerHello, and hence will be unusable. The definition of "too large" 1048 * depends on the underlying SSL library being used and on the size of the CN 1049 * fields of the certificates in the trust bundle. 1050 */ 1051 GRPCAPI void grpc_tls_credentials_options_set_send_client_ca_list( 1052 grpc_tls_credentials_options* options, bool send_client_ca_list); 1053 1054 /** --- SSL Session Cache. --- 1055 1056 A SSL session cache object represents a way to cache client sessions 1057 between connections. Only ticket-based resumption is supported. */ 1058 1059 typedef struct grpc_ssl_session_cache grpc_ssl_session_cache; 1060 1061 /** Create LRU cache for client-side SSL sessions with the given capacity. 1062 If capacity is < 1, a default capacity is used instead. */ 1063 GRPCAPI grpc_ssl_session_cache* grpc_ssl_session_cache_create_lru( 1064 size_t capacity); 1065 1066 /** Destroy SSL session cache. */ 1067 GRPCAPI void grpc_ssl_session_cache_destroy(grpc_ssl_session_cache* cache); 1068 1069 /** Create a channel arg with the given cache object. */ 1070 GRPCAPI grpc_arg 1071 grpc_ssl_session_cache_create_channel_arg(grpc_ssl_session_cache* cache); 1072 1073 /** Callback for getting the SSL roots override from the application. 1074 In case of success, *pem_roots_certs must be set to a NULL terminated string 1075 containing the list of PEM encoded root certificates. The ownership is passed 1076 to the core and freed (laster by the core) with gpr_free. 1077 If this function fails and GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment is 1078 set to a valid path, it will override the roots specified this func */ 1079 typedef grpc_ssl_roots_override_result (*grpc_ssl_roots_override_callback)( 1080 char** pem_root_certs); 1081 1082 /** Setup a callback to override the default TLS/SSL roots. 1083 This function is not thread-safe and must be called at initialization time 1084 before any ssl credentials are created to have the desired side effect. 1085 If GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment is set to a valid path, the 1086 callback will not be called. */ 1087 GRPCAPI void grpc_set_ssl_roots_override_callback( 1088 grpc_ssl_roots_override_callback cb); 1089 1090 GRPCAPI gpr_timespec grpc_max_auth_token_lifetime(void); 1091 1092 /** --- insecure credentials --- */ 1093 1094 /** 1095 * EXPERIMENTAL API - Subject to change 1096 * 1097 * This method creates an insecure channel credentials object. 1098 */ 1099 GRPCAPI grpc_channel_credentials* grpc_insecure_credentials_create(); 1100 1101 /** 1102 * EXPERIMENTAL API - Subject to change 1103 * 1104 * This method creates an insecure server credentials object. 1105 */ 1106 GRPCAPI grpc_server_credentials* grpc_insecure_server_credentials_create(); 1107 1108 /** 1109 * EXPERIMENTAL API - Subject to change 1110 * 1111 * This method creates an xDS channel credentials object. 1112 * 1113 * Creating a channel with credentials of this type indicates that the channel 1114 * should get credentials configuration from the xDS control plane. 1115 * 1116 * \a fallback_credentials are used if the channel target does not have the 1117 * 'xds:///' scheme or if the xDS control plane does not provide information on 1118 * how to fetch credentials dynamically. Does NOT take ownership of the \a 1119 * fallback_credentials. (Internally takes a ref to the object.) 1120 */ 1121 GRPCAPI grpc_channel_credentials* grpc_xds_credentials_create( 1122 grpc_channel_credentials* fallback_credentials); 1123 1124 /** 1125 * EXPERIMENTAL API - Subject to change 1126 * 1127 * This method creates an xDS server credentials object. 1128 * 1129 * \a fallback_credentials are used if the xDS control plane does not provide 1130 * information on how to fetch credentials dynamically. 1131 * 1132 * Does NOT take ownership of the \a fallback_credentials. (Internally takes 1133 * a ref to the object.) 1134 */ 1135 GRPCAPI grpc_server_credentials* grpc_xds_server_credentials_create( 1136 grpc_server_credentials* fallback_credentials); 1137 1138 /** --- Local channel/server credentials --- **/ 1139 1140 /** 1141 * This method creates a local channel credential object. The security level 1142 * of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY for UDS and 1143 * GRPC_SECURITY_NONE for LOCAL_TCP. It is used for experimental purpose 1144 * for now and subject to change. 1145 * 1146 * - type: local connection type 1147 * 1148 * It returns the created local channel credential object. 1149 */ 1150 GRPCAPI grpc_channel_credentials* grpc_local_credentials_create( 1151 grpc_local_connect_type type); 1152 1153 /** 1154 * This method creates a local server credential object. It is used for 1155 * experimental purpose for now and subject to change. 1156 * 1157 * - type: local connection type 1158 * 1159 * It returns the created local server credential object. 1160 */ 1161 GRPCAPI grpc_server_credentials* grpc_local_server_credentials_create( 1162 grpc_local_connect_type type); 1163 1164 /** 1165 * EXPERIMENTAL API - Subject to change 1166 * 1167 * The internal verifier type that will be used inside core. 1168 */ 1169 typedef struct grpc_tls_certificate_verifier grpc_tls_certificate_verifier; 1170 1171 /** 1172 * EXPERIMENTAL API - Subject to change 1173 * 1174 * Sets the verifier in options. The |options| will implicitly take a new ref to 1175 * the |verifier|. If not set on the client side, we will verify server's 1176 * certificates, and check the default hostname. If not set on the server side, 1177 * we will verify client's certificates. 1178 */ 1179 void grpc_tls_credentials_options_set_certificate_verifier( 1180 grpc_tls_credentials_options* options, 1181 grpc_tls_certificate_verifier* verifier); 1182 1183 /** 1184 * EXPERIMENTAL API - Subject to change 1185 * 1186 * Sets the options of whether to check the hostname of the peer on a per-call 1187 * basis. This is usually used in a combination with virtual hosting at the 1188 * client side, where each individual call on a channel can have a different 1189 * host associated with it. 1190 * This check is intended to verify that the host specified for the individual 1191 * call is covered by the cert that the peer presented. 1192 * The default is a non-zero value, which indicates performing such checks. 1193 */ 1194 GRPCAPI void grpc_tls_credentials_options_set_check_call_host( 1195 grpc_tls_credentials_options* options, int check_call_host); 1196 1197 /** --- TLS session key logging. --- 1198 * Experimental API to control tls session key logging. Tls session key logging 1199 * is expected to be used only for debugging purposes and never in production. 1200 * Tls session key logging is only enabled when: 1201 * At least one grpc_tls_credentials_options object is assigned a tls session 1202 * key logging file path using the API specified below. 1203 */ 1204 1205 /** 1206 * EXPERIMENTAL API - Subject to change. 1207 * Configures a grpc_tls_credentials_options object with tls session key 1208 * logging capability. TLS channels using these credentials have tls session 1209 * key logging enabled. 1210 * - options is the grpc_tls_credentials_options object 1211 * - path is a string pointing to the location where TLS session keys would be 1212 * stored. 1213 */ 1214 GRPCAPI void grpc_tls_credentials_options_set_tls_session_key_log_file_path( 1215 grpc_tls_credentials_options* options, const char* path); 1216 1217 #ifdef __cplusplus 1218 } 1219 #endif 1220 1221 #endif /* GRPC_CREDENTIALS_H */ 1222