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++/support/config.h>
42 : #include <grpc++/support/status.h>
43 : #include <grpc++/support/string_ref.h>
44 :
45 : namespace grpc {
46 : class ChannelArguments;
47 : class Channel;
48 : class SecureCredentials;
49 :
50 : /// A credentials object encapsulates all the state needed by a client to
51 : /// authenticate with a server and make various assertions, e.g., about the
52 : /// client’s identity, role, or whether it is authorized to make a particular
53 : /// call.
54 : ///
55 : /// \see https://github.com/grpc/grpc/blob/master/doc/grpc-auth-support.md
56 237 : class Credentials : public GrpcLibrary {
57 : public:
58 : ~Credentials() GRPC_OVERRIDE;
59 :
60 : /// Apply this instance's credentials to \a call.
61 : virtual bool ApplyToCall(grpc_call* call) = 0;
62 :
63 : protected:
64 : friend std::shared_ptr<Credentials> CompositeCredentials(
65 : const std::shared_ptr<Credentials>& creds1,
66 : const std::shared_ptr<Credentials>& creds2);
67 :
68 : virtual SecureCredentials* AsSecureCredentials() = 0;
69 :
70 : private:
71 : friend std::shared_ptr<Channel> CreateCustomChannel(
72 : const grpc::string& target, const std::shared_ptr<Credentials>& creds,
73 : const ChannelArguments& args);
74 :
75 : virtual std::shared_ptr<Channel> CreateChannel(
76 : const grpc::string& target, const ChannelArguments& args) = 0;
77 : };
78 :
79 : /// Options used to build SslCredentials.
80 46 : struct SslCredentialsOptions {
81 : /// The buffer containing the PEM encoding of the server root certificates. If
82 : /// this parameter is empty, the default roots will be used. The default
83 : /// roots can be overridden using the \a GRPC_DEFAULT_SSL_ROOTS_FILE_PATH
84 : /// environment variable pointing to a file on the file system containing the
85 : /// roots.
86 : grpc::string pem_root_certs;
87 :
88 : /// The buffer containing the PEM encoding of the client's private key. This
89 : /// parameter can be empty if the client does not have a private key.
90 : grpc::string pem_private_key;
91 :
92 : /// The buffer containing the PEM encoding of the client's certificate chain.
93 : /// This parameter can be empty if the client does not have a certificate
94 : /// chain.
95 : grpc::string pem_cert_chain;
96 : };
97 :
98 : // Factories for building different types of Credentials The functions may
99 : // return empty shared_ptr when credentials cannot be created. If a
100 : // Credentials pointer is returned, it can still be invalid when used to create
101 : // a channel. A lame channel will be created then and all rpcs will fail on it.
102 :
103 : /// Builds credentials with reasonable defaults.
104 : ///
105 : /// \warning Only use these credentials when connecting to a Google endpoint.
106 : /// Using these credentials to connect to any other service may result in this
107 : /// service being able to impersonate your client for requests to Google
108 : /// services.
109 : std::shared_ptr<Credentials> GoogleDefaultCredentials();
110 :
111 : /// Builds SSL Credentials given SSL specific options
112 : std::shared_ptr<Credentials> SslCredentials(
113 : const SslCredentialsOptions& options);
114 :
115 : /// Builds credentials for use when running in GCE
116 : ///
117 : /// \warning Only use these credentials when connecting to a Google endpoint.
118 : /// Using these credentials to connect to any other service may result in this
119 : /// service being able to impersonate your client for requests to Google
120 : /// services.
121 : std::shared_ptr<Credentials> GoogleComputeEngineCredentials();
122 :
123 : /// Builds Service Account JWT Access credentials.
124 : /// json_key is the JSON key string containing the client's private key.
125 : /// token_lifetime_seconds is the lifetime in seconds of each Json Web Token
126 : /// (JWT) created with this credentials. It should not exceed
127 : /// grpc_max_auth_token_lifetime or will be cropped to this value.
128 : std::shared_ptr<Credentials> ServiceAccountJWTAccessCredentials(
129 : const grpc::string& json_key, long token_lifetime_seconds);
130 :
131 : /// Builds refresh token credentials.
132 : /// json_refresh_token is the JSON string containing the refresh token along
133 : /// with a client_id and client_secret.
134 : ///
135 : /// \warning Only use these credentials when connecting to a Google endpoint.
136 : /// Using these credentials to connect to any other service may result in this
137 : /// service being able to impersonate your client for requests to Google
138 : /// services.
139 : std::shared_ptr<Credentials> GoogleRefreshTokenCredentials(
140 : const grpc::string& json_refresh_token);
141 :
142 : /// Builds access token credentials.
143 : /// access_token is an oauth2 access token that was fetched using an out of band
144 : /// mechanism.
145 : ///
146 : /// \warning Only use these credentials when connecting to a Google endpoint.
147 : /// Using these credentials to connect to any other service may result in this
148 : /// service being able to impersonate your client for requests to Google
149 : /// services.
150 : std::shared_ptr<Credentials> AccessTokenCredentials(
151 : const grpc::string& access_token);
152 :
153 : /// Builds IAM credentials.
154 : ///
155 : /// \warning Only use these credentials when connecting to a Google endpoint.
156 : /// Using these credentials to connect to any other service may result in this
157 : /// service being able to impersonate your client for requests to Google
158 : /// services.
159 : std::shared_ptr<Credentials> GoogleIAMCredentials(
160 : const grpc::string& authorization_token,
161 : const grpc::string& authority_selector);
162 :
163 : /// Combines two credentials objects into a composite credentials
164 : std::shared_ptr<Credentials> CompositeCredentials(
165 : const std::shared_ptr<Credentials>& creds1,
166 : const std::shared_ptr<Credentials>& creds2);
167 :
168 : /// Credentials for an unencrypted, unauthenticated channel
169 : std::shared_ptr<Credentials> InsecureCredentials();
170 :
171 : // User defined metadata credentials.
172 6 : class MetadataCredentialsPlugin {
173 : public:
174 6 : virtual ~MetadataCredentialsPlugin() {}
175 :
176 : // If this method returns true, the Process function will be scheduled in
177 : // a different thread from the one processing the call.
178 0 : virtual bool IsBlocking() const { return true; }
179 :
180 : // Gets the auth metatada produced by this plugin.
181 : virtual Status GetMetadata(
182 : grpc::string_ref service_url,
183 : std::multimap<grpc::string, grpc::string>* metadata) = 0;
184 : };
185 :
186 : std::shared_ptr<Credentials> MetadataCredentialsFromPlugin(
187 : std::unique_ptr<MetadataCredentialsPlugin> plugin);
188 :
189 : } // namespace grpc
190 :
191 : #endif // GRPCXX_CREDENTIALS_H
|
