credentials

package module
v0.0.0-...-5025e00 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 19, 2022 License: Apache-2.0 Imports: 11 Imported by: 0

README

grpc-credentials-go

Go implementation for credentials and security channels

Documentation

Overview

Package credentials implements various credentials supported by gRPC library, which encapsulate all the state needed by a client to authenticate with a server and make various assertions, e.g., about the client's identity, role, or whether it is authorized to make a particular call.

Index

Constants

This section is empty.

Variables

View Source 
var ErrConnDispatched = errors.New("credentials: rawConn is dispatched out of gRPC")

ErrConnDispatched indicates that rawConn has been dispatched out of gRPC and the caller should not close rawConn.

Functions

func CheckSecurityLevel 

func CheckSecurityLevel(ai AuthInfo, level SecurityLevel) error

CheckSecurityLevel checks if a connection's security level is greater than or equal to the specified one. It returns success if 1) the condition is satisified or 2) AuthInfo struct does not implement GetCommonAuthInfo() method or 3) CommonAuthInfo.SecurityLevel has an invalid zero value. For 2) and 3), it is for the purpose of backward-compatibility.

This API is experimental.

Types

type AuthInfo 

type AuthInfo interface {
	AuthType() string
}

AuthInfo defines the common interface for the auth information the users are interested in. A struct that implements AuthInfo should embed CommonAuthInfo by including additional information about the credentials in it.

type Bundle 

type Bundle interface {
	// TransportCredentials returns the transport credentials from the Bundle.
	//
	// Implementations must return non-nil transport credentials. If transport
	// security is not needed by the Bundle, implementations may choose to
	// return insecure.NewCredentials().
	TransportCredentials() TransportCredentials

	// PerRPCCredentials returns the per-RPC credentials from the Bundle.
	//
	// May be nil if per-RPC credentials are not needed.
	PerRPCCredentials() PerRPCCredentials

	// NewWithMode should make a copy of Bundle, and switch mode. Modifying the
	// existing Bundle may cause races.
	//
	// NewWithMode returns nil if the requested mode is not supported.
	NewWithMode(mode string) (Bundle, error)
}

Bundle is a combination of TransportCredentials and PerRPCCredentials.

It also contains a mode switching method, so it can be used as a combination of different credential policies.

Bundle cannot be used together with individual TransportCredentials. PerRPCCredentials from Bundle will be appended to other PerRPCCredentials.

This API is experimental.

type ChannelzSecurityInfo 

type ChannelzSecurityInfo interface {
	GetSecurityValue() ChannelzSecurityValue
}

ChannelzSecurityInfo defines the interface that security protocols should implement in order to provide security info to channelz.

This API is experimental.

type ChannelzSecurityValue 

type ChannelzSecurityValue interface {
	// contains filtered or unexported methods
}

ChannelzSecurityValue defines the interface that GetSecurityValue() return value should satisfy. This interface should only be satisfied by *TLSChannelzSecurityValue and *OtherChannelzSecurityValue.

This API is experimental.

type ClientHandshakeInfo 

type ClientHandshakeInfo struct {
	// Attributes contains the attributes for the address. It could be provided
	// by the gRPC, resolver, balancer etc.
	Attributes *attributes.Attributes
}

ClientHandshakeInfo holds data to be passed to ClientHandshake. This makes it possible to pass arbitrary data to the handshaker from gRPC, resolver, balancer etc. Individual credential implementations control the actual format of the data that they are willing to receive.

This API is experimental.

func ClientHandshakeInfoFromContext 

func ClientHandshakeInfoFromContext(ctx context.Context) ClientHandshakeInfo

ClientHandshakeInfoFromContext returns the ClientHandshakeInfo struct stored in ctx.

This API is experimental.

type CommonAuthInfo 

type CommonAuthInfo struct {
	SecurityLevel SecurityLevel
}

CommonAuthInfo contains authenticated information common to AuthInfo implementations. It should be embedded in a struct implementing AuthInfo to provide additional information about the credentials.

This API is experimental.

func (CommonAuthInfo) GetCommonAuthInfo 

