GRPC C++  1.39.1
credentials.h
Go to the documentation of this file.
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 GRPCPP_SECURITY_CREDENTIALS_H
20 #define GRPCPP_SECURITY_CREDENTIALS_H
21 
22 #include <map>
23 #include <memory>
24 #include <vector>
25 
27 #include <grpcpp/channel.h>
33 #include <grpcpp/support/status.h>
35 
36 struct grpc_call;
37 
38 namespace grpc {
39 class CallCredentials;
40 class SecureCallCredentials;
41 class SecureChannelCredentials;
42 class ChannelCredentials;
43 
44 std::shared_ptr<Channel> CreateCustomChannel(
45  const grpc::string& target,
46  const std::shared_ptr<grpc::ChannelCredentials>& creds,
47  const grpc::ChannelArguments& args);
48 
49 namespace experimental {
50 std::shared_ptr<grpc::Channel> CreateCustomChannelWithInterceptors(
51  const grpc::string& target,
52  const std::shared_ptr<grpc::ChannelCredentials>& creds,
53  const grpc::ChannelArguments& args,
54  std::vector<
55  std::unique_ptr<grpc::experimental::ClientInterceptorFactoryInterface>>
56  interceptor_creators);
57 
59 std::shared_ptr<ChannelCredentials> XdsCredentials(
60  const std::shared_ptr<ChannelCredentials>& fallback_creds);
61 } // namespace experimental
62 
70  public:
72  ~ChannelCredentials() override;
73 
74  protected:
75  friend std::shared_ptr<ChannelCredentials> CompositeChannelCredentials(
76  const std::shared_ptr<ChannelCredentials>& channel_creds,
77  const std::shared_ptr<CallCredentials>& call_creds);
78 
79  // TODO(yashykt): We need this friend declaration mainly for access to
80  // AsSecureCredentials(). Once we are able to remove insecure builds from gRPC
81  // (and also internal dependencies on the indirect method of creating a
82  // channel through credentials), we would be able to remove this.
83  friend std::shared_ptr<ChannelCredentials> grpc::experimental::XdsCredentials(
84  const std::shared_ptr<ChannelCredentials>& fallback_creds);
85 
86  virtual SecureChannelCredentials* AsSecureCredentials() = 0;
87 
88  private:
89  friend std::shared_ptr<grpc::Channel> CreateCustomChannel(
90  const grpc::string& target,
91  const std::shared_ptr<grpc::ChannelCredentials>& creds,
92  const grpc::ChannelArguments& args);
93 
94  friend std::shared_ptr<grpc::Channel>
96  const grpc::string& target,
97  const std::shared_ptr<grpc::ChannelCredentials>& creds,
98  const grpc::ChannelArguments& args,
99  std::vector<std::unique_ptr<
101  interceptor_creators);
102 
103  virtual std::shared_ptr<Channel> CreateChannelImpl(
104  const grpc::string& target, const ChannelArguments& args) = 0;
105 
106  // This function should have been a pure virtual function, but it is
107  // implemented as a virtual function so that it does not break API.
108  virtual std::shared_ptr<Channel> CreateChannelWithInterceptors(
109  const grpc::string& /*target*/, const ChannelArguments& /*args*/,
110  std::vector<std::unique_ptr<
112  /*interceptor_creators*/) {
113  return nullptr;
114  }
115 
116  // TODO(yashkt): This is a hack that is needed since InsecureCredentials can
117  // not use grpc_channel_credentials internally and should be removed after
118  // insecure builds are removed from gRPC.
119  virtual bool IsInsecure() const { return false; }
120 };
121 
127  public:
129  ~CallCredentials() override;
130 
132  virtual bool ApplyToCall(grpc_call* call) = 0;
133  virtual grpc::string DebugString() {
134  return "CallCredentials did not provide a debug string";
135  }
136 
137  protected:
138  friend std::shared_ptr<ChannelCredentials> CompositeChannelCredentials(
139  const std::shared_ptr<ChannelCredentials>& channel_creds,
140  const std::shared_ptr<CallCredentials>& call_creds);
141 
142  friend std::shared_ptr<CallCredentials> CompositeCallCredentials(
143  const std::shared_ptr<CallCredentials>& creds1,
144  const std::shared_ptr<CallCredentials>& creds2);
145 
146  virtual SecureCallCredentials* AsSecureCredentials() = 0;
147 };
148 
156  grpc::string pem_root_certs;
157 
160  grpc::string pem_private_key;
161 
165  grpc::string pem_cert_chain;
166 };
167 
168 // Factories for building different types of Credentials The functions may
169 // return empty shared_ptr when credentials cannot be created. If a
170 // Credentials pointer is returned, it can still be invalid when used to create
171 // a channel. A lame channel will be created then and all rpcs will fail on it.
172 
179 std::shared_ptr<ChannelCredentials> GoogleDefaultCredentials();
180 
182 std::shared_ptr<ChannelCredentials> SslCredentials(
183  const SslCredentialsOptions& options);
184 
191 std::shared_ptr<CallCredentials> GoogleComputeEngineCredentials();
192 
193 constexpr long kMaxAuthTokenLifetimeSecs = 3600;
194 
200 std::shared_ptr<CallCredentials> ServiceAccountJWTAccessCredentials(
201  const grpc::string& json_key,
202  long token_lifetime_seconds = kMaxAuthTokenLifetimeSecs);
203 
212 std::shared_ptr<CallCredentials> GoogleRefreshTokenCredentials(
213  const grpc::string& json_refresh_token);
214 
223 std::shared_ptr<CallCredentials> AccessTokenCredentials(
224  const grpc::string& access_token);
225 
232 std::shared_ptr<CallCredentials> GoogleIAMCredentials(
233  const grpc::string& authorization_token,
234  const grpc::string& authority_selector);
235 
238 std::shared_ptr<ChannelCredentials> CompositeChannelCredentials(
239  const std::shared_ptr<ChannelCredentials>& channel_creds,
240  const std::shared_ptr<CallCredentials>& call_creds);
241 
243 std::shared_ptr<CallCredentials> CompositeCallCredentials(
244  const std::shared_ptr<CallCredentials>& creds1,
245  const std::shared_ptr<CallCredentials>& creds2);
246 
248 std::shared_ptr<ChannelCredentials> InsecureChannelCredentials();
249 
252  public:
254 
257  virtual bool IsBlocking() const { return true; }
258 
260  virtual const char* GetType() const { return ""; }
261 
268  grpc::string_ref service_url, grpc::string_ref method_name,
269  const grpc::AuthContext& channel_auth_context,
270  std::multimap<grpc::string, grpc::string>* metadata) = 0;
271 
272  virtual grpc::string DebugString() {
273  return "MetadataCredentialsPlugin did not provide a debug string";
274  }
275 };
276 
277 std::shared_ptr<CallCredentials> MetadataCredentialsFromPlugin(
278  std::unique_ptr<MetadataCredentialsPlugin> plugin);
279 
283 std::shared_ptr<CallCredentials> ExternalAccountCredentials(
284  const grpc::string& json_string, const std::vector<grpc::string>& scopes);
285 
286 namespace experimental {
287 
294  grpc::string token_exchange_service_uri; // Required.
295  grpc::string resource; // Optional.
296  grpc::string audience; // Optional.
297  grpc::string scope; // Optional.
298  grpc::string requested_token_type; // Optional.
299  grpc::string subject_token_path; // Required.
300  grpc::string subject_token_type; // Required.
301  grpc::string actor_token_path; // Optional.
302  grpc::string actor_token_type; // Optional.
303 };
304 
305 grpc::Status StsCredentialsOptionsFromJson(const std::string& json_string,
306  StsCredentialsOptions* options);
307 
312 
313 std::shared_ptr<CallCredentials> StsCredentials(
314  const StsCredentialsOptions& options);
315 
316 std::shared_ptr<CallCredentials> MetadataCredentialsFromPlugin(
317  std::unique_ptr<MetadataCredentialsPlugin> plugin,
318  grpc_security_level min_security_level);
319 
325  std::vector<grpc::string> target_service_accounts;
326 };
327 
329 std::shared_ptr<ChannelCredentials> AltsCredentials(
330  const AltsCredentialsOptions& options);
331 
333 std::shared_ptr<ChannelCredentials> LocalCredentials(
335 
337 std::shared_ptr<ChannelCredentials> TlsCredentials(
338  const TlsChannelCredentialsOptions& options);
339 
340 } // namespace experimental
341 } // namespace grpc
342 
343 #endif // GRPCPP_SECURITY_CREDENTIALS_H
Class encapsulating the Authentication Information.
Definition: auth_context.h:65
A call credentials object encapsulates the state needed by a client to authenticate with a server for...
Definition: credentials.h:126
friend std::shared_ptr< CallCredentials > CompositeCallCredentials(const std::shared_ptr< CallCredentials > &creds1, const std::shared_ptr< CallCredentials > &creds2)
Combines two call credentials objects into a composite call credentials.
virtual SecureCallCredentials * AsSecureCredentials()=0
virtual grpc::string DebugString()
Definition: credentials.h:133
virtual bool ApplyToCall(grpc_call *call)=0
Apply this instance's credentials to call.
friend std::shared_ptr< ChannelCredentials > CompositeChannelCredentials(const std::shared_ptr< ChannelCredentials > &channel_creds, const std::shared_ptr< CallCredentials > &call_creds)
Combines a channel credentials and a call credentials into a composite channel credentials.
~CallCredentials() override
Options for channel creation.
Definition: channel_arguments.h:39
A channel credentials object encapsulates all the state needed by a client to authenticate with a ser...
Definition: credentials.h:69
friend std::shared_ptr< grpc::Channel > CreateCustomChannel(const grpc::string &target, const std::shared_ptr< grpc::ChannelCredentials > &creds, const grpc::ChannelArguments &args)
~ChannelCredentials() override
friend std::shared_ptr< ChannelCredentials > CompositeChannelCredentials(const std::shared_ptr< ChannelCredentials > &channel_creds, const std::shared_ptr< CallCredentials > &call_creds)
Combines a channel credentials and a call credentials into a composite channel credentials.
virtual SecureChannelCredentials * AsSecureCredentials()=0
Classes that require gRPC to be initialized should inherit from this class.
Definition: grpc_library.h:38
User defined metadata credentials.
Definition: credentials.h:251
virtual grpc::string DebugString()
Definition: credentials.h:272
virtual bool IsBlocking() const
If this method returns true, the Process function will be scheduled in a different thread from the on...
Definition: credentials.h:257
virtual ~MetadataCredentialsPlugin()
Definition: credentials.h:253
virtual const char * GetType() const
Type of credentials this plugin is implementing.
Definition: credentials.h:260
virtual grpc::Status GetMetadata(grpc::string_ref service_url, grpc::string_ref method_name, const grpc::AuthContext &channel_auth_context, std::multimap< grpc::string, grpc::string > *metadata)=0
Gets the auth metatada produced by this plugin.
Did it work? If it didn't, why?
Definition: status.h:31
Definition: tls_credentials_options.h:208
This class is a non owning reference to a string.
Definition: string_ref.h:41
grpc_local_connect_type
Type of local connections for which local channel/server credentials will be applied.
Definition: grpc_security_constants.h:155
grpc_security_level
Definition: grpc_security_constants.h:129
struct grpc_call grpc_call
A Call represents an RPC.
Definition: grpc_types.h:70
std::shared_ptr< CallCredentials > StsCredentials(const StsCredentialsOptions &options)
grpc::Status StsCredentialsOptionsFromEnv(StsCredentialsOptions *options)
Creates STS credentials options from the $STS_CREDENTIALS environment variable.
std::shared_ptr< CallCredentials > MetadataCredentialsFromPlugin(std::unique_ptr< MetadataCredentialsPlugin > plugin, grpc_security_level min_security_level)
grpc::Status StsCredentialsOptionsFromJson(const std::string &json_string, StsCredentialsOptions *options)
std::shared_ptr< ChannelCredentials > LocalCredentials(grpc_local_connect_type type)
Builds Local Credentials.
std::shared_ptr< ChannelCredentials > XdsCredentials(const std::shared_ptr< ChannelCredentials > &fallback_creds)
Builds XDS Credentials.
std::shared_ptr< ChannelCredentials > AltsCredentials(const AltsCredentialsOptions &options)
Builds ALTS Credentials given ALTS specific options.
std::shared_ptr< Channel > CreateCustomChannelWithInterceptors(const grpc::string &target, const std::shared_ptr< ChannelCredentials > &creds, const ChannelArguments &args, std::vector< std::unique_ptr< experimental::ClientInterceptorFactoryInterface >> interceptor_creators)
Create a new custom Channel pointing to target with interceptors being invoked per call.
std::shared_ptr< ChannelCredentials > TlsCredentials(const TlsChannelCredentialsOptions &options)
Builds TLS Credentials given TLS options.
An Alarm posts the user-provided tag to its associated completion queue or invokes the user-provided ...
Definition: alarm.h:33
std::shared_ptr< ChannelCredentials > CompositeChannelCredentials(const std::shared_ptr< ChannelCredentials > &channel_creds, const std::shared_ptr< CallCredentials > &call_creds)
Combines a channel credentials and a call credentials into a composite channel credentials.
std::shared_ptr< CallCredentials > ExternalAccountCredentials(const grpc::string &json_string, const std::vector< grpc::string > &scopes)
Builds External Account credentials.
std::shared_ptr< Channel > CreateCustomChannel(const grpc::string &target, const std::shared_ptr< ChannelCredentials > &creds, const ChannelArguments &args)
Create a new custom Channel pointing to target.
std::shared_ptr< ChannelCredentials > GoogleDefaultCredentials()
Builds credentials with reasonable defaults.
std::shared_ptr< ChannelCredentials > InsecureChannelCredentials()
Credentials for an unencrypted, unauthenticated channel.
std::shared_ptr< CallCredentials > MetadataCredentialsFromPlugin(std::unique_ptr< MetadataCredentialsPlugin > plugin)
std::shared_ptr< ChannelCredentials > SslCredentials(const SslCredentialsOptions &options)
Builds SSL Credentials given SSL specific options.
std::shared_ptr< CallCredentials > ServiceAccountJWTAccessCredentials(const grpc::string &json_key, long token_lifetime_seconds=kMaxAuthTokenLifetimeSecs)
Builds Service Account JWT Access credentials.
std::shared_ptr< CallCredentials > GoogleRefreshTokenCredentials(const grpc::string &json_refresh_token)
Builds refresh token credentials.
constexpr long kMaxAuthTokenLifetimeSecs
Definition: credentials.h:193
std::shared_ptr< CallCredentials > GoogleIAMCredentials(const grpc::string &authorization_token, const grpc::string &authority_selector)
Builds IAM credentials.
std::shared_ptr< CallCredentials > AccessTokenCredentials(const grpc::string &access_token)
Builds access token credentials.
std::shared_ptr< CallCredentials > GoogleComputeEngineCredentials()
Builds credentials for use when running in GCE.
std::shared_ptr< CallCredentials > CompositeCallCredentials(const std::shared_ptr< CallCredentials > &creds1, const std::shared_ptr< CallCredentials > &creds2)
Combines two call credentials objects into a composite call credentials.
Options used to build SslCredentials.
Definition: credentials.h:150
grpc::string pem_cert_chain
The buffer containing the PEM encoding of the client's certificate chain.
Definition: credentials.h:165
grpc::string pem_root_certs
The buffer containing the PEM encoding of the server root certificates.
Definition: credentials.h:156
grpc::string pem_private_key
The buffer containing the PEM encoding of the client's private key.
Definition: credentials.h:160
Options used to build AltsCredentials.
Definition: credentials.h:321
std::vector< grpc::string > target_service_accounts
service accounts of target endpoint that will be acceptable by the client.
Definition: credentials.h:325
Options for creating STS Oauth Token Exchange credentials following the IETF draft https://tools....
Definition: credentials.h:293
grpc::string scope
Definition: credentials.h:297
grpc::string token_exchange_service_uri
Definition: credentials.h:294
grpc::string actor_token_path
Definition: credentials.h:301
grpc::string subject_token_path
Definition: credentials.h:299
grpc::string actor_token_type
Definition: credentials.h:302
grpc::string audience
Definition: credentials.h:296
grpc::string resource
Definition: credentials.h:295
grpc::string requested_token_type
Definition: credentials.h:298
grpc::string subject_token_type
Definition: credentials.h:300