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
26#include <grpc/grpc_security_constants.h>
27#include <grpcpp/channel.h>
28#include <grpcpp/impl/codegen/grpc_library.h>
29#include <grpcpp/security/auth_context.h>
30#include <grpcpp/security/tls_credentials_options.h>
31#include <grpcpp/support/channel_arguments.h>
32#include <grpcpp/support/client_interceptor.h>
33#include <grpcpp/support/status.h>
34#include <grpcpp/support/string_ref.h>
35
36struct grpc_call;
37
38namespace grpc {
39class CallCredentials;
40class SecureCallCredentials;
41class SecureChannelCredentials;
42class ChannelCredentials;
43
44std::shared_ptr<Channel> CreateCustomChannel(
45 const grpc::string& target,
46 const std::shared_ptr<grpc::ChannelCredentials>& creds,
47 const grpc::ChannelArguments& args);
48
49namespace experimental {
50std::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} // namespace experimental
58
59/// Builds XDS Credentials.
60std::shared_ptr<ChannelCredentials> XdsCredentials(
61 const std::shared_ptr<ChannelCredentials>& fallback_creds);
62
63/// A channel credentials object encapsulates all the state needed by a client
64/// to authenticate with a server for a given channel.
65/// It can make various assertions, e.g., about the client’s identity, role
66/// for all the calls on that channel.
67///
68/// \see https://grpc.io/docs/guides/auth.html
69class ChannelCredentials : private grpc::GrpcLibraryCodegen {
70 public:
71 ChannelCredentials();
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::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>
95 grpc::experimental::CreateCustomChannelWithInterceptors(
96 const grpc::string& target,
97 const std::shared_ptr<grpc::ChannelCredentials>& creds,
98 const grpc::ChannelArguments& args,
99 std::vector<std::unique_ptr<
100 grpc::experimental::ClientInterceptorFactoryInterface>>
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<
111 grpc::experimental::ClientInterceptorFactoryInterface>>
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
122/// A call credentials object encapsulates the state needed by a client to
123/// authenticate with a server for a given call on a channel.
124///
125/// \see https://grpc.io/docs/guides/auth.html
126class CallCredentials : private grpc::GrpcLibraryCodegen {
127 public:
128 CallCredentials();
129 ~CallCredentials() override;
130
131 /// Apply this instance's credentials to \a call.
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
149/// Options used to build SslCredentials.
150struct SslCredentialsOptions {
151 /// The buffer containing the PEM encoding of the server root certificates. If
152 /// this parameter is empty, the default roots will be used. The default
153 /// roots can be overridden using the \a GRPC_DEFAULT_SSL_ROOTS_FILE_PATH
154 /// environment variable pointing to a file on the file system containing the
155 /// roots.
156 grpc::string pem_root_certs;
157
158 /// The buffer containing the PEM encoding of the client's private key. This
159 /// parameter can be empty if the client does not have a private key.
160 grpc::string pem_private_key;
161
162 /// The buffer containing the PEM encoding of the client's certificate chain.
163 /// This parameter can be empty if the client does not have a certificate
164 /// chain.
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
173/// Builds credentials with reasonable defaults.
174///
175/// \warning Only use these credentials when connecting to a Google endpoint.
176/// Using these credentials to connect to any other service may result in this
177/// service being able to impersonate your client for requests to Google
178/// services.
179std::shared_ptr<ChannelCredentials> GoogleDefaultCredentials();
180
181/// Builds SSL Credentials given SSL specific options
182std::shared_ptr<ChannelCredentials> SslCredentials(
183 const SslCredentialsOptions& options);
184
185/// Builds credentials for use when running in GCE
186///
187/// \warning Only use these credentials when connecting to a Google endpoint.
188/// Using these credentials to connect to any other service may result in this
189/// service being able to impersonate your client for requests to Google
190/// services.
191std::shared_ptr<CallCredentials> GoogleComputeEngineCredentials();
192
193constexpr long kMaxAuthTokenLifetimeSecs = 3600;
194
195/// Builds Service Account JWT Access credentials.
196/// json_key is the JSON key string containing the client's private key.
197/// token_lifetime_seconds is the lifetime in seconds of each Json Web Token
198/// (JWT) created with this credentials. It should not exceed
199/// \a kMaxAuthTokenLifetimeSecs or will be cropped to this value.
200std::shared_ptr<CallCredentials> ServiceAccountJWTAccessCredentials(
201 const grpc::string& json_key,
202 long token_lifetime_seconds = kMaxAuthTokenLifetimeSecs);
203
204/// Builds refresh token credentials.
205/// json_refresh_token is the JSON string containing the refresh token along
206/// with a client_id and client_secret.
207///
208/// \warning Only use these credentials when connecting to a Google endpoint.
209/// Using these credentials to connect to any other service may result in this
210/// service being able to impersonate your client for requests to Google
211/// services.
212std::shared_ptr<CallCredentials> GoogleRefreshTokenCredentials(
213 const grpc::string& json_refresh_token);
214
215/// Builds access token credentials.
216/// access_token is an oauth2 access token that was fetched using an out of band
217/// mechanism.
218///
219/// \warning Only use these credentials when connecting to a Google endpoint.
220/// Using these credentials to connect to any other service may result in this
221/// service being able to impersonate your client for requests to Google
222/// services.
223std::shared_ptr<CallCredentials> AccessTokenCredentials(
224 const grpc::string& access_token);
225
226/// Builds IAM credentials.
227///
228/// \warning Only use these credentials when connecting to a Google endpoint.
229/// Using these credentials to connect to any other service may result in this
230/// service being able to impersonate your client for requests to Google
231/// services.
232std::shared_ptr<CallCredentials> GoogleIAMCredentials(
233 const grpc::string& authorization_token,
234 const grpc::string& authority_selector);
235
236/// Combines a channel credentials and a call credentials into a composite
237/// channel credentials.
238std::shared_ptr<ChannelCredentials> CompositeChannelCredentials(
239 const std::shared_ptr<ChannelCredentials>& channel_creds,
240 const std::shared_ptr<CallCredentials>& call_creds);
241
242/// Combines two call credentials objects into a composite call credentials.
243std::shared_ptr<CallCredentials> CompositeCallCredentials(
244 const std::shared_ptr<CallCredentials>& creds1,
245 const std::shared_ptr<CallCredentials>& creds2);
246
247/// Credentials for an unencrypted, unauthenticated channel
248std::shared_ptr<ChannelCredentials> InsecureChannelCredentials();
249
250/// User defined metadata credentials.
251class MetadataCredentialsPlugin {
252 public:
253 virtual ~MetadataCredentialsPlugin() {}
254
255 /// If this method returns true, the Process function will be scheduled in
256 /// a different thread from the one processing the call.
257 virtual bool IsBlocking() const { return true; }
258
259 /// Type of credentials this plugin is implementing.
260 virtual const char* GetType() const { return ""; }
261
262 /// Gets the auth metatada produced by this plugin.
263 /// The fully qualified method name is:
264 /// service_url + "/" + method_name.
265 /// The channel_auth_context contains (among other things), the identity of
266 /// the server.
267 virtual grpc::Status GetMetadata(
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
277std::shared_ptr<CallCredentials> MetadataCredentialsFromPlugin(
278 std::unique_ptr<MetadataCredentialsPlugin> plugin);
279
280/// Builds External Account credentials.
281/// json_string is the JSON string containing the credentials options.
282/// scopes contains the scopes to be binded with the credentials.
283std::shared_ptr<CallCredentials> ExternalAccountCredentials(
284 const grpc::string& json_string, const std::vector<grpc::string>& scopes);
285
286namespace experimental {
287
288/// Options for creating STS Oauth Token Exchange credentials following the IETF
289/// draft https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16.
290/// Optional fields may be set to empty string. It is the responsibility of the
291/// caller to ensure that the subject and actor tokens are refreshed on disk at
292/// the specified paths.
293struct StsCredentialsOptions {
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
305grpc::Status StsCredentialsOptionsFromJson(const std::string& json_string,
306 StsCredentialsOptions* options);
307
308/// Creates STS credentials options from the $STS_CREDENTIALS environment
309/// variable. This environment variable points to the path of a JSON file
310/// comforming to the schema described above.
311grpc::Status StsCredentialsOptionsFromEnv(StsCredentialsOptions* options);
312
313std::shared_ptr<CallCredentials> StsCredentials(
314 const StsCredentialsOptions& options);
315
316std::shared_ptr<CallCredentials> MetadataCredentialsFromPlugin(
317 std::unique_ptr<MetadataCredentialsPlugin> plugin,
318 grpc_security_level min_security_level);
319
320/// Options used to build AltsCredentials.
321struct AltsCredentialsOptions {
322 /// service accounts of target endpoint that will be acceptable
323 /// by the client. If service accounts are provided and none of them matches
324 /// that of the server, authentication will fail.
325 std::vector<grpc::string> target_service_accounts;
326};
327
328/// Builds ALTS Credentials given ALTS specific options
329std::shared_ptr<ChannelCredentials> AltsCredentials(
330 const AltsCredentialsOptions& options);
331
332/// Builds Local Credentials.
333std::shared_ptr<ChannelCredentials> LocalCredentials(
334 grpc_local_connect_type type);
335
336/// Builds TLS Credentials given TLS options.
337std::shared_ptr<ChannelCredentials> TlsCredentials(
338 const TlsChannelCredentialsOptions& options);
339
340} // namespace experimental
341} // namespace grpc
342
343#endif // GRPCPP_SECURITY_CREDENTIALS_H
344

source code of include/grpcpp/security/credentials.h