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