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_IMPL_H
20#define GRPCPP_SECURITY_CREDENTIALS_IMPL_H
21
22#include <map>
23#include <memory>
24#include <vector>
25
26#include <grpc/grpc_security_constants.h>
27#include <grpcpp/channel_impl.h>
28#include <grpcpp/impl/codegen/client_interceptor.h>
29#include <grpcpp/impl/codegen/grpc_library.h>
30#include <grpcpp/security/auth_context.h>
31#include <grpcpp/security/tls_credentials_options.h>
32#include <grpcpp/support/channel_arguments_impl.h>
33#include <grpcpp/support/status.h>
34#include <grpcpp/support/string_ref.h>
35
36struct grpc_call;
37
38namespace grpc_impl {
39
40class ChannelCredentials;
41class CallCredentials;
42class SecureCallCredentials;
43class SecureChannelCredentials;
44
45std::shared_ptr<Channel> CreateCustomChannelImpl(
46 const grpc::string& target,
47 const std::shared_ptr<ChannelCredentials>& creds,
48 const ChannelArguments& args);
49
50namespace experimental {
51std::shared_ptr<Channel> CreateCustomChannelWithInterceptors(
52 const grpc::string& target,
53 const std::shared_ptr<ChannelCredentials>& creds,
54 const ChannelArguments& args,
55 std::vector<
56 std::unique_ptr<grpc::experimental::ClientInterceptorFactoryInterface>>
57 interceptor_creators);
58}
59
60/// A channel credentials object encapsulates all the state needed by a client
61/// to authenticate with a server for a given channel.
62/// It can make various assertions, e.g., about the client’s identity, role
63/// for all the calls on that channel.
64///
65/// \see https://grpc.io/docs/guides/auth.html
66class ChannelCredentials : private grpc::GrpcLibraryCodegen {
67 public:
68 ChannelCredentials();
69 ~ChannelCredentials();
70
71 protected:
72 friend std::shared_ptr<ChannelCredentials> CompositeChannelCredentials(
73 const std::shared_ptr<ChannelCredentials>& channel_creds,
74 const std::shared_ptr<CallCredentials>& call_creds);
75
76 virtual SecureChannelCredentials* AsSecureCredentials() = 0;
77
78 private:
79 friend std::shared_ptr<Channel> CreateCustomChannelImpl(
80 const grpc::string& target,
81 const std::shared_ptr<ChannelCredentials>& creds,
82 const ChannelArguments& args);
83
84 friend std::shared_ptr<Channel>
85 grpc_impl::experimental::CreateCustomChannelWithInterceptors(
86 const grpc::string& target,
87 const std::shared_ptr<ChannelCredentials>& creds,
88 const ChannelArguments& args,
89 std::vector<std::unique_ptr<
90 grpc::experimental::ClientInterceptorFactoryInterface>>
91 interceptor_creators);
92
93 virtual std::shared_ptr<Channel> CreateChannelImpl(
94 const grpc::string& target, const ChannelArguments& args) = 0;
95
96 // This function should have been a pure virtual function, but it is
97 // implemented as a virtual function so that it does not break API.
98 virtual std::shared_ptr<Channel> CreateChannelWithInterceptors(
99 const grpc::string& /*target*/, const ChannelArguments& /*args*/,
100 std::vector<std::unique_ptr<
101 grpc::experimental::ClientInterceptorFactoryInterface>>
102 /*interceptor_creators*/) {
103 return nullptr;
104 }
105};
106
107/// A call credentials object encapsulates the state needed by a client to
108/// authenticate with a server for a given call on a channel.
109///
110/// \see https://grpc.io/docs/guides/auth.html
111class CallCredentials : private grpc::GrpcLibraryCodegen {
112 public:
113 CallCredentials();
114 ~CallCredentials();
115
116 /// Apply this instance's credentials to \a call.
117 virtual bool ApplyToCall(grpc_call* call) = 0;
118 virtual grpc::string DebugString() {
119 return "CallCredentials did not provide a debug string";
120 }
121
122 protected:
123 friend std::shared_ptr<ChannelCredentials> CompositeChannelCredentials(
124 const std::shared_ptr<ChannelCredentials>& channel_creds,
125 const std::shared_ptr<CallCredentials>& call_creds);
126
127 friend std::shared_ptr<CallCredentials> CompositeCallCredentials(
128 const std::shared_ptr<CallCredentials>& creds1,
129 const std::shared_ptr<CallCredentials>& creds2);
130
131 virtual SecureCallCredentials* AsSecureCredentials() = 0;
132};
133
134/// Options used to build SslCredentials.
135struct SslCredentialsOptions {
136 /// The buffer containing the PEM encoding of the server root certificates. If
137 /// this parameter is empty, the default roots will be used. The default
138 /// roots can be overridden using the \a GRPC_DEFAULT_SSL_ROOTS_FILE_PATH
139 /// environment variable pointing to a file on the file system containing the
140 /// roots.
141 grpc::string pem_root_certs;
142
143 /// The buffer containing the PEM encoding of the client's private key. This
144 /// parameter can be empty if the client does not have a private key.
145 grpc::string pem_private_key;
146
147 /// The buffer containing the PEM encoding of the client's certificate chain.
148 /// This parameter can be empty if the client does not have a certificate
149 /// chain.
150 grpc::string pem_cert_chain;
151};
152
153// Factories for building different types of Credentials The functions may
154// return empty shared_ptr when credentials cannot be created. If a
155// Credentials pointer is returned, it can still be invalid when used to create
156// a channel. A lame channel will be created then and all rpcs will fail on it.
157
158/// Builds credentials with reasonable defaults.
159///
160/// \warning Only use these credentials when connecting to a Google endpoint.
161/// Using these credentials to connect to any other service may result in this
162/// service being able to impersonate your client for requests to Google
163/// services.
164std::shared_ptr<ChannelCredentials> GoogleDefaultCredentials();
165
166/// Builds SSL Credentials given SSL specific options
167std::shared_ptr<ChannelCredentials> SslCredentials(
168 const SslCredentialsOptions& options);
169
170/// Builds credentials for use when running in GCE
171///
172/// \warning Only use these credentials when connecting to a Google endpoint.
173/// Using these credentials to connect to any other service may result in this
174/// service being able to impersonate your client for requests to Google
175/// services.
176std::shared_ptr<CallCredentials> GoogleComputeEngineCredentials();
177
178constexpr long kMaxAuthTokenLifetimeSecs = 3600;
179
180/// Builds Service Account JWT Access credentials.
181/// json_key is the JSON key string containing the client's private key.
182/// token_lifetime_seconds is the lifetime in seconds of each Json Web Token
183/// (JWT) created with this credentials. It should not exceed
184/// \a kMaxAuthTokenLifetimeSecs or will be cropped to this value.
185std::shared_ptr<CallCredentials> ServiceAccountJWTAccessCredentials(
186 const grpc::string& json_key,
187 long token_lifetime_seconds = grpc_impl::kMaxAuthTokenLifetimeSecs);
188
189/// Builds refresh token credentials.
190/// json_refresh_token is the JSON string containing the refresh token along
191/// with a client_id and client_secret.
192///
193/// \warning Only use these credentials when connecting to a Google endpoint.
194/// Using these credentials to connect to any other service may result in this
195/// service being able to impersonate your client for requests to Google
196/// services.
197std::shared_ptr<CallCredentials> GoogleRefreshTokenCredentials(
198 const grpc::string& json_refresh_token);
199
200/// Builds access token credentials.
201/// access_token is an oauth2 access token that was fetched using an out of band
202/// mechanism.
203///
204/// \warning Only use these credentials when connecting to a Google endpoint.
205/// Using these credentials to connect to any other service may result in this
206/// service being able to impersonate your client for requests to Google
207/// services.
208std::shared_ptr<CallCredentials> AccessTokenCredentials(
209 const grpc::string& access_token);
210
211/// Builds IAM credentials.
212///
213/// \warning Only use these credentials when connecting to a Google endpoint.
214/// Using these credentials to connect to any other service may result in this
215/// service being able to impersonate your client for requests to Google
216/// services.
217std::shared_ptr<CallCredentials> GoogleIAMCredentials(
218 const grpc::string& authorization_token,
219 const grpc::string& authority_selector);
220
221/// Combines a channel credentials and a call credentials into a composite
222/// channel credentials.
223std::shared_ptr<ChannelCredentials> CompositeChannelCredentials(
224 const std::shared_ptr<ChannelCredentials>& channel_creds,
225 const std::shared_ptr<CallCredentials>& call_creds);
226
227/// Combines two call credentials objects into a composite call credentials.
228std::shared_ptr<CallCredentials> CompositeCallCredentials(
229 const std::shared_ptr<CallCredentials>& creds1,
230 const std::shared_ptr<CallCredentials>& creds2);
231
232/// Credentials for an unencrypted, unauthenticated channel
233std::shared_ptr<ChannelCredentials> InsecureChannelCredentials();
234
235/// User defined metadata credentials.
236class MetadataCredentialsPlugin {
237 public:
238 virtual ~MetadataCredentialsPlugin() {}
239
240 /// If this method returns true, the Process function will be scheduled in
241 /// a different thread from the one processing the call.
242 virtual bool IsBlocking() const { return true; }
243
244 /// Type of credentials this plugin is implementing.
245 virtual const char* GetType() const { return ""; }
246
247 /// Gets the auth metatada produced by this plugin.
248 /// The fully qualified method name is:
249 /// service_url + "/" + method_name.
250 /// The channel_auth_context contains (among other things), the identity of
251 /// the server.
252 virtual grpc::Status GetMetadata(
253 grpc::string_ref service_url, grpc::string_ref method_name,
254 const grpc::AuthContext& channel_auth_context,
255 std::multimap<grpc::string, grpc::string>* metadata) = 0;
256
257 virtual grpc::string DebugString() {
258 return "MetadataCredentialsPlugin did not provide a debug string";
259 }
260};
261
262std::shared_ptr<CallCredentials> MetadataCredentialsFromPlugin(
263 std::unique_ptr<MetadataCredentialsPlugin> plugin);
264
265namespace experimental {
266
267/// Options for creating STS Oauth Token Exchange credentials following the IETF
268/// draft https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16.
269/// Optional fields may be set to empty string. It is the responsibility of the
270/// caller to ensure that the subject and actor tokens are refreshed on disk at
271/// the specified paths.
272struct StsCredentialsOptions {
273 grpc::string token_exchange_service_uri; // Required.
274 grpc::string resource; // Optional.
275 grpc::string audience; // Optional.
276 grpc::string scope; // Optional.
277 grpc::string requested_token_type; // Optional.
278 grpc::string subject_token_path; // Required.
279 grpc::string subject_token_type; // Required.
280 grpc::string actor_token_path; // Optional.
281 grpc::string actor_token_type; // Optional.
282};
283
284/// Creates STS Options from a JSON string. The JSON schema is as follows:
285/// {
286/// "title": "STS Credentials Config",
287/// "type": "object",
288/// "required": ["token_exchange_service_uri", "subject_token_path",
289/// "subject_token_type"],
290/// "properties": {
291/// "token_exchange_service_uri": {
292/// "type": "string"
293/// },
294/// "resource": {
295/// "type": "string"
296/// },
297/// "audience": {
298/// "type": "string"
299/// },
300/// "scope": {
301/// "type": "string"
302/// },
303/// "requested_token_type": {
304/// "type": "string"
305/// },
306/// "subject_token_path": {
307/// "type": "string"
308/// },
309/// "subject_token_type": {
310/// "type": "string"
311/// },
312/// "actor_token_path" : {
313/// "type": "string"
314/// },
315/// "actor_token_type": {
316/// "type": "string"
317/// }
318/// }
319/// }
320grpc::Status StsCredentialsOptionsFromJson(const grpc::string& json_string,
321 StsCredentialsOptions* options);
322
323/// Creates STS credentials options from the $STS_CREDENTIALS environment
324/// variable. This environment variable points to the path of a JSON file
325/// comforming to the schema described above.
326grpc::Status StsCredentialsOptionsFromEnv(StsCredentialsOptions* options);
327
328std::shared_ptr<CallCredentials> StsCredentials(
329 const StsCredentialsOptions& options);
330
331std::shared_ptr<CallCredentials> MetadataCredentialsFromPlugin(
332 std::unique_ptr<MetadataCredentialsPlugin> plugin,
333 grpc_security_level min_security_level);
334
335/// Options used to build AltsCredentials.
336struct AltsCredentialsOptions {
337 /// service accounts of target endpoint that will be acceptable
338 /// by the client. If service accounts are provided and none of them matches
339 /// that of the server, authentication will fail.
340 std::vector<grpc::string> target_service_accounts;
341};
342
343/// Builds ALTS Credentials given ALTS specific options
344std::shared_ptr<ChannelCredentials> AltsCredentials(
345 const AltsCredentialsOptions& options);
346
347/// Builds Local Credentials.
348std::shared_ptr<ChannelCredentials> LocalCredentials(
349 grpc_local_connect_type type);
350
351/// Builds TLS Credentials given TLS options.
352std::shared_ptr<ChannelCredentials> TlsCredentials(
353 const TlsCredentialsOptions& options);
354
355} // namespace experimental
356} // namespace grpc_impl
357
358#endif // GRPCPP_SECURITY_CREDENTIALS_IMPL_H
359

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