GRPC Core  18.0.0
Data Structures | Functions
ssl_credentials.cc File Reference
#include <grpc/support/port_platform.h>
#include "src/core/lib/security/credentials/ssl/ssl_credentials.h"
#include <string.h>
#include "src/core/lib/channel/channel_args.h"
#include "src/core/lib/surface/api_trace.h"
#include "src/core/tsi/ssl_transport_security.h"
#include <grpc/support/alloc.h>
#include <grpc/support/log.h>
#include <grpc/support/string_util.h>

Data Structures

struct  grpc_ssl_server_credentials_options
 

Functions

void grpc_tsi_ssl_pem_key_cert_pairs_destroy (tsi_ssl_pem_key_cert_pair *kp, size_t num_key_cert_pairs)
 
grpc_channel_credentialsgrpc_ssl_credentials_create (const char *pem_root_certs, grpc_ssl_pem_key_cert_pair *pem_key_cert_pair, const verify_peer_options *verify_options, void *reserved)
 Deprecated in favor of grpc_ssl_server_credentials_create_ex. More...
 
grpc_channel_credentialsgrpc_ssl_credentials_create_ex (const char *pem_root_certs, grpc_ssl_pem_key_cert_pair *pem_key_cert_pair, const grpc_ssl_verify_peer_options *verify_options, void *reserved)
 
tsi_ssl_pem_key_cert_pairgrpc_convert_grpc_to_tsi_cert_pairs (const grpc_ssl_pem_key_cert_pair *pem_key_cert_pairs, size_t num_key_cert_pairs)
 
grpc_ssl_server_certificate_configgrpc_ssl_server_certificate_config_create (const char *pem_root_certs, const grpc_ssl_pem_key_cert_pair *pem_key_cert_pairs, size_t num_key_cert_pairs)
 Creates a grpc_ssl_server_certificate_config object. More...
 
void grpc_ssl_server_certificate_config_destroy (grpc_ssl_server_certificate_config *config)
 Destroys a grpc_ssl_server_certificate_config object. More...
 
grpc_ssl_server_credentials_optionsgrpc_ssl_server_credentials_create_options_using_config (grpc_ssl_client_certificate_request_type client_certificate_request, grpc_ssl_server_certificate_config *config)
 Creates an options object using a certificate config. More...
 
grpc_ssl_server_credentials_optionsgrpc_ssl_server_credentials_create_options_using_config_fetcher (grpc_ssl_client_certificate_request_type client_certificate_request, grpc_ssl_server_certificate_config_callback cb, void *user_data)
 Creates an options object using a certificate config fetcher. More...
 
grpc_server_credentialsgrpc_ssl_server_credentials_create (const char *pem_root_certs, grpc_ssl_pem_key_cert_pair *pem_key_cert_pairs, size_t num_key_cert_pairs, int force_client_auth, void *reserved)
 Deprecated in favor of grpc_ssl_server_credentials_create_ex. More...
 
grpc_server_credentialsgrpc_ssl_server_credentials_create_ex (const char *pem_root_certs, grpc_ssl_pem_key_cert_pair *pem_key_cert_pairs, size_t num_key_cert_pairs, grpc_ssl_client_certificate_request_type client_certificate_request, void *reserved)
 Deprecated in favor of grpc_ssl_server_credentials_create_with_options. More...
 
grpc_server_credentialsgrpc_ssl_server_credentials_create_with_options (grpc_ssl_server_credentials_options *options)
 Creates an SSL server_credentials object using the provided options struct. More...
 
void grpc_ssl_server_credentials_options_destroy (grpc_ssl_server_credentials_options *o)
 Destroys a grpc_ssl_server_credentials_options object. More...
 

Function Documentation

◆ grpc_convert_grpc_to_tsi_cert_pairs()

tsi_ssl_pem_key_cert_pair* grpc_convert_grpc_to_tsi_cert_pairs ( const grpc_ssl_pem_key_cert_pair pem_key_cert_pairs,
size_t  num_key_cert_pairs 
)

◆ grpc_ssl_credentials_create()

grpc_channel_credentials* grpc_ssl_credentials_create ( const char *  pem_root_certs,
grpc_ssl_pem_key_cert_pair pem_key_cert_pair,
const verify_peer_options verify_options,
void *  reserved 
)

Deprecated in favor of grpc_ssl_server_credentials_create_ex.

It will be removed after all of its call sites are migrated to grpc_ssl_server_credentials_create_ex. Creates an SSL credentials object. The security level of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY.

  • pem_root_certs is the NULL-terminated string containing the PEM encoding of the server root certificates. If this parameter is NULL, the implementation will first try to dereference the file pointed by the GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment variable, and if that fails, try to get the roots set by grpc_override_ssl_default_roots. Eventually, if all these fail, it will try to get the roots from a well-known place on disk (in the grpc install directory).

    gRPC has implemented root cache if the underlying OpenSSL library supports it. The gRPC root certificates cache is only applicable on the default root certificates, which is used when this parameter is nullptr. If user provides their own pem_root_certs, when creating an SSL credential object, gRPC would not be able to cache it, and each subchannel will generate a copy of the root store. So it is recommended to avoid providing large room pem with pem_root_certs parameter to avoid excessive memory consumption, particularly on mobile platforms such as iOS.

  • pem_key_cert_pair is a pointer on the object containing client's private key and certificate chain. This parameter can be NULL if the client does not have such a key/cert pair.
  • verify_options is an optional verify_peer_options object which holds additional options controlling how peer certificates are verified. For example, you can supply a callback which receives the peer's certificate with which you can do additional verification. Can be NULL, in which case verification will retain default behavior. Any settings in verify_options are copied during this call, so the verify_options object can be released afterwards.

