blob: e438fda226fe1ac1eae5f10fef9eb7fcd3168ee0 [file] [log] [blame]
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -07001/*
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"
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -070027 "errors"
28 "fmt"
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -070029 "net"
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -070030
31 "github.com/golang/protobuf/proto"
Arjun E K57a7fcb2020-01-30 06:44:45 +000032 "google.golang.org/grpc/internal"
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -070033)
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
Arjun E K57a7fcb2020-01-30 06:44:45 +000044 // timeout and cancellation. Additionally, RequestInfo data will be
45 // available via ctx to this call.
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -070046 // 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
Arjun E K57a7fcb2020-01-30 06:44:45 +000054// 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
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -070096// 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
amit.ghosh258d14c2020-10-02 15:13:38 +0200103 // 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.
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700108 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.
Arjun E K57a7fcb2020-01-30 06:44:45 +0000114// A struct that implements AuthInfo should embed CommonAuthInfo by including additional
115// information about the credentials in it.
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700116type 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.
Arjun E K57a7fcb2020-01-30 06:44:45 +0000130 // The auth information should embed CommonAuthInfo to return additional information about
131 // the credentials. Implementations must use the provided context to implement timely cancellation.
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700132 // 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
Arjun E K57a7fcb2020-01-30 06:44:45 +0000141 // the connection. The auth information should embed CommonAuthInfo to return additional information
142 // about the credentials.
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700143 //
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
Arjun E K57a7fcb2020-01-30 06:44:45 +0000175// 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
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700183}
184
Arjun E K57a7fcb2020-01-30 06:44:45 +0000185// 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
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700194}
195
Arjun E K57a7fcb2020-01-30 06:44:45 +0000196// 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
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700204 }
Arjun E K57a7fcb2020-01-30 06:44:45 +0000205 ri, _ := RequestInfoFromContext(ctx)
206 if ri.AuthInfo == nil {
207 return errors.New("unable to obtain SecurityLevel from context")
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700208 }
Arjun E K57a7fcb2020-01-30 06:44:45 +0000209 if ci, ok := ri.AuthInfo.(internalInfo); ok {
210 // CommonAuthInfo.SecurityLevel has an invalid value.
211 if ci.GetCommonAuthInfo().SecurityLevel == 0 {
212 return nil
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700213 }
Arjun E K57a7fcb2020-01-30 06:44:45 +0000214 if ci.GetCommonAuthInfo().SecurityLevel < level {
215 return fmt.Errorf("requires SecurityLevel %v; connection has %v", level, ci.GetCommonAuthInfo().SecurityLevel)
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700216 }
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700217 }
Arjun E K57a7fcb2020-01-30 06:44:45 +0000218 // The condition is satisfied or AuthInfo struct does not implement GetCommonAuthInfo() method.
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700219 return nil
220}
221
Arjun E K57a7fcb2020-01-30 06:44:45 +0000222func init() {
223 internal.NewRequestInfoContext = func(ctx context.Context, ri RequestInfo) context.Context {
224 return context.WithValue(ctx, requestInfoKey{}, ri)
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700225 }
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700226}
227
228// ChannelzSecurityInfo defines the interface that security protocols should implement
229// in order to provide security info to channelz.
Arjun E K57a7fcb2020-01-30 06:44:45 +0000230//
231// This API is experimental.
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700232type 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.
Arjun E K57a7fcb2020-01-30 06:44:45 +0000239//
240// This API is experimental.
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700241type ChannelzSecurityValue interface {
242 isChannelzSecurityValue()
243}
244
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700245// 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.
Arjun E K57a7fcb2020-01-30 06:44:45 +0000249//
250// This API is experimental.
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700251type OtherChannelzSecurityValue struct {
252 ChannelzSecurityValue
253 Name string
254 Value proto.Message
255}