func (c CommonAuthInfo) GetCommonAuthInfo() CommonAuthInfo

GetCommonAuthInfo returns the pointer to CommonAuthInfo struct.

type OtherChannelzSecurityValue 

type OtherChannelzSecurityValue struct {
	ChannelzSecurityValue
	Name  string
	Value proto.Message
}

OtherChannelzSecurityValue defines the struct that non-TLS protocol should return from GetSecurityValue(), which contains protocol specific security info. Note the Value field will be sent to users of channelz requesting channel info, and thus sensitive info should better be avoided.

This API is experimental.

type PerRPCCredentials 

type PerRPCCredentials interface {
	// GetRequestMetadata gets the current request metadata, refreshing tokens
	// if required. This should be called by the transport layer on each
	// request, and the data should be populated in headers or other
	// context. If a status code is returned, it will be used as the status for
	// the RPC (restricted to an allowable set of codes as defined by gRFC
	// A54). uri is the URI of the entry point for the request.  When supported
	// by the underlying implementation, ctx can be used for timeout and
	// cancellation. Additionally, RequestInfo data will be available via ctx
	// to this call.  TODO(zhaoq): Define the set of the qualified keys instead
	// of leaving it as an arbitrary string.
	GetRequestMetadata(ctx context.Context, uri ...string) (map[string]string, error)
	// RequireTransportSecurity indicates whether the credentials requires
	// transport security.
	RequireTransportSecurity() bool
}

PerRPCCredentials defines the common interface for the credentials which need to attach security information to every RPC (e.g., oauth2).

type ProtocolInfo 

type ProtocolInfo struct {
	// ProtocolVersion is the gRPC wire protocol version.
	ProtocolVersion string
	// SecurityProtocol is the security protocol in use.
	SecurityProtocol string
	// SecurityVersion is the security protocol version.  It is a static version string from the
	// credentials, not a value that reflects per-connection protocol negotiation.  To retrieve
	// details about the credentials used for a connection, use the Peer's AuthInfo field instead.
	//
	// Deprecated: please use Peer.AuthInfo.
	SecurityVersion string
	// ServerName is the user-configured server name.
	ServerName string
}

ProtocolInfo provides information regarding the gRPC wire protocol version, security protocol, security protocol version in use, server name, etc.

type RequestInfo 

type RequestInfo struct {
	// The method passed to Invoke or NewStream for this RPC. (For proto methods, this has the format "/some.Service/Method")
	Method string
	// AuthInfo contains the information from a security handshake (TransportCredentials.ClientHandshake, TransportCredentials.ServerHandshake)
	AuthInfo AuthInfo
}

RequestInfo contains request data attached to the context passed to GetRequestMetadata calls.

This API is experimental.

func RequestInfoFromContext 

func RequestInfoFromContext(ctx context.Context) (ri RequestInfo, ok bool)

RequestInfoFromContext extracts the RequestInfo from the context if it exists.

This API is experimental.

type SecurityLevel 

type SecurityLevel int

SecurityLevel defines the protection level on an established connection.

This API is experimental. 

const (
	// InvalidSecurityLevel indicates an invalid security level.
	// The zero SecurityLevel value is invalid for backward compatibility.
	InvalidSecurityLevel SecurityLevel = iota
	// NoSecurity indicates a connection is insecure.
	NoSecurity
	// IntegrityOnly indicates a connection only provides integrity protection.
	IntegrityOnly
	// PrivacyAndIntegrity indicates a connection provides both privacy and integrity protection.
	PrivacyAndIntegrity
)

func (SecurityLevel) String 

func (s SecurityLevel) String() string

String returns SecurityLevel in a string format.

type TLSChannelzSecurityValue 

type TLSChannelzSecurityValue struct {
	ChannelzSecurityValue
	StandardName      string
	LocalCertificate  []byte
	RemoteCertificate []byte
}

TLSChannelzSecurityValue defines the struct that TLS protocol should return from GetSecurityValue(), containing security info like cipher and certificate used.

Experimental

Notice: This type is EXPERIMENTAL and may be changed or removed in a later release.

