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