◆ grpc_ssl_credentials_create_ex()

grpc_channel_credentials* grpc_ssl_credentials_create_ex ( const char *  pem_root_certs,
grpc_ssl_pem_key_cert_pair pem_key_cert_pair,
const grpc_ssl_verify_peer_options verify_options,
void *  reserved 
)

◆ grpc_ssl_server_certificate_config_create()

grpc_ssl_server_certificate_config* grpc_ssl_server_certificate_config_create ( const char *  pem_root_certs,
const grpc_ssl_pem_key_cert_pair pem_key_cert_pairs,
size_t  num_key_cert_pairs 
)

Creates a grpc_ssl_server_certificate_config object.

  • pem_roots_cert is the NULL-terminated string containing the PEM encoding of the client root certificates. This parameter may be NULL if the server does not want the client to be authenticated with SSL.
  • pem_key_cert_pairs is an array private key / certificate chains of the server. This parameter cannot be NULL.
  • num_key_cert_pairs indicates the number of items in the private_key_files and cert_chain_files parameters. It must be at least 1.
  • It is the caller's responsibility to free this object via grpc_ssl_server_certificate_config_destroy().

◆ grpc_ssl_server_certificate_config_destroy()

void grpc_ssl_server_certificate_config_destroy ( grpc_ssl_server_certificate_config config)

◆ grpc_ssl_server_credentials_create()

grpc_server_credentials* grpc_ssl_server_credentials_create ( const char *  pem_root_certs,
grpc_ssl_pem_key_cert_pair pem_key_cert_pairs,
size_t  num_key_cert_pairs,
int  force_client_auth,
void *  reserved 
)

Deprecated in favor of grpc_ssl_server_credentials_create_ex.

Creates an SSL server_credentials object.

  • pem_roots_cert is the NULL-terminated string containing the PEM encoding of the client root certificates. This parameter may be NULL if the server does not want the client to be authenticated with SSL.
  • pem_key_cert_pairs is an array private key / certificate chains of the server. This parameter cannot be NULL.
  • num_key_cert_pairs indicates the number of items in the private_key_files and cert_chain_files parameters. It should be at least 1.
  • force_client_auth, if set to non-zero will force the client to authenticate with an SSL cert. Note that this option is ignored if pem_root_certs is NULL.

◆ grpc_ssl_server_credentials_create_ex()

grpc_server_credentials* grpc_ssl_server_credentials_create_ex ( const char *  pem_root_certs,
grpc_ssl_pem_key_cert_pair pem_key_cert_pairs,
size_t  num_key_cert_pairs,
grpc_ssl_client_certificate_request_type  client_certificate_request,
void *  reserved 
)

Deprecated in favor of grpc_ssl_server_credentials_create_with_options.

Same as grpc_ssl_server_credentials_create method except uses grpc_ssl_client_certificate_request_type enum to support more ways to authenticate client certificates.

◆ grpc_ssl_server_credentials_create_options_using_config()

grpc_ssl_server_credentials_options* grpc_ssl_server_credentials_create_options_using_config ( grpc_ssl_client_certificate_request_type  client_certificate_request,
grpc_ssl_server_certificate_config certificate_config 
)

Creates an options object using a certificate config.

Use this method when the certificates and keys of the SSL server will not change during the server's lifetime.

  • Takes ownership of the certificate_config parameter.

◆ grpc_ssl_server_credentials_create_options_using_config_fetcher()

grpc_ssl_server_credentials_options* grpc_ssl_server_credentials_create_options_using_config_fetcher ( grpc_ssl_client_certificate_request_type  client_certificate_request,
grpc_ssl_server_certificate_config_callback  cb,
void *  user_data 
)

Creates an options object using a certificate config fetcher.

Use this method to reload the certificates and keys of the SSL server without interrupting the operation of the server. Initial certificate config will be fetched during server initialization.

  • user_data parameter, if not NULL, contains opaque data which will be passed to the fetcher (see definition of grpc_ssl_server_certificate_config_callback).

◆ grpc_ssl_server_credentials_create_with_options()

grpc_server_credentials* grpc_ssl_server_credentials_create_with_options ( grpc_ssl_server_credentials_options options)

Creates an SSL server_credentials object using the provided options struct.

  • Takes ownership of the options parameter.

◆ grpc_ssl_server_credentials_options_destroy()

void grpc_ssl_server_credentials_options_destroy ( grpc_ssl_server_credentials_options o)

◆ grpc_tsi_ssl_pem_key_cert_pairs_destroy()

void grpc_tsi_ssl_pem_key_cert_pairs_destroy ( tsi_ssl_pem_key_cert_pair kp,
size_t  num_key_cert_pairs 
)