Line data Source code
1 : /*
2 : *
3 : * Copyright 2015, Google Inc.
4 : * All rights reserved.
5 : *
6 : * Redistribution and use in source and binary forms, with or without
7 : * modification, are permitted provided that the following conditions are
8 : * met:
9 : *
10 : * * Redistributions of source code must retain the above copyright
11 : * notice, this list of conditions and the following disclaimer.
12 : * * Redistributions in binary form must reproduce the above
13 : * copyright notice, this list of conditions and the following disclaimer
14 : * in the documentation and/or other materials provided with the
15 : * distribution.
16 : * * Neither the name of Google Inc. nor the names of its
17 : * contributors may be used to endorse or promote products derived from
18 : * this software without specific prior written permission.
19 : *
20 : * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21 : * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22 : * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23 : * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24 : * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25 : * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26 : * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27 : * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28 : * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 : * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30 : * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 : *
32 : */
33 :
34 : #ifndef GRPCXX_CREDENTIALS_H
35 : #define GRPCXX_CREDENTIALS_H
36 :
37 : #include <map>
38 : #include <memory>
39 :
40 : #include <grpc++/impl/grpc_library.h>
41 : #include <grpc++/security/auth_context.h>
42 : #include <grpc++/support/config.h>
43 : #include <grpc++/support/status.h>
44 : #include <grpc++/support/string_ref.h>
45 :
46 : namespace grpc {
47 : class ChannelArguments;
48 : class Channel;
49 : class SecureChannelCredentials;
50 : class CallCredentials;
51 : class SecureCallCredentials;
52 :
53 : /// A channel credentials object encapsulates all the state needed by a client
54 : /// to authenticate with a server for a given channel.
55 : /// It can make various assertions, e.g., about the client’s identity, role
56 : /// for all the calls on that channel.
57 : ///
58 : /// \see https://github.com/grpc/grpc/blob/master/doc/grpc-auth-support.md
59 221 : class ChannelCredentials : public GrpcLibrary {
60 : public:
61 : ~ChannelCredentials() GRPC_OVERRIDE;
62 :
63 : protected:
64 : friend std::shared_ptr<ChannelCredentials> CompositeChannelCredentials(
65 : const std::shared_ptr<ChannelCredentials>& channel_creds,
66 : const std::shared_ptr<CallCredentials>& call_creds);
67 :
68 : virtual SecureChannelCredentials* AsSecureCredentials() = 0;
69 :
70 : private:
71 : friend std::shared_ptr<Channel> CreateCustomChannel(
72 : const grpc::string& target,
73 : const std::shared_ptr<ChannelCredentials>& creds,
74 : const ChannelArguments& args);
75 :
76 : virtual std::shared_ptr<Channel> CreateChannel(
77 : const grpc::string& target, const ChannelArguments& args) = 0;
78 : };
79 :
80 : /// A call credentials object encapsulates the state needed by a client to
81 : /// authenticate with a server for a given call on a channel.
82 : ///
83 : /// \see https://github.com/grpc/grpc/blob/master/doc/grpc-auth-support.md
84 9 : class CallCredentials : public GrpcLibrary {
85 : public:
86 : ~CallCredentials() GRPC_OVERRIDE;
87 :
88 : /// Apply this instance's credentials to \a call.
89 : virtual bool ApplyToCall(grpc_call* call) = 0;
90 :
91 : protected:
92 : friend std::shared_ptr<ChannelCredentials> CompositeChannelCredentials(
93 : const std::shared_ptr<ChannelCredentials>& channel_creds,
94 : const std::shared_ptr<CallCredentials>& call_creds);
95 :
96 : friend std::shared_ptr<CallCredentials> CompositeCallCredentials(
97 : const std::shared_ptr<CallCredentials>& creds1,
98 : const std::shared_ptr<CallCredentials>& creds2);
99 :
100 : virtual SecureCallCredentials* AsSecureCredentials() = 0;
101 : };
102 :
103 : /// Options used to build SslCredentials.
104 47 : struct SslCredentialsOptions {
105 : /// The buffer containing the PEM encoding of the server root certificates. If
106 : /// this parameter is empty, the default roots will be used. The default
107 : /// roots can be overridden using the \a GRPC_DEFAULT_SSL_ROOTS_FILE_PATH
108 : /// environment variable pointing to a file on the file system containing the
109 : /// roots.
110 : grpc::string pem_root_certs;
111 :
112 : /// The buffer containing the PEM encoding of the client's private key. This
113 : /// parameter can be empty if the client does not have a private key.
114 : grpc::string pem_private_key;
115 :
116 : /// The buffer containing the PEM encoding of the client's certificate chain.
117 : /// This parameter can be empty if the client does not have a certificate
118 : /// chain.
119 : grpc::string pem_cert_chain;
120 : };
121 :
122 : // Factories for building different types of Credentials The functions may
123 : // return empty shared_ptr when credentials cannot be created. If a
124 : // Credentials pointer is returned, it can still be invalid when used to create
125 : // a channel. A lame channel will be created then and all rpcs will fail on it.
126 :
127 : /// Builds credentials with reasonable defaults.
128 : ///
129 : /// \warning Only use these credentials when connecting to a Google endpoint.
130 : /// Using these credentials to connect to any other service may result in this
131 : /// service being able to impersonate your client for requests to Google
132 : /// services.
133 : std::shared_ptr<ChannelCredentials> GoogleDefaultCredentials();
134 :
135 : /// Builds SSL Credentials given SSL specific options
136 : std::shared_ptr<ChannelCredentials> SslCredentials(
137 : const SslCredentialsOptions& options);
138 :
139 : /// Builds credentials for use when running in GCE
140 : ///
141 : /// \warning Only use these credentials when connecting to a Google endpoint.
142 : /// Using these credentials to connect to any other service may result in this
143 : /// service being able to impersonate your client for requests to Google
144 : /// services.
145 : std::shared_ptr<CallCredentials> GoogleComputeEngineCredentials();
146 :
147 : /// Builds Service Account JWT Access credentials.
148 : /// json_key is the JSON key string containing the client's private key.
149 : /// token_lifetime_seconds is the lifetime in seconds of each Json Web Token
150 : /// (JWT) created with this credentials. It should not exceed
151 : /// grpc_max_auth_token_lifetime or will be cropped to this value.
152 : std::shared_ptr<CallCredentials> ServiceAccountJWTAccessCredentials(
153 : const grpc::string& json_key, long token_lifetime_seconds);
154 :
155 : /// Builds refresh token credentials.
156 : /// json_refresh_token is the JSON string containing the refresh token along
157 : /// with a client_id and client_secret.
158 : ///
159 : /// \warning Only use these credentials when connecting to a Google endpoint.
160 : /// Using these credentials to connect to any other service may result in this
161 : /// service being able to impersonate your client for requests to Google
162 : /// services.
163 : std::shared_ptr<CallCredentials> GoogleRefreshTokenCredentials(
164 : const grpc::string& json_refresh_token);
165 :
166 : /// Builds access token credentials.
167 : /// access_token is an oauth2 access token that was fetched using an out of band
168 : /// mechanism.
169 : ///
170 : /// \warning Only use these credentials when connecting to a Google endpoint.
171 : /// Using these credentials to connect to any other service may result in this
172 : /// service being able to impersonate your client for requests to Google
173 : /// services.
174 : std::shared_ptr<CallCredentials> AccessTokenCredentials(
175 : const grpc::string& access_token);
176 :
177 : /// Builds IAM credentials.
178 : ///
179 : /// \warning Only use these credentials when connecting to a Google endpoint.
180 : /// Using these credentials to connect to any other service may result in this
181 : /// service being able to impersonate your client for requests to Google
182 : /// services.
183 : std::shared_ptr<CallCredentials> GoogleIAMCredentials(
184 : const grpc::string& authorization_token,
185 : const grpc::string& authority_selector);
186 :
187 : /// Combines a channel credentials and a call credentials into a composite
188 : /// channel credentials.
189 : std::shared_ptr<ChannelCredentials> CompositeChannelCredentials(
190 : const std::shared_ptr<ChannelCredentials>& channel_creds,
191 : const std::shared_ptr<CallCredentials>& call_creds);
192 :
193 : /// Combines two call credentials objects into a composite call credentials.
194 : std::shared_ptr<CallCredentials> CompositeCallCredentials(
195 : const std::shared_ptr<CallCredentials>& creds1,
196 : const std::shared_ptr<CallCredentials>& creds2);
197 :
198 : /// Credentials for an unencrypted, unauthenticated channel
199 : std::shared_ptr<ChannelCredentials> InsecureChannelCredentials();
200 :
201 : // User defined metadata credentials.
202 6 : class MetadataCredentialsPlugin {
203 : public:
204 6 : virtual ~MetadataCredentialsPlugin() {}
205 :
206 : // If this method returns true, the Process function will be scheduled in
207 : // a different thread from the one processing the call.
208 0 : virtual bool IsBlocking() const { return true; }
209 :
210 : // Type of credentials this plugin is implementing.
211 6 : virtual const char* GetType() const { return ""; }
212 :
213 : // Gets the auth metatada produced by this plugin.
214 : // The fully qualified method name is:
215 : // service_url + "/" + method_name.
216 : // The channel_auth_context contains (among other things), the identity of
217 : // the server.
218 : virtual Status GetMetadata(
219 : grpc::string_ref service_url, grpc::string_ref method_name,
220 : const AuthContext& channel_auth_context,
221 : std::multimap<grpc::string, grpc::string>* metadata) = 0;
222 : };
223 :
224 : std::shared_ptr<CallCredentials> MetadataCredentialsFromPlugin(
225 : std::unique_ptr<MetadataCredentialsPlugin> plugin);
226 :
227 : } // namespace grpc
228 :
229 : #endif // GRPCXX_CREDENTIALS_H
|
