1 /* 2 * 3 * Copyright 2015 gRPC authors. 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 */ 18 19 #ifndef GRPC_GRPC_SECURITY_H 20 #define GRPC_GRPC_SECURITY_H 21 22 #include <grpc/support/port_platform.h> 23 24 #include <grpc/grpc.h> 25 #include <grpc/grpc_security_constants.h> 26 #include <grpc/status.h> 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif 31 32 /** --- Authentication Context. --- */ 33 34 typedef struct grpc_auth_context grpc_auth_context; 35 36 typedef struct grpc_auth_property_iterator { 37 const grpc_auth_context* ctx; 38 size_t index; 39 const char* name; 40 } grpc_auth_property_iterator; 41 42 /** value, if not NULL, is guaranteed to be NULL terminated. */ 43 typedef struct grpc_auth_property { 44 char* name; 45 char* value; 46 size_t value_length; 47 } grpc_auth_property; 48 49 /** Returns NULL when the iterator is at the end. */ 50 GRPCAPI const grpc_auth_property* grpc_auth_property_iterator_next( 51 grpc_auth_property_iterator* it); 52 53 /** Iterates over the auth context. */ 54 GRPCAPI grpc_auth_property_iterator 55 grpc_auth_context_property_iterator(const grpc_auth_context* ctx); 56 57 /** Gets the peer identity. Returns an empty iterator (first _next will return 58 NULL) if the peer is not authenticated. */ 59 GRPCAPI grpc_auth_property_iterator 60 grpc_auth_context_peer_identity(const grpc_auth_context* ctx); 61 62 /** Finds a property in the context. May return an empty iterator (first _next 63 will return NULL) if no property with this name was found in the context. */ 64 GRPCAPI grpc_auth_property_iterator grpc_auth_context_find_properties_by_name( 65 const grpc_auth_context* ctx, const char* name); 66 67 /** Gets the name of the property that indicates the peer identity. Will return 68 NULL if the peer is not authenticated. */ 69 GRPCAPI const char* grpc_auth_context_peer_identity_property_name( 70 const grpc_auth_context* ctx); 71 72 /** Returns 1 if the peer is authenticated, 0 otherwise. */ 73 GRPCAPI int grpc_auth_context_peer_is_authenticated( 74 const grpc_auth_context* ctx); 75 76 /** Gets the auth context from the call. Caller needs to call 77 grpc_auth_context_release on the returned context. */ 78 GRPCAPI grpc_auth_context* grpc_call_auth_context(grpc_call* call); 79 80 /** Releases the auth context returned from grpc_call_auth_context. */ 81 GRPCAPI void grpc_auth_context_release(grpc_auth_context* context); 82 83 /** -- 84 The following auth context methods should only be called by a server metadata 85 processor to set properties extracted from auth metadata. 86 -- */ 87 88 /** Add a property. */ 89 GRPCAPI void grpc_auth_context_add_property(grpc_auth_context* ctx, 90 const char* name, const char* value, 91 size_t value_length); 92 93 /** Add a C string property. */ 94 GRPCAPI void grpc_auth_context_add_cstring_property(grpc_auth_context* ctx, 95 const char* name, 96 const char* value); 97 98 /** Sets the property name. Returns 1 if successful or 0 in case of failure 99 (which means that no property with this name exists). */ 100 GRPCAPI int grpc_auth_context_set_peer_identity_property_name( 101 grpc_auth_context* ctx, const char* name); 102 103 /** --- SSL Session Cache. --- 104 105 A SSL session cache object represents a way to cache client sessions 106 between connections. Only ticket-based resumption is supported. */ 107 108 typedef struct grpc_ssl_session_cache grpc_ssl_session_cache; 109 110 /** Create LRU cache for client-side SSL sessions with the given capacity. 111 If capacity is < 1, a default capacity is used instead. */ 112 GRPCAPI grpc_ssl_session_cache* grpc_ssl_session_cache_create_lru( 113 size_t capacity); 114 115 /** Destroy SSL session cache. */ 116 GRPCAPI void grpc_ssl_session_cache_destroy(grpc_ssl_session_cache* cache); 117 118 /** Create a channel arg with the given cache object. */ 119 GRPCAPI grpc_arg 120 grpc_ssl_session_cache_create_channel_arg(grpc_ssl_session_cache* cache); 121 122 /** --- grpc_call_credentials object. 123 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. */ 127 128 typedef struct grpc_call_credentials grpc_call_credentials; 129 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); 133 134 /** --- grpc_channel_credentials object. --- 135 136 A channel credentials object represents a way to authenticate a client on a 137 channel. */ 138 139 typedef struct grpc_channel_credentials grpc_channel_credentials; 140 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); 144 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. 149 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. 158 159 If nullptr is supplied, the returned channel credentials object will use a 160 call credentials object based on the Application Default Credentials 161 mechanism. 162 */ 163 GRPCAPI grpc_channel_credentials* grpc_google_default_credentials_create( 164 grpc_call_credentials* call_credentials); 165 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); 174 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); 182 183 /** Object that holds a private key / certificate chain pair in PEM format. */ 184 typedef struct { 185 /** private_key is the NULL-terminated string containing the PEM encoding of 186 the client's private key. */ 187 const char* private_key; 188 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; 193 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 197 channel. */ 198 typedef struct { 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. 204 */ 205 int (*verify_peer_callback)(const char* target_name, const char* peer_pem, 206 void* userdata); 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; 215 216 /** Object that holds additional peer-verification options on a secure 217 channel. */ 218 typedef struct { 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. 224 */ 225 int (*verify_peer_callback)(const char* target_name, const char* peer_pem, 226 void* userdata); 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; 235 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). 247 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); 269 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). 279 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); 301 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, 306 void* reserved); 307 308 /** --- composite credentials. */ 309 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, 313 void* reserved); 314 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( 319 void* reserved); 320 321 GRPCAPI gpr_timespec grpc_max_auth_token_lifetime(void); 322 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, 331 void* reserved); 332 333 /** Creates an Oauth2 Refresh Token credentials object for connecting to Google. 334 May return NULL if the input is invalid. 335 WARNING: Do NOT use this credentials to connect to a non-google service as 336 this could result in an oauth2 token leak. 337 - json_refresh_token is the JSON string containing the refresh token itself 338 along with a client_id and client_secret. */ 339 GRPCAPI grpc_call_credentials* grpc_google_refresh_token_credentials_create( 340 const char* json_refresh_token, void* reserved); 341 342 /** Creates an Oauth2 Access Token credentials with an access token that was 343 acquired by an out of band mechanism. */ 344 GRPCAPI grpc_call_credentials* grpc_access_token_credentials_create( 345 const char* access_token, void* reserved); 346 347 /** Creates an IAM credentials object for connecting to Google. */ 348 GRPCAPI grpc_call_credentials* grpc_google_iam_credentials_create( 349 const char* authorization_token, const char* authority_selector, 350 void* reserved); 351 352 /** Options for creating STS Oauth Token Exchange credentials following the IETF 353 draft https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16. 354 Optional fields may be set to NULL or empty string. It is the responsibility 355 of the caller to ensure that the subject and actor tokens are refreshed on 356 disk at the specified paths. This API is used for experimental purposes for 357 now and may change in the future. */ 358 typedef struct { 359 const char* token_exchange_service_uri; /* Required. */ 360 const char* resource; /* Optional. */ 361 const char* audience; /* Optional. */ 362 const char* scope; /* Optional. */ 363 const char* requested_token_type; /* Optional. */ 364 const char* subject_token_path; /* Required. */ 365 const char* subject_token_type; /* Required. */ 366 const char* actor_token_path; /* Optional. */ 367 const char* actor_token_type; /* Optional. */ 368 } grpc_sts_credentials_options; 369 370 /** Creates an STS credentials following the STS Token Exchanged specifed in the 371 IETF draft https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16. 372 This API is used for experimental purposes for now and may change in the 373 future. */ 374 GRPCAPI grpc_call_credentials* grpc_sts_credentials_create( 375 const grpc_sts_credentials_options* options, void* reserved); 376 377 /** Callback function to be called by the metadata credentials plugin 378 implementation when the metadata is ready. 379 - user_data is the opaque pointer that was passed in the get_metadata method 380 of the grpc_metadata_credentials_plugin (see below). 381 - creds_md is an array of credentials metadata produced by the plugin. It 382 may be set to NULL in case of an error. 383 - num_creds_md is the number of items in the creds_md array. 384 - status must be GRPC_STATUS_OK in case of success or another specific error 385 code otherwise. 386 - error_details contains details about the error if any. In case of success 387 it should be NULL and will be otherwise ignored. */ 388 typedef void (*grpc_credentials_plugin_metadata_cb)( 389 void* user_data, const grpc_metadata* creds_md, size_t num_creds_md, 390 grpc_status_code status, const char* error_details); 391 392 /** Context that can be used by metadata credentials plugin in order to create 393 auth related metadata. */ 394 typedef struct { 395 /** The fully qualifed service url. */ 396 const char* service_url; 397 398 /** The method name of the RPC being called (not fully qualified). 399 The fully qualified method name can be built from the service_url: 400 full_qualified_method_name = ctx->service_url + '/' + ctx->method_name. */ 401 const char* method_name; 402 403 /** The auth_context of the channel which gives the server's identity. */ 404 const grpc_auth_context* channel_auth_context; 405 406 /** Reserved for future use. */ 407 void* reserved; 408 } grpc_auth_metadata_context; 409 410 /** Performs a deep copy from \a from to \a to. **/ 411 GRPCAPI void grpc_auth_metadata_context_copy(grpc_auth_metadata_context* from, 412 grpc_auth_metadata_context* to); 413 414 /** Releases internal resources held by \a context. **/ 415 GRPCAPI void grpc_auth_metadata_context_reset( 416 grpc_auth_metadata_context* context); 417 418 /** Maximum number of metadata entries returnable by a credentials plugin via 419 a synchronous return. */ 420 #define GRPC_METADATA_CREDENTIALS_PLUGIN_SYNC_MAX 4 421 422 /** grpc_metadata_credentials plugin is an API user provided structure used to 423 create grpc_credentials objects that can be set on a channel (composed) or 424 a call. See grpc_credentials_metadata_create_from_plugin below. 425 The grpc client stack will call the get_metadata method of the plugin for 426 every call in scope for the credentials created from it. */ 427 typedef struct { 428 /** The implementation of this method has to be non-blocking, but can 429 be performed synchronously or asynchronously. 430 431 If processing occurs synchronously, returns non-zero and populates 432 creds_md, num_creds_md, status, and error_details. In this case, 433 the caller takes ownership of the entries in creds_md and of 434 error_details. Note that if the plugin needs to return more than 435 GRPC_METADATA_CREDENTIALS_PLUGIN_SYNC_MAX entries in creds_md, it must 436 return asynchronously. 437 438 If processing occurs asynchronously, returns zero and invokes \a cb 439 when processing is completed. \a user_data will be passed as the 440 first parameter of the callback. NOTE: \a cb MUST be invoked in a 441 different thread, not from the thread in which \a get_metadata() is 442 invoked. 443 444 \a context is the information that can be used by the plugin to create 445 auth metadata. */ 446 int (*get_metadata)( 447 void* state, grpc_auth_metadata_context context, 448 grpc_credentials_plugin_metadata_cb cb, void* user_data, 449 grpc_metadata creds_md[GRPC_METADATA_CREDENTIALS_PLUGIN_SYNC_MAX], 450 size_t* num_creds_md, grpc_status_code* status, 451 const char** error_details); 452 453 /** Implements debug string of the given plugin. This method returns an 454 * allocated string that the caller needs to free using gpr_free() */ 455 char* (*debug_string)(void* state); 456 457 /** Destroys the plugin state. */ 458 void (*destroy)(void* state); 459 460 /** State that will be set as the first parameter of the methods above. */ 461 void* state; 462 463 /** Type of credentials that this plugin is implementing. */ 464 const char* type; 465 } grpc_metadata_credentials_plugin; 466 467 /** Creates a credentials object from a plugin with a specified minimum security 468 * level. */ 469 GRPCAPI grpc_call_credentials* grpc_metadata_credentials_create_from_plugin( 470 grpc_metadata_credentials_plugin plugin, 471 grpc_security_level min_security_level, void* reserved); 472 473 /** --- Secure channel creation. --- */ 474 475 /** Creates a secure channel using the passed-in credentials. Additional 476 channel level configuration MAY be provided by grpc_channel_args, though 477 the expectation is that most clients will want to simply pass NULL. The 478 user data in 'args' need only live through the invocation of this function. 479 However, if any args of the 'pointer' type are passed, then the referenced 480 vtable must be maintained by the caller until grpc_channel_destroy 481 terminates. See grpc_channel_args definition for more on this. */ 482 GRPCAPI grpc_channel* grpc_secure_channel_create( 483 grpc_channel_credentials* creds, const char* target, 484 const grpc_channel_args* args, void* reserved); 485 486 /** --- grpc_server_credentials object. --- 487 488 A server credentials object represents a way to authenticate a server. */ 489 490 typedef struct grpc_server_credentials grpc_server_credentials; 491 492 /** Releases a server_credentials object. 493 The creator of the server_credentials object is responsible for its release. 494 */ 495 GRPCAPI void grpc_server_credentials_release(grpc_server_credentials* creds); 496 497 /** Server certificate config object holds the server's public certificates and 498 associated private keys, as well as any CA certificates needed for client 499 certificate validation (if applicable). Create using 500 grpc_ssl_server_certificate_config_create(). */ 501 typedef struct grpc_ssl_server_certificate_config 502 grpc_ssl_server_certificate_config; 503 504 /** Creates a grpc_ssl_server_certificate_config object. 505 - pem_roots_cert is the NULL-terminated string containing the PEM encoding of 506 the client root certificates. This parameter may be NULL if the server does 507 not want the client to be authenticated with SSL. 508 - pem_key_cert_pairs is an array private key / certificate chains of the 509 server. This parameter cannot be NULL. 510 - num_key_cert_pairs indicates the number of items in the private_key_files 511 and cert_chain_files parameters. It must be at least 1. 512 - It is the caller's responsibility to free this object via 513 grpc_ssl_server_certificate_config_destroy(). */ 514 GRPCAPI grpc_ssl_server_certificate_config* 515 grpc_ssl_server_certificate_config_create( 516 const char* pem_root_certs, 517 const grpc_ssl_pem_key_cert_pair* pem_key_cert_pairs, 518 size_t num_key_cert_pairs); 519 520 /** Destroys a grpc_ssl_server_certificate_config object. */ 521 GRPCAPI void grpc_ssl_server_certificate_config_destroy( 522 grpc_ssl_server_certificate_config* config); 523 524 /** Callback to retrieve updated SSL server certificates, private keys, and 525 trusted CAs (for client authentication). 526 - user_data parameter, if not NULL, contains opaque data to be used by the 527 callback. 528 - Use grpc_ssl_server_certificate_config_create to create the config. 529 - The caller assumes ownership of the config. */ 530 typedef grpc_ssl_certificate_config_reload_status ( 531 *grpc_ssl_server_certificate_config_callback)( 532 void* user_data, grpc_ssl_server_certificate_config** config); 533 534 /** Deprecated in favor of grpc_ssl_server_credentials_create_ex. 535 Creates an SSL server_credentials object. 536 - pem_roots_cert is the NULL-terminated string containing the PEM encoding of 537 the client root certificates. This parameter may be NULL if the server does 538 not want the client to be authenticated with SSL. 539 - pem_key_cert_pairs is an array private key / certificate chains of the 540 server. This parameter cannot be NULL. 541 - num_key_cert_pairs indicates the number of items in the private_key_files 542 and cert_chain_files parameters. It should be at least 1. 543 - force_client_auth, if set to non-zero will force the client to authenticate 544 with an SSL cert. Note that this option is ignored if pem_root_certs is 545 NULL. */ 546 GRPCAPI grpc_server_credentials* grpc_ssl_server_credentials_create( 547 const char* pem_root_certs, grpc_ssl_pem_key_cert_pair* pem_key_cert_pairs, 548 size_t num_key_cert_pairs, int force_client_auth, void* reserved); 549 550 /** Deprecated in favor of grpc_ssl_server_credentials_create_with_options. 551 Same as grpc_ssl_server_credentials_create method except uses 552 grpc_ssl_client_certificate_request_type enum to support more ways to 553 authenticate client certificates.*/ 554 GRPCAPI grpc_server_credentials* grpc_ssl_server_credentials_create_ex( 555 const char* pem_root_certs, grpc_ssl_pem_key_cert_pair* pem_key_cert_pairs, 556 size_t num_key_cert_pairs, 557 grpc_ssl_client_certificate_request_type client_certificate_request, 558 void* reserved); 559 560 typedef struct grpc_ssl_server_credentials_options 561 grpc_ssl_server_credentials_options; 562 563 /** Creates an options object using a certificate config. Use this method when 564 the certificates and keys of the SSL server will not change during the 565 server's lifetime. 566 - Takes ownership of the certificate_config parameter. */ 567 GRPCAPI grpc_ssl_server_credentials_options* 568 grpc_ssl_server_credentials_create_options_using_config( 569 grpc_ssl_client_certificate_request_type client_certificate_request, 570 grpc_ssl_server_certificate_config* certificate_config); 571 572 /** Creates an options object using a certificate config fetcher. Use this 573 method to reload the certificates and keys of the SSL server without 574 interrupting the operation of the server. Initial certificate config will be 575 fetched during server initialization. 576 - user_data parameter, if not NULL, contains opaque data which will be passed 577 to the fetcher (see definition of 578 grpc_ssl_server_certificate_config_callback). */ 579 GRPCAPI grpc_ssl_server_credentials_options* 580 grpc_ssl_server_credentials_create_options_using_config_fetcher( 581 grpc_ssl_client_certificate_request_type client_certificate_request, 582 grpc_ssl_server_certificate_config_callback cb, void* user_data); 583 584 /** Destroys a grpc_ssl_server_credentials_options object. */ 585 GRPCAPI void grpc_ssl_server_credentials_options_destroy( 586 grpc_ssl_server_credentials_options* options); 587 588 /** Creates an SSL server_credentials object using the provided options struct. 589 - Takes ownership of the options parameter. */ 590 GRPCAPI grpc_server_credentials* 591 grpc_ssl_server_credentials_create_with_options( 592 grpc_ssl_server_credentials_options* options); 593 594 /** --- Server-side secure ports. --- */ 595 596 /** Add a HTTP2 over an encrypted link over tcp listener. 597 Returns bound port number on success, 0 on failure. 598 REQUIRES: server not started */ 599 GRPCAPI int grpc_server_add_secure_http2_port(grpc_server* server, 600 const char* addr, 601 grpc_server_credentials* creds); 602 603 /** --- Call specific credentials. --- */ 604 605 /** Sets a credentials to a call. Can only be called on the client side before 606 grpc_call_start_batch. */ 607 GRPCAPI grpc_call_error grpc_call_set_credentials(grpc_call* call, 608 grpc_call_credentials* creds); 609 610 /** --- Auth Metadata Processing --- */ 611 612 /** Callback function that is called when the metadata processing is done. 613 - Consumed metadata will be removed from the set of metadata available on the 614 call. consumed_md may be NULL if no metadata has been consumed. 615 - Response metadata will be set on the response. response_md may be NULL. 616 - status is GRPC_STATUS_OK for success or a specific status for an error. 617 Common error status for auth metadata processing is either 618 GRPC_STATUS_UNAUTHENTICATED in case of an authentication failure or 619 GRPC_STATUS PERMISSION_DENIED in case of an authorization failure. 620 - error_details gives details about the error. May be NULL. */ 621 typedef void (*grpc_process_auth_metadata_done_cb)( 622 void* user_data, const grpc_metadata* consumed_md, size_t num_consumed_md, 623 const grpc_metadata* response_md, size_t num_response_md, 624 grpc_status_code status, const char* error_details); 625 626 /** Pluggable server-side metadata processor object. */ 627 typedef struct { 628 /** The context object is read/write: it contains the properties of the 629 channel peer and it is the job of the process function to augment it with 630 properties derived from the passed-in metadata. 631 The lifetime of these objects is guaranteed until cb is invoked. */ 632 void (*process)(void* state, grpc_auth_context* context, 633 const grpc_metadata* md, size_t num_md, 634 grpc_process_auth_metadata_done_cb cb, void* user_data); 635 void (*destroy)(void* state); 636 void* state; 637 } grpc_auth_metadata_processor; 638 639 GRPCAPI void grpc_server_credentials_set_auth_metadata_processor( 640 grpc_server_credentials* creds, grpc_auth_metadata_processor processor); 641 642 /** --- ALTS channel/server credentials --- **/ 643 644 /** 645 * Main interface for ALTS credentials options. The options will contain 646 * information that will be passed from grpc to TSI layer such as RPC protocol 647 * versions. ALTS client (channel) and server credentials will have their own 648 * implementation of this interface. The APIs listed in this header are 649 * thread-compatible. It is used for experimental purpose for now and subject 650 * to change. 651 */ 652 typedef struct grpc_alts_credentials_options grpc_alts_credentials_options; 653 654 /** 655 * This method creates a grpc ALTS credentials client options instance. 656 * It is used for experimental purpose for now and subject to change. 657 */ 658 GRPCAPI grpc_alts_credentials_options* 659 grpc_alts_credentials_client_options_create(void); 660 661 /** 662 * This method creates a grpc ALTS credentials server options instance. 663 * It is used for experimental purpose for now and subject to change. 664 */ 665 GRPCAPI grpc_alts_credentials_options* 666 grpc_alts_credentials_server_options_create(void); 667 668 /** 669 * This method adds a target service account to grpc client's ALTS credentials 670 * options instance. It is used for experimental purpose for now and subject 671 * to change. 672 * 673 * - options: grpc ALTS credentials options instance. 674 * - service_account: service account of target endpoint. 675 */ 676 GRPCAPI void grpc_alts_credentials_client_options_add_target_service_account( 677 grpc_alts_credentials_options* options, const char* service_account); 678 679 /** 680 * This method destroys a grpc_alts_credentials_options instance by 681 * de-allocating all of its occupied memory. It is used for experimental purpose 682 * for now and subject to change. 683 * 684 * - options: a grpc_alts_credentials_options instance that needs to be 685 * destroyed. 686 */ 687 GRPCAPI void grpc_alts_credentials_options_destroy( 688 grpc_alts_credentials_options* options); 689 690 /** 691 * This method creates an ALTS channel credential object. The security 692 * level of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY. 693 * It is used for experimental purpose for now and subject to change. 694 * 695 * - options: grpc ALTS credentials options instance for client. 696 * 697 * It returns the created ALTS channel credential object. 698 */ 699 GRPCAPI grpc_channel_credentials* grpc_alts_credentials_create( 700 const grpc_alts_credentials_options* options); 701 702 /** 703 * This method creates an ALTS server credential object. It is used for 704 * experimental purpose for now and subject to change. 705 * 706 * - options: grpc ALTS credentials options instance for server. 707 * 708 * It returns the created ALTS server credential object. 709 */ 710 GRPCAPI grpc_server_credentials* grpc_alts_server_credentials_create( 711 const grpc_alts_credentials_options* options); 712 713 /** --- Local channel/server credentials --- **/ 714 715 /** 716 * This method creates a local channel credential object. The security level 717 * of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY for UDS and 718 * GRPC_SECURITY_NONE for LOCAL_TCP. It is used for experimental purpose 719 * for now and subject to change. 720 * 721 * - type: local connection type 722 * 723 * It returns the created local channel credential object. 724 */ 725 GRPCAPI grpc_channel_credentials* grpc_local_credentials_create( 726 grpc_local_connect_type type); 727 728 /** 729 * This method creates a local server credential object. It is used for 730 * experimental purpose for now and subject to change. 731 * 732 * - type: local connection type 733 * 734 * It returns the created local server credential object. 735 */ 736 GRPCAPI grpc_server_credentials* grpc_local_server_credentials_create( 737 grpc_local_connect_type type); 738 739 /** --- TLS channel/server credentials --- 740 * It is used for experimental purpose for now and subject to change. */ 741 742 /** Struct for indicating errors. It is used for 743 * experimental purpose for now and subject to change. */ 744 typedef struct grpc_tls_error_details grpc_tls_error_details; 745 746 /** Config for TLS server authorization check. It is used for 747 * experimental purpose for now and subject to change. */ 748 typedef struct grpc_tls_server_authorization_check_config 749 grpc_tls_server_authorization_check_config; 750 751 /** 752 * A struct that can be specified by callers to configure underlying TLS 753 * behaviors. It is used for experimental purpose for now and subject to change. 754 */ 755 typedef struct grpc_tls_credentials_options grpc_tls_credentials_options; 756 757 /** 758 * A struct provides ways to gain credential data that will be used in the TLS 759 * handshake. It is used for experimental purpose for now and subject to change. 760 */ 761 typedef struct grpc_tls_certificate_provider grpc_tls_certificate_provider; 762 763 /** 764 * A struct that stores the credential data presented to the peer in handshake 765 * to show local identity. It is used for experimental purpose for now and 766 * subject to change. 767 */ 768 typedef struct grpc_tls_identity_pairs grpc_tls_identity_pairs; 769 770 /** 771 * Creates a grpc_tls_identity_pairs that stores a list of identity credential 772 * data, including identity private key and identity certificate chain. It is 773 * used for experimental purpose for now and subject to change. 774 */ 775 GRPCAPI grpc_tls_identity_pairs* grpc_tls_identity_pairs_create(); 776 777 /** 778 * Adds a identity private key and a identity certificate chain to 779 * grpc_tls_identity_pairs. This function will make an internal copy of 780 * |private_key| and |cert_chain|. It is used for experimental purpose for now 781 * and subject to change. 782 */ 783 GRPCAPI void grpc_tls_identity_pairs_add_pair(grpc_tls_identity_pairs* pairs, 784 const char* private_key, 785 const char* cert_chain); 786 787 /** 788 * Destroys a grpc_tls_identity_pairs object. If this object is passed to a 789 * provider initiation function, the ownership is transferred so this function 790 * doesn't need to be called. Otherwise the creator of the 791 * grpc_tls_identity_pairs object is responsible for its destruction. It is 792 * used for experimental purpose for now and subject to change. 793 */ 794 GRPCAPI void grpc_tls_identity_pairs_destroy(grpc_tls_identity_pairs* pairs); 795 796 /** 797 * Creates a grpc_tls_certificate_provider that will load credential data from 798 * static string during initialization. This provider will always return the 799 * same cert data for all cert names. 800 * root_certificate and pem_key_cert_pairs can be nullptr, indicating the 801 * corresponding credential data is not needed. 802 * This function will make a copy of |root_certificate|. 803 * The ownership of |pem_key_cert_pairs| is transferred. 804 * It is used for experimental purpose for now and subject to change. 805 */ 806 GRPCAPI grpc_tls_certificate_provider* 807 grpc_tls_certificate_provider_static_data_create( 808 const char* root_certificate, grpc_tls_identity_pairs* pem_key_cert_pairs); 809 810 /** 811 * Releases a grpc_tls_certificate_provider object. The creator of the 812 * grpc_tls_certificate_provider object is responsible for its release. It is 813 * used for experimental purpose for now and subject to change. 814 */ 815 GRPCAPI void grpc_tls_certificate_provider_release( 816 grpc_tls_certificate_provider* provider); 817 818 /** 819 * Creates an grpc_tls_credentials_options. 820 * It is used for experimental purpose for now and subject to change. 821 */ 822 GRPCAPI grpc_tls_credentials_options* grpc_tls_credentials_options_create(void); 823 824 /** 825 * Sets the options of whether to request and verify client certs. This should 826 * be called only on the server side. It returns 1 on success and 0 on failure. 827 * It is used for experimental purpose for now and subject to change. 828 */ 829 GRPCAPI void grpc_tls_credentials_options_set_cert_request_type( 830 grpc_tls_credentials_options* options, 831 grpc_ssl_client_certificate_request_type type); 832 833 /** 834 * Sets the options of whether to choose certain checks, e.g. certificate check, 835 * hostname check, etc. This should be called only on the client side. If 836 * |server_verification_option| is not GRPC_TLS_SERVER_VERIFICATION, use of a 837 * custom authorization check (grpc_tls_server_authorization_check_config) is 838 * mandatory. It returns 1 on success and 0 on failure. It is used for 839 * experimental purpose for now and subject to change. 840 */ 841 GRPCAPI void grpc_tls_credentials_options_set_server_verification_option( 842 grpc_tls_credentials_options* options, 843 grpc_tls_server_verification_option server_verification_option); 844 845 /** 846 * Sets the credential provider in the options. 847 * The |options| will implicitly take a new ref to the |provider|. 848 * It returns 1 on success and 0 on failure. 849 * It is used for experimental purpose for now and subject to change. 850 */ 851 GRPCAPI void grpc_tls_credentials_options_set_certificate_provider( 852 grpc_tls_credentials_options* options, 853 grpc_tls_certificate_provider* provider); 854 855 /** 856 * If set, gRPC stack will keep watching the root certificates with 857 * name |root_cert_name|. It returns 1 on success and 0 on failure. It is used 858 * for experimental purpose for now and subject to change. 859 */ 860 GRPCAPI void grpc_tls_credentials_options_watch_root_certs( 861 grpc_tls_credentials_options* options); 862 863 /** 864 * Sets the name of the root certificates being watched. 865 * If not set, We will use a default empty string as the root certificate name. 866 * It is used for experimental purpose for now and subject to change. 867 */ 868 GRPCAPI void grpc_tls_credentials_options_set_root_cert_name( 869 grpc_tls_credentials_options* options, const char* root_cert_name); 870 871 /** 872 * If set, gRPC stack will keep watching the identity key-cert pairs 873 * with name |identity_cert_name|. It returns 1 on success and 0 on failure. It 874 * is used for experimental purpose for now and subject to change. 875 */ 876 GRPCAPI void grpc_tls_credentials_options_watch_identity_key_cert_pairs( 877 grpc_tls_credentials_options* options); 878 879 /** 880 * Sets the name of the identity certificates being watched. 881 * If not set, We will use a default empty string as the identity certificate 882 * name. It is used for experimental purpose for now and subject to change. 883 */ 884 GRPCAPI void grpc_tls_credentials_options_set_identity_cert_name( 885 grpc_tls_credentials_options* options, const char* identity_cert_name); 886 887 /** 888 * Sets the configuration for a custom authorization check performed at the end 889 * of the handshake. The |options| will implicitly take a new ref to the 890 * |config|. It returns 1 on success and 0 on failure. It is used for 891 * experimental purpose for now and subject to change. 892 */ 893 GRPCAPI void grpc_tls_credentials_options_set_server_authorization_check_config( 894 grpc_tls_credentials_options* options, 895 grpc_tls_server_authorization_check_config* config); 896 897 /** --- TLS server authorization check config. --- 898 * It is used for experimental purpose for now and subject to change. */ 899 900 typedef struct grpc_tls_server_authorization_check_arg 901 grpc_tls_server_authorization_check_arg; 902 903 /** callback function provided by gRPC used to handle the result of server 904 authorization check. It is used when schedule API is implemented 905 asynchronously, and serves to bring the control back to gRPC C core. It is 906 used for experimental purpose for now and subject to change. */ 907 typedef void (*grpc_tls_on_server_authorization_check_done_cb)( 908 grpc_tls_server_authorization_check_arg* arg); 909 910 /** A struct containing all information necessary to schedule/cancel a server 911 authorization check request. 912 - cb and cb_user_data represent a gRPC-provided callback and an argument 913 passed to it. 914 - success will store the result of server authorization check. That is, 915 if success returns a non-zero value, it means the authorization check 916 passes and if returning zero, it means the check fails. 917 - target_name is the name of an endpoint the channel is connecting to. 918 - peer_cert represents a complete certificate chain including both 919 signing and leaf certificates. 920 - status and error_details contain information 921 about errors occurred when a server authorization check request is 922 scheduled/cancelled. 923 - config is a pointer to the unique 924 grpc_tls_server_authorization_check_config instance that this argument 925 corresponds to. 926 - context is a pointer to a wrapped language implementation of this 927 grpc_tls_server_authorization_check_arg instance. 928 - destroy_context is a pointer to a caller-provided method that cleans 929 up any data associated with the context pointer. 930 It is used for experimental purpose for now and subject to change. 931 */ 932 struct grpc_tls_server_authorization_check_arg { 933 grpc_tls_on_server_authorization_check_done_cb cb; 934 void* cb_user_data; 935 int success; 936 const char* target_name; 937 const char* peer_cert; 938 const char* peer_cert_full_chain; 939 grpc_status_code status; 940 grpc_tls_error_details* error_details; 941 grpc_tls_server_authorization_check_config* config; 942 void* context; 943 void (*destroy_context)(void* ctx); 944 }; 945 946 /** Create a grpc_tls_server_authorization_check_config instance. 947 - config_user_data is config-specific, read-only user data 948 that works for all channels created with a credential using the config. 949 - schedule is a pointer to an application-provided callback used to invoke 950 server authorization check API. The implementation of this method has to 951 be non-blocking, but can be performed synchronously or asynchronously. 952 1)If processing occurs synchronously, it populates arg->result, 953 arg->status, and arg->error_details and returns zero. 954 2) If processing occurs asynchronously, it returns a non-zero value. The 955 application then invokes arg->cb when processing is completed. Note that 956 arg->cb cannot be invoked before schedule API returns. 957 - cancel is a pointer to an application-provided callback used to cancel a 958 server authorization check request scheduled via an asynchronous schedule 959 API. arg is used to pinpoint an exact check request to be cancelled. The 960 operation may not have any effect if the request has already been 961 processed. 962 - destruct is a pointer to an application-provided callback used to clean up 963 any data associated with the config. 964 It is used for experimental purpose for now and subject to change. 965 */ 966 GRPCAPI grpc_tls_server_authorization_check_config* 967 grpc_tls_server_authorization_check_config_create( 968 const void* config_user_data, 969 int (*schedule)(void* config_user_data, 970 grpc_tls_server_authorization_check_arg* arg), 971 void (*cancel)(void* config_user_data, 972 grpc_tls_server_authorization_check_arg* arg), 973 void (*destruct)(void* config_user_data)); 974 975 /** 976 * Releases a grpc_tls_server_authorization_check_config object. The creator of 977 * the grpc_tls_server_authorization_check_config object is responsible for its 978 * release. It is used for experimental purpose for now and subject to change. 979 */ 980 GRPCAPI void grpc_tls_server_authorization_check_config_release( 981 grpc_tls_server_authorization_check_config* config); 982 983 /** 984 * Creates a TLS channel credential object based on the 985 * grpc_tls_credentials_options specified by callers. The 986 * grpc_channel_credentials will take the ownership of the |options|. The 987 * security level of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY. It 988 * is used for experimental purpose for now and subject to change. 989 */ 990 grpc_channel_credentials* grpc_tls_credentials_create( 991 grpc_tls_credentials_options* options); 992 993 /** 994 * Creates a TLS server credential object based on the 995 * grpc_tls_credentials_options specified by callers. The 996 * grpc_server_credentials will take the ownership of the |options|. It 997 * is used for experimental purpose for now and subject to change. 998 */ 999 grpc_server_credentials* grpc_tls_server_credentials_create( 1000 grpc_tls_credentials_options* options); 1001 1002 /** 1003 * EXPERIMENTAL API - Subject to change 1004 * 1005 * This method creates an insecure channel credentials object. 1006 */ 1007 grpc_channel_credentials* grpc_insecure_credentials_create(); 1008 1009 /** 1010 * EXPERIMENTAL API - Subject to change 1011 * 1012 * This method creates an XDS channel credentials object. 1013 * 1014 * Creating a channel with credentials of this type indicates that an xDS 1015 * channel should get credentials configuration from the xDS control plane. 1016 * 1017 * \a fallback_credentials are used if the channel target does not have the 1018 * 'xds:///' scheme or if the xDS control plane does not provide information on 1019 * how to fetch credentials dynamically. Does NOT take ownership of the \a 1020 * fallback_credentials. (Internally takes a ref to the object.) 1021 */ 1022 GRPCAPI grpc_channel_credentials* grpc_xds_credentials_create( 1023 grpc_channel_credentials* fallback_credentials); 1024 1025 #ifdef __cplusplus 1026 } 1027 #endif 1028 1029 #endif /* GRPC_GRPC_SECURITY_H */ 1030