1/* 2 * 3 * Copyright 2014 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// Package credentials implements various credentials supported by gRPC library, 20// which encapsulate all the state needed by a client to authenticate with a 21// server and make various assertions, e.g., about the client's identity, role, 22// or whether it is authorized to make a particular call. 23package credentials // import "google.golang.org/grpc/credentials" 24 25import ( 26 "context" 27 "errors" 28 "fmt" 29 "net" 30 31 "github.com/golang/protobuf/proto" 32 "google.golang.org/grpc/internal" 33) 34 35// PerRPCCredentials defines the common interface for the credentials which need to 36// attach security information to every RPC (e.g., oauth2). 37type PerRPCCredentials interface { 38 // GetRequestMetadata gets the current request metadata, refreshing 39 // tokens if required. This should be called by the transport layer on 40 // each request, and the data should be populated in headers or other 41 // context. If a status code is returned, it will be used as the status 42 // for the RPC. uri is the URI of the entry point for the request. 43 // When supported by the underlying implementation, ctx can be used for 44 // timeout and cancellation. Additionally, RequestInfo data will be 45 // available via ctx to this call. 46 // TODO(zhaoq): Define the set of the qualified keys instead of leaving 47 // it as an arbitrary string. 48 GetRequestMetadata(ctx context.Context, uri ...string) (map[string]string, error) 49 // RequireTransportSecurity indicates whether the credentials requires 50 // transport security. 51 RequireTransportSecurity() bool 52} 53 54// SecurityLevel defines the protection level on an established connection. 55// 56// This API is experimental. 57type SecurityLevel int 58 59const ( 60 // NoSecurity indicates a connection is insecure. 61 // The zero SecurityLevel value is invalid for backward compatibility. 62 NoSecurity SecurityLevel = iota + 1 63 // IntegrityOnly indicates a connection only provides integrity protection. 64 IntegrityOnly 65 // PrivacyAndIntegrity indicates a connection provides both privacy and integrity protection. 66 PrivacyAndIntegrity 67) 68 69// String returns SecurityLevel in a string format. 70func (s SecurityLevel) String() string { 71 switch s { 72 case NoSecurity: 73 return "NoSecurity" 74 case IntegrityOnly: 75 return "IntegrityOnly" 76 case PrivacyAndIntegrity: 77 return "PrivacyAndIntegrity" 78 } 79 return fmt.Sprintf("invalid SecurityLevel: %v", int(s)) 80} 81 82// CommonAuthInfo contains authenticated information common to AuthInfo implementations. 83// It should be embedded in a struct implementing AuthInfo to provide additional information 84// about the credentials. 85// 86// This API is experimental. 87type CommonAuthInfo struct { 88 SecurityLevel SecurityLevel 89} 90 91// GetCommonAuthInfo returns the pointer to CommonAuthInfo struct. 92func (c *CommonAuthInfo) GetCommonAuthInfo() *CommonAuthInfo { 93 return c 94} 95 96// ProtocolInfo provides information regarding the gRPC wire protocol version, 97// security protocol, security protocol version in use, server name, etc. 98type ProtocolInfo struct { 99 // ProtocolVersion is the gRPC wire protocol version. 100 ProtocolVersion string 101 // SecurityProtocol is the security protocol in use. 102 SecurityProtocol string 103 // SecurityVersion is the security protocol version. It is a static version string from the 104 // credentials, not a value that reflects per-connection protocol negotiation. To retrieve 105 // details about the credentials used for a connection, use the Peer's AuthInfo field instead. 106 // 107 // Deprecated: please use Peer.AuthInfo. 108 SecurityVersion string 109 // ServerName is the user-configured server name. 110 ServerName string 111} 112 113// AuthInfo defines the common interface for the auth information the users are interested in. 114// A struct that implements AuthInfo should embed CommonAuthInfo by including additional 115// information about the credentials in it. 116type AuthInfo interface { 117 AuthType() string 118} 119 120// ErrConnDispatched indicates that rawConn has been dispatched out of gRPC 121// and the caller should not close rawConn. 122var ErrConnDispatched = errors.New("credentials: rawConn is dispatched out of gRPC") 123 124// TransportCredentials defines the common interface for all the live gRPC wire 125// protocols and supported transport security protocols (e.g., TLS, SSL). 126type TransportCredentials interface { 127 // ClientHandshake does the authentication handshake specified by the corresponding 128 // authentication protocol on rawConn for clients. It returns the authenticated 129 // connection and the corresponding auth information about the connection. 130 // The auth information should embed CommonAuthInfo to return additional information about 131 // the credentials. Implementations must use the provided context to implement timely cancellation. 132 // gRPC will try to reconnect if the error returned is a temporary error 133 // (io.EOF, context.DeadlineExceeded or err.Temporary() == true). 134 // If the returned error is a wrapper error, implementations should make sure that 135 // the error implements Temporary() to have the correct retry behaviors. 136 // 137 // If the returned net.Conn is closed, it MUST close the net.Conn provided. 138 ClientHandshake(context.Context, string, net.Conn) (net.Conn, AuthInfo, error) 139 // ServerHandshake does the authentication handshake for servers. It returns 140 // the authenticated connection and the corresponding auth information about 141 // the connection. The auth information should embed CommonAuthInfo to return additional information 142 // about the credentials. 143 // 144 // If the returned net.Conn is closed, it MUST close the net.Conn provided. 145 ServerHandshake(net.Conn) (net.Conn, AuthInfo, error) 146 // Info provides the ProtocolInfo of this TransportCredentials. 147 Info() ProtocolInfo 148 // Clone makes a copy of this TransportCredentials. 149 Clone() TransportCredentials 150 // OverrideServerName overrides the server name used to verify the hostname on the returned certificates from the server. 151 // gRPC internals also use it to override the virtual hosting name if it is set. 152 // It must be called before dialing. Currently, this is only used by grpclb. 153 OverrideServerName(string) error 154} 155 156// Bundle is a combination of TransportCredentials and PerRPCCredentials. 157// 158// It also contains a mode switching method, so it can be used as a combination 159// of different credential policies. 160// 161// Bundle cannot be used together with individual TransportCredentials. 162// PerRPCCredentials from Bundle will be appended to other PerRPCCredentials. 163// 164// This API is experimental. 165type Bundle interface { 166 TransportCredentials() TransportCredentials 167 PerRPCCredentials() PerRPCCredentials 168 // NewWithMode should make a copy of Bundle, and switch mode. Modifying the 169 // existing Bundle may cause races. 170 // 171 // NewWithMode returns nil if the requested mode is not supported. 172 NewWithMode(mode string) (Bundle, error) 173} 174 175// RequestInfo contains request data attached to the context passed to GetRequestMetadata calls. 176// 177// This API is experimental. 178type RequestInfo struct { 179 // The method passed to Invoke or NewStream for this RPC. (For proto methods, this has the format "/some.Service/Method") 180 Method string 181 // AuthInfo contains the information from a security handshake (TransportCredentials.ClientHandshake, TransportCredentials.ServerHandshake) 182 AuthInfo AuthInfo 183} 184 185// requestInfoKey is a struct to be used as the key when attaching a RequestInfo to a context object. 186type requestInfoKey struct{} 187 188// RequestInfoFromContext extracts the RequestInfo from the context if it exists. 189// 190// This API is experimental. 191func RequestInfoFromContext(ctx context.Context) (ri RequestInfo, ok bool) { 192 ri, ok = ctx.Value(requestInfoKey{}).(RequestInfo) 193 return 194} 195 196// CheckSecurityLevel checks if a connection's security level is greater than or equal to the specified one. 197// It returns success if 1) the condition is satisified or 2) AuthInfo struct does not implement GetCommonAuthInfo() method 198// or 3) CommonAuthInfo.SecurityLevel has an invalid zero value. For 2) and 3), it is for the purpose of backward-compatibility. 199// 200// This API is experimental. 201func CheckSecurityLevel(ctx context.Context, level SecurityLevel) error { 202 type internalInfo interface { 203 GetCommonAuthInfo() *CommonAuthInfo 204 } 205 ri, _ := RequestInfoFromContext(ctx) 206 if ri.AuthInfo == nil { 207 return errors.New("unable to obtain SecurityLevel from context") 208 } 209 if ci, ok := ri.AuthInfo.(internalInfo); ok { 210 // CommonAuthInfo.SecurityLevel has an invalid value. 211 if ci.GetCommonAuthInfo().SecurityLevel == 0 { 212 return nil 213 } 214 if ci.GetCommonAuthInfo().SecurityLevel < level { 215 return fmt.Errorf("requires SecurityLevel %v; connection has %v", level, ci.GetCommonAuthInfo().SecurityLevel) 216 } 217 } 218 // The condition is satisfied or AuthInfo struct does not implement GetCommonAuthInfo() method. 219 return nil 220} 221 222func init() { 223 internal.NewRequestInfoContext = func(ctx context.Context, ri RequestInfo) context.Context { 224 return context.WithValue(ctx, requestInfoKey{}, ri) 225 } 226} 227 228// ChannelzSecurityInfo defines the interface that security protocols should implement 229// in order to provide security info to channelz. 230// 231// This API is experimental. 232type ChannelzSecurityInfo interface { 233 GetSecurityValue() ChannelzSecurityValue 234} 235 236// ChannelzSecurityValue defines the interface that GetSecurityValue() return value 237// should satisfy. This interface should only be satisfied by *TLSChannelzSecurityValue 238// and *OtherChannelzSecurityValue. 239// 240// This API is experimental. 241type ChannelzSecurityValue interface { 242 isChannelzSecurityValue() 243} 244 245// OtherChannelzSecurityValue defines the struct that non-TLS protocol should return 246// from GetSecurityValue(), which contains protocol specific security info. Note 247// the Value field will be sent to users of channelz requesting channel info, and 248// thus sensitive info should better be avoided. 249// 250// This API is experimental. 251type OtherChannelzSecurityValue struct { 252 ChannelzSecurityValue 253 Name string 254 Value proto.Message 255} 256