src/core/lib/security/credentials/credentials.h

   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_CORE_LIB_SECURITY_CREDENTIALS_CREDENTIALS_H
  20 #define GRPC_CORE_LIB_SECURITY_CREDENTIALS_CREDENTIALS_H
  21
  22 #include <grpc/support/port_platform.h>
  23
  24 #include <string.h>
  25
  26 #include <string>
  27
  28 #include <grpc/grpc.h>
  29 #include <grpc/grpc_security.h>
  30 #include <grpc/support/sync.h>
  31 #include "src/core/lib/transport/metadata_batch.h"
  32
  33 #include "src/core/lib/gprpp/ref_counted.h"
  34 #include "src/core/lib/http/httpcli.h"
  35 #include "src/core/lib/http/parser.h"
  36 #include "src/core/lib/iomgr/polling_entity.h"
  37 #include "src/core/lib/security/security_connector/security_connector.h"
  38
  39 struct grpc_http_response;
  40
  41 /* --- Constants. --- */
  42
  43 typedef enum {
  44   GRPC_CREDENTIALS_OK = 0,
  45   GRPC_CREDENTIALS_ERROR
  46 } grpc_credentials_status;
  47
  48 #define GRPC_FAKE_TRANSPORT_SECURITY_TYPE "fake"
  49
  50 #define GRPC_CHANNEL_CREDENTIALS_TYPE_SSL "Ssl"
  51 #define GRPC_CHANNEL_CREDENTIALS_TYPE_FAKE_TRANSPORT_SECURITY \
  52   "FakeTransportSecurity"
  53 #define GRPC_CHANNEL_CREDENTIALS_TYPE_GOOGLE_DEFAULT "GoogleDefault"
  54
  55 #define GRPC_CALL_CREDENTIALS_TYPE_OAUTH2 "Oauth2"
  56 #define GRPC_CALL_CREDENTIALS_TYPE_JWT "Jwt"
  57 #define GRPC_CALL_CREDENTIALS_TYPE_IAM "Iam"
  58 #define GRPC_CALL_CREDENTIALS_TYPE_COMPOSITE "Composite"
  59
  60 #define GRPC_AUTHORIZATION_METADATA_KEY "authorization"
  61 #define GRPC_IAM_AUTHORIZATION_TOKEN_METADATA_KEY \
  62   "x-goog-iam-authorization-token"
  63 #define GRPC_IAM_AUTHORITY_SELECTOR_METADATA_KEY "x-goog-iam-authority-selector"
  64
  65 #define GRPC_SECURE_TOKEN_REFRESH_THRESHOLD_SECS 60
  66
  67 #define GRPC_COMPUTE_ENGINE_METADATA_HOST "metadata.google.internal."
  68 #define GRPC_COMPUTE_ENGINE_METADATA_TOKEN_PATH \
  69   "/computeMetadata/v1/instance/service-accounts/default/token"
  70
  71 #define GRPC_GOOGLE_OAUTH2_SERVICE_HOST "oauth2.googleapis.com"
  72 #define GRPC_GOOGLE_OAUTH2_SERVICE_TOKEN_PATH "/token"
  73
  74 #define GRPC_SERVICE_ACCOUNT_POST_BODY_PREFIX                         \
  75   "grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&" \
  76   "assertion="
  77
  78 #define GRPC_REFRESH_TOKEN_POST_BODY_FORMAT_STRING \
  79   "client_id=%s&client_secret=%s&refresh_token=%s&grant_type=refresh_token"
  80
  81 /* --- Google utils --- */
  82
  83 /* It is the caller's responsibility to gpr_free the result if not NULL. */
  84 std::string grpc_get_well_known_google_credentials_file_path(void);
  85
  86 /* Implementation function for the different platforms. */
  87 std::string grpc_get_well_known_google_credentials_file_path_impl(void);
  88
  89 /* Override for testing only. Not thread-safe */
  90 typedef std::string (*grpc_well_known_credentials_path_getter)(void);
  91 void grpc_override_well_known_credentials_path_getter(
  92     grpc_well_known_credentials_path_getter getter);
  93
  94 /* --- grpc_channel_credentials. --- */
  95
  96 #define GRPC_ARG_CHANNEL_CREDENTIALS "grpc.channel_credentials"
  97
  98 // This type is forward declared as a C struct and we cannot define it as a
  99 // class. Otherwise, compiler will complain about type mismatch due to
 100 // -Wmismatched-tags.
 101 struct grpc_channel_credentials
 102     : grpc_core::RefCounted<grpc_channel_credentials> {
 103  public:
 104   explicit grpc_channel_credentials(const char* type) : type_(type) {}
 105   ~grpc_channel_credentials() override = default;
 106
 107   // Creates a security connector for the channel. May also create new channel
 108   // args for the channel to be used in place of the passed in const args if
 109   // returned non NULL. In that case the caller is responsible for destroying
 110   // new_args after channel creation.
 111   virtual grpc_core::RefCountedPtr<grpc_channel_security_connector>
 112   create_security_connector(
 113       grpc_core::RefCountedPtr<grpc_call_credentials> call_creds,
 114       const char* target, const grpc_channel_args* args,
 115       grpc_channel_args** new_args) = 0;
 116
 117   // Creates a version of the channel credentials without any attached call
 118   // credentials. This can be used in order to open a channel to a non-trusted
 119   // gRPC load balancer.
 120   virtual grpc_core::RefCountedPtr<grpc_channel_credentials>
 121   duplicate_without_call_credentials() {
 122     // By default we just increment the refcount.
 123     return Ref();
 124   }
 125
 126   // Allows credentials to optionally modify a parent channel's args.
 127   // By default, leave channel args as is. The callee takes ownership
 128   // of the passed-in channel args, and the caller takes ownership
 129   // of the returned channel args.
 130   virtual grpc_channel_args* update_arguments(grpc_channel_args* args) {
 131     return args;
 132   }
 133
 134   const char* type() const { return type_; }
 135
 136  private:
 137   const char* type_;
 138 };
 139
 140 /* Util to encapsulate the channel credentials in a channel arg. */
 141 grpc_arg grpc_channel_credentials_to_arg(grpc_channel_credentials* credentials);
 142
 143 /* Util to get the channel credentials from a channel arg. */
 144 grpc_channel_credentials* grpc_channel_credentials_from_arg(
 145     const grpc_arg* arg);
 146
 147 /* Util to find the channel credentials from channel args. */
 148 grpc_channel_credentials* grpc_channel_credentials_find_in_args(
 149     const grpc_channel_args* args);
 150
 151 /* --- grpc_credentials_mdelem_array. --- */
 152
 153 struct grpc_credentials_mdelem_array {
 154   grpc_mdelem* md = nullptr;
 155   size_t size = 0;
 156 };
 157 /// Takes a new ref to \a md.
 158 void grpc_credentials_mdelem_array_add(grpc_credentials_mdelem_array* list,
 159                                        grpc_mdelem md);
 160
 161 /// Appends all elements from \a src to \a dst, taking a new ref to each one.
 162 void grpc_credentials_mdelem_array_append(grpc_credentials_mdelem_array* dst,
 163                                           grpc_credentials_mdelem_array* src);
 164
 165 void grpc_credentials_mdelem_array_destroy(grpc_credentials_mdelem_array* list);
 166
 167 /* --- grpc_call_credentials. --- */
 168
 169 // This type is forward declared as a C struct and we cannot define it as a
 170 // class. Otherwise, compiler will complain about type mismatch due to
 171 // -Wmismatched-tags.
 172 struct grpc_call_credentials
 173     : public grpc_core::RefCounted<grpc_call_credentials> {
 174  public:
 175   explicit grpc_call_credentials(
 176       const char* type,
 177       grpc_security_level min_security_level = GRPC_PRIVACY_AND_INTEGRITY)
 178       : type_(type), min_security_level_(min_security_level) {}
 179
 180   ~grpc_call_credentials() override = default;
 181
 182   // Returns true if completed synchronously, in which case \a error will
 183   // be set to indicate the result.  Otherwise, \a on_request_metadata will
 184   // be invoked asynchronously when complete.  \a md_array will be populated
 185   // with the resulting metadata once complete.
 186   virtual bool get_request_metadata(grpc_polling_entity* pollent,
 187                                     grpc_auth_metadata_context context,
 188                                     grpc_credentials_mdelem_array* md_array,
 189                                     grpc_closure* on_request_metadata,
 190                                     grpc_error** error) = 0;
 191
 192   // Cancels a pending asynchronous operation started by
 193   // grpc_call_credentials_get_request_metadata() with the corresponding
 194   // value of \a md_array.
 195   virtual void cancel_get_request_metadata(
 196       grpc_credentials_mdelem_array* md_array, grpc_error* error) = 0;
 197
 198   virtual grpc_security_level min_security_level() const {
 199     return min_security_level_;
 200   }
 201
 202   virtual std::string debug_string() {
 203     return "grpc_call_credentials did not provide debug string";
 204   }
 205
 206   const char* type() const { return type_; }
 207
 208  private:
 209   const char* type_;
 210   const grpc_security_level min_security_level_;
 211 };
 212
 213 /* Metadata-only credentials with the specified key and value where
 214    asynchronicity can be simulated for testing. */
 215 grpc_call_credentials* grpc_md_only_test_credentials_create(
 216     const char* md_key, const char* md_value, bool is_async);
 217
 218 /* --- grpc_server_credentials. --- */
 219
 220 // This type is forward declared as a C struct and we cannot define it as a
 221 // class. Otherwise, compiler will complain about type mismatch due to
 222 // -Wmismatched-tags.
 223 struct grpc_server_credentials
 224     : public grpc_core::RefCounted<grpc_server_credentials> {
 225  public:
 226   explicit grpc_server_credentials(const char* type) : type_(type) {}
 227
 228   ~grpc_server_credentials() override { DestroyProcessor(); }
 229
 230   // Ownership of \a args is not passed.
 231   virtual grpc_core::RefCountedPtr<grpc_server_security_connector>
 232   create_security_connector(const grpc_channel_args* args) = 0;
 233
 234   const char* type() const { return type_; }
 235
 236   const grpc_auth_metadata_processor& auth_metadata_processor() const {
 237     return processor_;
 238   }
 239   void set_auth_metadata_processor(
 240       const grpc_auth_metadata_processor& processor);
 241
 242  private:
 243   void DestroyProcessor() {
 244     if (processor_.destroy != nullptr && processor_.state != nullptr) {
 245       processor_.destroy(processor_.state);
 246     }
 247   }
 248
 249   const char* type_;
 250   grpc_auth_metadata_processor processor_ =
 251       grpc_auth_metadata_processor();  // Zero-initialize the C struct.
 252 };
 253
 254 #define GRPC_SERVER_CREDENTIALS_ARG "grpc.server_credentials"
 255
 256 grpc_arg grpc_server_credentials_to_arg(grpc_server_credentials* c);
 257 grpc_server_credentials* grpc_server_credentials_from_arg(const grpc_arg* arg);
 258 grpc_server_credentials* grpc_find_server_credentials_in_args(
 259     const grpc_channel_args* args);
 260
 261 /* -- Credentials Metadata Request. -- */
 262
 263 struct grpc_credentials_metadata_request {
 264   explicit grpc_credentials_metadata_request(
 265       grpc_core::RefCountedPtr<grpc_call_credentials> creds)
 266       : creds(std::move(creds)) {}
 267   ~grpc_credentials_metadata_request() {
 268     grpc_http_response_destroy(&response);
 269   }
 270
 271   grpc_core::RefCountedPtr<grpc_call_credentials> creds;
 272   grpc_http_response response;
 273 };
 274
 275 inline grpc_credentials_metadata_request*
 276 grpc_credentials_metadata_request_create(
 277     grpc_core::RefCountedPtr<grpc_call_credentials> creds) {
 278   return new grpc_credentials_metadata_request(std::move(creds));
 279 }
 280
 281 inline void grpc_credentials_metadata_request_destroy(
 282     grpc_credentials_metadata_request* r) {
 283   delete r;
 284 }
 285
 286 #endif /* GRPC_CORE_LIB_SECURITY_CREDENTIALS_CREDENTIALS_H */