grpc_security.h

Go to the documentation of this file.

/*
 *
 * Copyright 2015 gRPC authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 */

#ifndef GRPC_GRPC_SECURITY_H
#define GRPC_GRPC_SECURITY_H

#include <grpc/support/port_platform.h>

#include <grpc/grpc.h>
#include <grpc/grpc_security_constants.h>
#include <grpc/status.h>

#ifdef __cplusplus
extern "C" {
#endif

typedef struct grpc_auth_context grpc_auth_context;

typedef struct grpc_auth_property_iterator {
  const grpc_auth_context* ctx;
  size_t index;
  const char* name;
} grpc_auth_property_iterator;

typedef struct grpc_auth_property {
  char* name;
  char* value;
  size_t value_length;
} grpc_auth_property;

GRPCAPI const grpc_auth_property* grpc_auth_property_iterator_next(
    grpc_auth_property_iterator* it);

GRPCAPI grpc_auth_property_iterator
grpc_auth_context_property_iterator(const grpc_auth_context* ctx);

GRPCAPI grpc_auth_property_iterator
grpc_auth_context_peer_identity(const grpc_auth_context* ctx);

GRPCAPI grpc_auth_property_iterator grpc_auth_context_find_properties_by_name(
    const grpc_auth_context* ctx, const char* name);

GRPCAPI const char* grpc_auth_context_peer_identity_property_name(
    const grpc_auth_context* ctx);

GRPCAPI int grpc_auth_context_peer_is_authenticated(
    const grpc_auth_context* ctx);

GRPCAPI grpc_auth_context* grpc_call_auth_context(grpc_call* call);

GRPCAPI void grpc_auth_context_release(grpc_auth_context* context);

GRPCAPI void grpc_auth_context_add_property(grpc_auth_context* ctx,
                                            const char* name, const char* value,
                                            size_t value_length);

GRPCAPI void grpc_auth_context_add_cstring_property(grpc_auth_context* ctx,
                                                    const char* name,
                                                    const char* value);

GRPCAPI int grpc_auth_context_set_peer_identity_property_name(
    grpc_auth_context* ctx, const char* name);

typedef struct grpc_ssl_session_cache grpc_ssl_session_cache;

GRPCAPI grpc_ssl_session_cache* grpc_ssl_session_cache_create_lru(
    size_t capacity);

GRPCAPI void grpc_ssl_session_cache_destroy(grpc_ssl_session_cache* cache);

GRPCAPI grpc_arg
grpc_ssl_session_cache_create_channel_arg(grpc_ssl_session_cache* cache);

typedef struct grpc_channel_credentials grpc_channel_credentials;

GRPCAPI void grpc_channel_credentials_release(grpc_channel_credentials* creds);

GRPCAPI grpc_channel_credentials* grpc_google_default_credentials_create(void);

typedef grpc_ssl_roots_override_result (*grpc_ssl_roots_override_callback)(
    char** pem_root_certs);

GRPCAPI void grpc_set_ssl_roots_override_callback(
    grpc_ssl_roots_override_callback cb);

typedef struct {
  const char* private_key;

  const char* cert_chain;
} grpc_ssl_pem_key_cert_pair;

typedef struct {
  int (*verify_peer_callback)(const char* target_name, const char* peer_pem,
                              void* userdata);
  void* verify_peer_callback_userdata;
  void (*verify_peer_destruct)(void* userdata);
} verify_peer_options;

GRPCAPI 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);

typedef struct grpc_call_credentials grpc_call_credentials;

GRPCAPI void grpc_call_credentials_release(grpc_call_credentials* creds);

GRPCAPI grpc_channel_credentials* grpc_composite_channel_credentials_create(
    grpc_channel_credentials* channel_creds, grpc_call_credentials* call_creds,
    void* reserved);

GRPCAPI grpc_call_credentials* grpc_composite_call_credentials_create(
    grpc_call_credentials* creds1, grpc_call_credentials* creds2,
    void* reserved);

GRPCAPI grpc_call_credentials* grpc_google_compute_engine_credentials_create(
    void* reserved);

GRPCAPI gpr_timespec grpc_max_auth_token_lifetime(void);

