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/impl/codegen/grpc_library.h>
28 #include <grpcpp/security/auth_context.h>
29 #include <grpcpp/support/status.h>
30 #include <grpcpp/support/string_ref.h>
31 
32 struct grpc_call;
33 
34 namespace grpc {
35 class ChannelArguments;
36 class Channel;
37 class SecureChannelCredentials;
38 class CallCredentials;
39 class SecureCallCredentials;
40 
41 /// A channel credentials object encapsulates all the state needed by a client
42 /// to authenticate with a server for a given channel.
43 /// It can make various assertions, e.g., about the client’s identity, role
44 /// for all the calls on that channel.
45 ///
46 /// \see https://grpc.io/docs/guides/auth.html
47 class ChannelCredentials : private GrpcLibraryCodegen {
48  public:
49   ChannelCredentials();
50   ~ChannelCredentials();
51 
52  protected:
53   friend std::shared_ptr<ChannelCredentials> CompositeChannelCredentials(
54       const std::shared_ptr<ChannelCredentials>& channel_creds,
55       const std::shared_ptr<CallCredentials>& call_creds);
56 
57   virtual SecureChannelCredentials* AsSecureCredentials() = 0;
58 
59  private:
60   friend std::shared_ptr<Channel> CreateCustomChannel(
61       const grpc::string& target,
62       const std::shared_ptr<ChannelCredentials>& creds,
63       const ChannelArguments& args);
64 
65   virtual std::shared_ptr<Channel> CreateChannel(
66       const grpc::string& target, const ChannelArguments& args) = 0;
67 };
68 
69 /// A call credentials object encapsulates the state needed by a client to
70 /// authenticate with a server for a given call on a channel.
71 ///
72 /// \see https://grpc.io/docs/guides/auth.html
73 class CallCredentials : private GrpcLibraryCodegen {
74  public:
75   CallCredentials();
76   ~CallCredentials();
77 
78   /// Apply this instance's credentials to \a call.
79   virtual bool ApplyToCall(grpc_call* call) = 0;
80 
81  protected:
82   friend std::shared_ptr<ChannelCredentials> CompositeChannelCredentials(
83       const std::shared_ptr<ChannelCredentials>& channel_creds,
84       const std::shared_ptr<CallCredentials>& call_creds);
85 
86   friend std::shared_ptr<CallCredentials> CompositeCallCredentials(
87       const std::shared_ptr<CallCredentials>& creds1,
88       const std::shared_ptr<CallCredentials>& creds2);
89 
90   virtual SecureCallCredentials* AsSecureCredentials() = 0;
91 };
92 
93 /// Options used to build SslCredentials.
94 struct SslCredentialsOptions {
95   /// The buffer containing the PEM encoding of the server root certificates. If
96   /// this parameter is empty, the default roots will be used.  The default
97   /// roots can be overridden using the \a GRPC_DEFAULT_SSL_ROOTS_FILE_PATH
98   /// environment variable pointing to a file on the file system containing the
99   /// roots.
100   grpc::string pem_root_certs;
101 
102   /// The buffer containing the PEM encoding of the client's private key. This
103   /// parameter can be empty if the client does not have a private key.
104   grpc::string pem_private_key;
105 
106   /// The buffer containing the PEM encoding of the client's certificate chain.
107   /// This parameter can be empty if the client does not have a certificate
108   /// chain.
109   grpc::string pem_cert_chain;
110 };
111 
112 // Factories for building different types of Credentials The functions may
113 // return empty shared_ptr when credentials cannot be created. If a
114 // Credentials pointer is returned, it can still be invalid when used to create
115 // a channel. A lame channel will be created then and all rpcs will fail on it.
116 
117 /// Builds credentials with reasonable defaults.
118 ///
119 /// \warning Only use these credentials when connecting to a Google endpoint.
120 /// Using these credentials to connect to any other service may result in this
121 /// service being able to impersonate your client for requests to Google
122 /// services.
123 std::shared_ptr<ChannelCredentials> GoogleDefaultCredentials();
124 
125 /// Builds SSL Credentials given SSL specific options
126 std::shared_ptr<ChannelCredentials> SslCredentials(
127     const SslCredentialsOptions& options);
128 
129 /// Builds credentials for use when running in GCE
130 ///
131 /// \warning Only use these credentials when connecting to a Google endpoint.
132 /// Using these credentials to connect to any other service may result in this
133 /// service being able to impersonate your client for requests to Google
134 /// services.
135 std::shared_ptr<CallCredentials> GoogleComputeEngineCredentials();
136 
137 /// Constant for maximum auth token lifetime.
138 constexpr long kMaxAuthTokenLifetimeSecs = 3600;
139 
140 /// Builds Service Account JWT Access credentials.
141 /// json_key is the JSON key string containing the client's private key.
142 /// token_lifetime_seconds is the lifetime in seconds of each Json Web Token
143 /// (JWT) created with this credentials. It should not exceed
144 /// \a kMaxAuthTokenLifetimeSecs or will be cropped to this value.
145 std::shared_ptr<CallCredentials> ServiceAccountJWTAccessCredentials(
146     const grpc::string& json_key,
147     long token_lifetime_seconds = kMaxAuthTokenLifetimeSecs);
148 
149 /// Builds refresh token credentials.
150 /// json_refresh_token is the JSON string containing the refresh token along
151 /// with a client_id and client_secret.
152 ///
153 /// \warning Only use these credentials when connecting to a Google endpoint.
154 /// Using these credentials to connect to any other service may result in this
155 /// service being able to impersonate your client for requests to Google
156 /// services.
157 std::shared_ptr<CallCredentials> GoogleRefreshTokenCredentials(
158     const grpc::string& json_refresh_token);
159 
160 /// Builds access token credentials.
161 /// access_token is an oauth2 access token that was fetched using an out of band
162 /// mechanism.
163 ///
164 /// \warning Only use these credentials when connecting to a Google endpoint.
165 /// Using these credentials to connect to any other service may result in this
166 /// service being able to impersonate your client for requests to Google
167 /// services.
168 std::shared_ptr<CallCredentials> AccessTokenCredentials(
169     const grpc::string& access_token);
170 
171 /// Builds IAM credentials.
172 ///
173 /// \warning Only use these credentials when connecting to a Google endpoint.
174 /// Using these credentials to connect to any other service may result in this
175 /// service being able to impersonate your client for requests to Google
176 /// services.
177 std::shared_ptr<CallCredentials> GoogleIAMCredentials(
178     const grpc::string& authorization_token,
179     const grpc::string& authority_selector);
180 
181 /// Combines a channel credentials and a call credentials into a composite
182 /// channel credentials.
183 std::shared_ptr<ChannelCredentials> CompositeChannelCredentials(
184     const std::shared_ptr<ChannelCredentials>& channel_creds,
185     const std::shared_ptr<CallCredentials>& call_creds);
186 
187 /// Combines two call credentials objects into a composite call credentials.
188 std::shared_ptr<CallCredentials> CompositeCallCredentials(
189     const std::shared_ptr<CallCredentials>& creds1,
190     const std::shared_ptr<CallCredentials>& creds2);
191 
192 /// Credentials for an unencrypted, unauthenticated channel
193 std::shared_ptr<ChannelCredentials> InsecureChannelCredentials();
194 
195 /// Credentials for a channel using Cronet.
196 std::shared_ptr<ChannelCredentials> CronetChannelCredentials(void* engine);
197 
198 /// User defined metadata credentials.
199 class MetadataCredentialsPlugin {
200  public:
~MetadataCredentialsPlugin()201   virtual ~MetadataCredentialsPlugin() {}
202 
203   /// If this method returns true, the Process function will be scheduled in
204   /// a different thread from the one processing the call.
IsBlocking()205   virtual bool IsBlocking() const { return true; }
206 
207   /// Type of credentials this plugin is implementing.
GetType()208   virtual const char* GetType() const { return ""; }
209 
210   /// Gets the auth metatada produced by this plugin.
211   /// The fully qualified method name is:
212   /// service_url + "/" + method_name.
213   /// The channel_auth_context contains (among other things), the identity of
214   /// the server.
215   virtual Status GetMetadata(
216       grpc::string_ref service_url, grpc::string_ref method_name,
217       const AuthContext& channel_auth_context,
218       std::multimap<grpc::string, grpc::string>* metadata) = 0;
219 };
220 
221 std::shared_ptr<CallCredentials> MetadataCredentialsFromPlugin(
222     std::unique_ptr<MetadataCredentialsPlugin> plugin);
223 
224 namespace experimental {
225 
226 /// Options used to build AltsCredentials.
227 struct AltsCredentialsOptions {
228   /// service accounts of target endpoint that will be acceptable
229   /// by the client. If service accounts are provided and none of them matches
230   /// that of the server, authentication will fail.
231   std::vector<grpc::string> target_service_accounts;
232 };
233 
234 /// Builds ALTS Credentials given ALTS specific options
235 std::shared_ptr<ChannelCredentials> AltsCredentials(
236     const AltsCredentialsOptions& options);
237 
238 /// Builds Local Credentials.
239 std::shared_ptr<ChannelCredentials> LocalCredentials(
240     grpc_local_connect_type type);
241 
242 }  // namespace experimental
243 }  // namespace grpc
244 
245 #endif  // GRPCPP_SECURITY_CREDENTIALS_H
246