type TLSInfo 

type TLSInfo struct {
	State tls.ConnectionState
	CommonAuthInfo
	// This API is experimental.
	SPIFFEID *url.URL
}

TLSInfo contains the auth information for a TLS authenticated connection. It implements the AuthInfo interface.

func (TLSInfo) AuthType 

func (t TLSInfo) AuthType() string

AuthType returns the type of TLSInfo as a string.

func (TLSInfo) GetSecurityValue 

func (t TLSInfo) GetSecurityValue() ChannelzSecurityValue

GetSecurityValue returns security info requested by channelz.

type TransportCredentials 

type TransportCredentials interface {
	// ClientHandshake does the authentication handshake specified by the
	// corresponding authentication protocol on rawConn for clients. It returns
	// the authenticated connection and the corresponding auth information
	// about the connection.  The auth information should embed CommonAuthInfo
	// to return additional information about the credentials. Implementations
	// must use the provided context to implement timely cancellation.  gRPC
	// will try to reconnect if the error returned is a temporary error
	// (io.EOF, context.DeadlineExceeded or err.Temporary() == true).  If the
	// returned error is a wrapper error, implementations should make sure that
	// the error implements Temporary() to have the correct retry behaviors.
	// Additionally, ClientHandshakeInfo data will be available via the context
	// passed to this call.
	//
	// The second argument to this method is the `:authority` header value used
	// while creating new streams on this connection after authentication
	// succeeds. Implementations must use this as the server name during the
	// authentication handshake.
	//
	// If the returned net.Conn is closed, it MUST close the net.Conn provided.
	ClientHandshake(context.Context, string, net.Conn) (net.Conn, AuthInfo, error)
	// ServerHandshake does the authentication handshake for servers. It returns
	// the authenticated connection and the corresponding auth information about
	// the connection. The auth information should embed CommonAuthInfo to return additional information
	// about the credentials.
	//
	// If the returned net.Conn is closed, it MUST close the net.Conn provided.
	ServerHandshake(net.Conn) (net.Conn, AuthInfo, error)
	// Info provides the ProtocolInfo of this TransportCredentials.
	Info() ProtocolInfo
	// Clone makes a copy of this TransportCredentials.
	Clone() TransportCredentials
	// OverrideServerName specifies the value used for the following:
	// - verifying the hostname on the returned certificates
	// - as SNI in the client's handshake to support virtual hosting
	// - as the value for `:authority` header at stream creation time
	//
	// Deprecated: use grpc.WithAuthority instead. Will be supported
	// throughout 1.x.
	OverrideServerName(string) error
}

TransportCredentials defines the common interface for all the live gRPC wire protocols and supported transport security protocols (e.g., TLS, SSL).

func NewClientTLSFromCert 

func NewClientTLSFromCert(cp *x509.CertPool, serverNameOverride string) TransportCredentials

NewClientTLSFromCert constructs TLS credentials from the provided root certificate authority certificate(s) to validate server connections. If certificates to establish the identity of the client need to be included in the credentials (eg: for mTLS), use NewTLS instead, where a complete tls.Config can be specified. serverNameOverride is for testing only. If set to a non empty string, it will override the virtual host name of authority (e.g. :authority header field) in requests.

func NewClientTLSFromFile 

func NewClientTLSFromFile(certFile, serverNameOverride string) (TransportCredentials, error)

NewClientTLSFromFile constructs TLS credentials from the provided root certificate authority certificate file(s) to validate server connections. If certificates to establish the identity of the client need to be included in the credentials (eg: for mTLS), use NewTLS instead, where a complete tls.Config can be specified. serverNameOverride is for testing only. If set to a non empty string, it will override the virtual host name of authority (e.g. :authority header field) in requests.

func NewServerTLSFromCert 

func NewServerTLSFromCert(cert *tls.Certificate) TransportCredentials

NewServerTLSFromCert constructs TLS credentials from the input certificate for server.

func NewServerTLSFromFile 

func NewServerTLSFromFile(certFile, keyFile string) (TransportCredentials, error)