GRPCAPI grpc_call_credentials*
grpc_service_account_jwt_access_credentials_create(const char* json_key,
                                                   gpr_timespec token_lifetime,
                                                   void* reserved);

GRPCAPI grpc_call_credentials* grpc_google_refresh_token_credentials_create(
    const char* json_refresh_token, void* reserved);

GRPCAPI grpc_call_credentials* grpc_access_token_credentials_create(
    const char* access_token, void* reserved);

GRPCAPI grpc_call_credentials* grpc_google_iam_credentials_create(
    const char* authorization_token, const char* authority_selector,
    void* reserved);

typedef void (*grpc_credentials_plugin_metadata_cb)(
    void* user_data, const grpc_metadata* creds_md, size_t num_creds_md,
    grpc_status_code status, const char* error_details);

typedef struct {
  const char* service_url;

  const char* method_name;

  const grpc_auth_context* channel_auth_context;

  void* reserved;
} grpc_auth_metadata_context;

#define GRPC_METADATA_CREDENTIALS_PLUGIN_SYNC_MAX 4

typedef struct {
  int (*get_metadata)(
      void* state, grpc_auth_metadata_context context,
      grpc_credentials_plugin_metadata_cb cb, void* user_data,
      grpc_metadata creds_md[GRPC_METADATA_CREDENTIALS_PLUGIN_SYNC_MAX],
      size_t* num_creds_md, grpc_status_code* status,
      const char** error_details);

  void (*destroy)(void* state);

  void* state;

  const char* type;
} grpc_metadata_credentials_plugin;

GRPCAPI grpc_call_credentials* grpc_metadata_credentials_create_from_plugin(
    grpc_metadata_credentials_plugin plugin, void* reserved);

GRPCAPI grpc_channel* grpc_secure_channel_create(
    grpc_channel_credentials* creds, const char* target,
    const grpc_channel_args* args, void* reserved);

typedef struct grpc_server_credentials grpc_server_credentials;

GRPCAPI void grpc_server_credentials_release(grpc_server_credentials* creds);

typedef struct grpc_ssl_server_certificate_config
    grpc_ssl_server_certificate_config;

GRPCAPI 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);

GRPCAPI void grpc_ssl_server_certificate_config_destroy(
    grpc_ssl_server_certificate_config* config);

typedef grpc_ssl_certificate_config_reload_status (
    *grpc_ssl_server_certificate_config_callback)(
    void* user_data, grpc_ssl_server_certificate_config** config);

GRPCAPI 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);

GRPCAPI 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);

typedef struct grpc_ssl_server_credentials_options
    grpc_ssl_server_credentials_options;

GRPCAPI 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);

GRPCAPI 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);

GRPCAPI void grpc_ssl_server_credentials_options_destroy(
    grpc_ssl_server_credentials_options* options);

GRPCAPI grpc_server_credentials*
grpc_ssl_server_credentials_create_with_options(
    grpc_ssl_server_credentials_options* options);

GRPCAPI int grpc_server_add_secure_http2_port(grpc_server* server,
                                              const char* addr,
                                              grpc_server_credentials* creds);

GRPCAPI grpc_call_error grpc_call_set_credentials(grpc_call* call,
                                                  grpc_call_credentials* creds);

typedef void (*grpc_process_auth_metadata_done_cb)(
    void* user_data, const grpc_metadata* consumed_md, size_t num_consumed_md,
    const grpc_metadata* response_md, size_t num_response_md,
    grpc_status_code status, const char* error_details);

typedef struct {
  void (*process)(void* state, grpc_auth_context* context,
                  const grpc_metadata* md, size_t num_md,
                  grpc_process_auth_metadata_done_cb cb, void* user_data);
  void (*destroy)(void* state);
  void* state;
} grpc_auth_metadata_processor;

GRPCAPI void grpc_server_credentials_set_auth_metadata_processor(
    grpc_server_credentials* creds, grpc_auth_metadata_processor processor);

typedef struct grpc_alts_credentials_options grpc_alts_credentials_options;

GRPCAPI grpc_alts_credentials_options*
grpc_alts_credentials_client_options_create(void);

GRPCAPI grpc_alts_credentials_options*
grpc_alts_credentials_server_options_create(void);

GRPCAPI void grpc_alts_credentials_client_options_add_target_service_account(
    grpc_alts_credentials_options* options, const char* service_account);