NewServerTLSFromFile constructs TLS credentials from the input certificate file and key file for server.

func NewTLS 

func NewTLS(c *tls.Config) TransportCredentials

NewTLS uses c to construct a TransportCredentials based on TLS.

Source Files

View all Source files

Directories

Path Synopsis
Package alts implements the ALTS credential support by gRPC library, which encapsulates all the state needed by a client to authenticate with a server using ALTS and make various assertions, e.g., about the client's identity, role, or whether it is authorized to make a particular call.
 Package alts implements the ALTS credential support by gRPC library, which encapsulates all the state needed by a client to authenticate with a server using ALTS and make various assertions, e.g., about the client's identity, role, or whether it is authorized to make a particular call.
internal
Package internal contains common core functionality for ALTS.
 Package internal contains common core functionality for ALTS.
internal/authinfo
Package authinfo provide authentication information returned by handshakers.
 Package authinfo provide authentication information returned by handshakers.
internal/conn
Package conn contains an implementation of a secure channel created by gRPC handshakers.
 Package conn contains an implementation of a secure channel created by gRPC handshakers.
internal/handshaker
Package handshaker provides ALTS handshaking functionality for GCP.
 Package handshaker provides ALTS handshaking functionality for GCP.
internal/handshaker/service
Package service manages connections between the VM application and the ALTS handshaker service.
 Package service manages connections between the VM application and the ALTS handshaker service.
internal/proto/grpc_gcp
internal/testutil
Package testutil include useful test utilities for the handshaker.
 Package testutil include useful test utilities for the handshaker.
Package google defines credentials for google cloud services.
 Package google defines credentials for google cloud services.
Package insecure provides an implementation of the credentials.TransportCredentials interface which disables transport security.
 Package insecure provides an implementation of the credentials.TransportCredentials interface which disables transport security.
Package internal contains gRPC-internal code, to avoid polluting the godoc of the top-level grpc package.
 Package internal contains gRPC-internal code, to avoid polluting the godoc of the top-level grpc package.
credentials
Package credentials defines APIs for parsing SPIFFE ID.
 Package credentials defines APIs for parsing SPIFFE ID.
credentials/xds
Package xds contains non-user facing functionality of the xds credentials.
 Package xds contains non-user facing functionality of the xds credentials.
grpctest
Package grpctest implements testing helpers.
 Package grpctest implements testing helpers.
leakcheck
Package leakcheck contains functions to check leaked goroutines.
 Package leakcheck contains functions to check leaked goroutines.
transport
Package transport defines and implements message oriented communication channel to complete various transactions (e.g., an RPC).
 Package transport defines and implements message oriented communication channel to complete various transactions (e.g., an RPC).
transport/networktype
Package networktype declares the network type to be used in the default dialer.
 Package networktype declares the network type to be used in the default dialer.
xds/matcher
Package matcher contains types that need to be shared between code under google.golang.org/grpc/xds/...
 Package matcher contains types that need to be shared between code under google.golang.org/grpc/xds/...
xds/rbac
Package rbac provides service-level and method-level access control for a service.
 Package rbac provides service-level and method-level access control for a service.
Package local implements local transport credentials.
 Package local implements local transport credentials.
Package oauth implements gRPC credentials using OAuth.
 Package oauth implements gRPC credentials using OAuth.
Package sts implements call credentials using STS (Security Token Service) as defined in https://tools.ietf.org/html/rfc8693.
 Package sts implements call credentials using STS (Security Token Service) as defined in https://tools.ietf.org/html/rfc8693.
tls
certprovider
Package certprovider defines APIs for Certificate Providers in gRPC.
 Package certprovider defines APIs for Certificate Providers in gRPC.
certprovider/pemfile
Package pemfile provides a file watching certificate provider plugin implementation which works for files with PEM contents.
 Package pemfile provides a file watching certificate provider plugin implementation which works for files with PEM contents.
Package xds provides a transport credentials implementation where the security configuration is pushed by a management server using xDS APIs.
 Package xds provides a transport credentials implementation where the security configuration is pushed by a management server using xDS APIs.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.