GRPCAPI void grpc_alts_credentials_options_destroy(
    grpc_alts_credentials_options* options);

GRPCAPI grpc_channel_credentials* grpc_alts_credentials_create(
    const grpc_alts_credentials_options* options);

GRPCAPI grpc_server_credentials* grpc_alts_server_credentials_create(
    const grpc_alts_credentials_options* options);

GRPCAPI grpc_channel_credentials* grpc_local_credentials_create(
    grpc_local_connect_type type);

GRPCAPI grpc_server_credentials* grpc_local_server_credentials_create(
    grpc_local_connect_type type);

typedef struct grpc_tls_key_materials_config grpc_tls_key_materials_config;

typedef struct grpc_tls_credential_reload_config
    grpc_tls_credential_reload_config;

typedef struct grpc_tls_server_authorization_check_config
    grpc_tls_server_authorization_check_config;

typedef struct grpc_tls_credentials_options grpc_tls_credentials_options;

GRPCAPI grpc_tls_credentials_options* grpc_tls_credentials_options_create();

GRPCAPI int grpc_tls_credentials_options_set_cert_request_type(
    grpc_tls_credentials_options* options,
    grpc_ssl_client_certificate_request_type type);

GRPCAPI int grpc_tls_credentials_options_set_key_materials_config(
    grpc_tls_credentials_options* options,
    grpc_tls_key_materials_config* config);

GRPCAPI int grpc_tls_credentials_options_set_credential_reload_config(
    grpc_tls_credentials_options* options,
    grpc_tls_credential_reload_config* config);

GRPCAPI int grpc_tls_credentials_options_set_server_authorization_check_config(
    grpc_tls_credentials_options* options,
    grpc_tls_server_authorization_check_config* config);

GRPCAPI grpc_tls_key_materials_config* grpc_tls_key_materials_config_create();

GRPCAPI int grpc_tls_key_materials_config_set_key_materials(
    grpc_tls_key_materials_config* config, const char* pem_root_certs,
    const grpc_ssl_pem_key_cert_pair** pem_key_cert_pairs,
    size_t num_key_cert_pairs);

typedef struct grpc_tls_credential_reload_arg grpc_tls_credential_reload_arg;

typedef void (*grpc_tls_on_credential_reload_done_cb)(
    grpc_tls_credential_reload_arg* arg);

struct grpc_tls_credential_reload_arg {
  grpc_tls_on_credential_reload_done_cb cb;
  void* cb_user_data;
  grpc_tls_key_materials_config* key_materials_config;
  grpc_ssl_certificate_config_reload_status status;
  const char* error_details;
};

GRPCAPI grpc_tls_credential_reload_config*
grpc_tls_credential_reload_config_create(
    const void* config_user_data,
    int (*schedule)(void* config_user_data,
                    grpc_tls_credential_reload_arg* arg),
    void (*cancel)(void* config_user_data, grpc_tls_credential_reload_arg* arg),
    void (*destruct)(void* config_user_data));

typedef struct grpc_tls_server_authorization_check_arg
    grpc_tls_server_authorization_check_arg;

typedef void (*grpc_tls_on_server_authorization_check_done_cb)(
    grpc_tls_server_authorization_check_arg* arg);

struct grpc_tls_server_authorization_check_arg {
  grpc_tls_on_server_authorization_check_done_cb cb;
  void* cb_user_data;
  int success;
  const char* target_name;
  const char* peer_cert;
  grpc_status_code status;
  const char* error_details;
};

GRPCAPI grpc_tls_server_authorization_check_config*
grpc_tls_server_authorization_check_config_create(
    const void* config_user_data,
    int (*schedule)(void* config_user_data,
                    grpc_tls_server_authorization_check_arg* arg),
    void (*cancel)(void* config_user_data,
                   grpc_tls_server_authorization_check_arg* arg),
    void (*destruct)(void* config_user_data));

grpc_channel_credentials* grpc_tls_spiffe_credentials_create(
    grpc_tls_credentials_options* options);

grpc_server_credentials* grpc_tls_spiffe_server_credentials_create(
    grpc_tls_credentials_options* options);

#ifdef __cplusplus
}
#endif

#endif /* GRPC_GRPC_SECURITY_H */