grpc: google.golang.org/grpc/security/advancedtls Index | Files

package advancedtls

import "google.golang.org/grpc/security/advancedtls"

Package advancedtls is a utility library containing functions to construct credentials.TransportCredentials that can perform credential reloading and custom verification check.

Index

Package Files

advancedtls.go pemfile_provider.go sni.go

func NewClientCreds Uses

func NewClientCreds(o *ClientOptions) (credentials.TransportCredentials, error)

NewClientCreds uses ClientOptions to construct a TransportCredentials based on TLS.

func NewServerCreds Uses

func NewServerCreds(o *ServerOptions) (credentials.TransportCredentials, error)

NewServerCreds uses ServerOptions to construct a TransportCredentials based on TLS.

func WrapSyscallConn Uses

func WrapSyscallConn(rawConn, newConn net.Conn) net.Conn

WrapSyscallConn tries to wrap rawConn and newConn into a net.Conn that implements syscall.Conn. rawConn will be used to support syscall, and newConn will be used for read/write.

This function returns newConn if rawConn doesn't implement syscall.Conn.

type ClientOptions Uses

type ClientOptions struct {
    // IdentityOptions is OPTIONAL on client side. This field only needs to be
    // set if mutual authentication is required on server side.
    IdentityOptions IdentityCertificateOptions
    // VerifyPeer is a custom verification check after certificate signature
    // check.
    // If this is set, we will perform this customized check after doing the
    // normal check(s) indicated by setting VType.
    VerifyPeer CustomVerificationFunc
    // 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.
    ServerNameOverride string
    // RootOptions is OPTIONAL on client side. If not set, we will try to use the
    // default trust certificates in users' OS system.
    RootOptions RootCertificateOptions
    // VType is the verification type on the client side.
    VType VerificationType
}

ClientOptions contains the fields needed to be filled by the client.

type CustomVerificationFunc Uses

type CustomVerificationFunc func(params *VerificationFuncParams) (*VerificationResults, error)

CustomVerificationFunc is the function defined by users to perform custom verification check. CustomVerificationFunc returns nil if the authorization fails; otherwise returns an empty struct.

type GetRootCAsParams Uses

type GetRootCAsParams struct {
    RawConn  net.Conn
    RawCerts [][]byte
}

GetRootCAsParams contains the parameters available to users when implementing GetRootCAs.

type GetRootCAsResults Uses

type GetRootCAsResults struct {
    TrustCerts *x509.CertPool
}

GetRootCAsResults contains the results of GetRootCAs. If users want to reload the root trust certificate, it is required to return the proper TrustCerts in GetRootCAs.

type IdentityCertificateOptions Uses

type IdentityCertificateOptions struct {
    // If Certificates is set, it will be used every time when needed to present
    //identity certificates, without performing identity certificate reloading.
    Certificates []tls.Certificate
    // If GetIdentityCertificatesForClient is set, it will be invoked to obtain
    // identity certs for every new connection.
    // This field MUST be set on client side.
    GetIdentityCertificatesForClient func(*tls.CertificateRequestInfo) (*tls.Certificate, error)
    // If GetIdentityCertificatesForServer is set, it will be invoked to obtain
    // identity certs for every new connection.
    // This field MUST be set on server side.
    GetIdentityCertificatesForServer func(*tls.ClientHelloInfo) ([]*tls.Certificate, error)
    // If IdentityProvider is set, we will use the identity certs from the
    // Provider's KeyMaterial() call in the new connections. The Provider must
    // have initial credentials if specified. Otherwise, KeyMaterial() will block
    // forever.
    IdentityProvider certprovider.Provider
}

IdentityCertificateOptions contains options to obtain identity certificates for both the client and the server. At most one option could be set.

type PEMFileProvider Uses

type PEMFileProvider struct {
    // contains filtered or unexported fields
}

PEMFileProvider implements certprovider.Provider. It provides the most up-to-date identity private key-cert pairs and/or root certificates.

func NewPEMFileProvider Uses

func NewPEMFileProvider(o PEMFileProviderOptions) (*PEMFileProvider, error)

NewPEMFileProvider returns a new PEMFileProvider constructed using the provided options.

func (*PEMFileProvider) Close Uses

func (p *PEMFileProvider) Close()

Close cleans up resources allocated by the PEMFileProvider.

func (*PEMFileProvider) KeyMaterial Uses

func (p *PEMFileProvider) KeyMaterial(ctx context.Context) (*certprovider.KeyMaterial, error)

KeyMaterial returns the key material sourced by the PEMFileProvider. Callers are expected to use the returned value as read-only.

type PEMFileProviderOptions Uses

type PEMFileProviderOptions struct {
    // CertFile is the file path that holds identity certificate whose updates
    // will be captured by a watching goroutine.
    // Optional. If this is set, KeyFile must also be set.
    CertFile string
    // KeyFile is the file path that holds identity private key whose updates
    // will be captured by a watching goroutine.
    // Optional. If this is set, CertFile must also be set.
    KeyFile string
    // TrustFile is the file path that holds trust certificate whose updates will
    // be captured by a watching goroutine.
    // Optional.
    TrustFile string
    // IdentityInterval is the time duration between two credential update checks
    // for identity certs.
    // Optional. If not set, we will use the default interval(1 hour).
    IdentityInterval time.Duration
    // RootInterval is the time duration between two credential update checks
    // for root certs.
    // Optional. If not set, we will use the default interval(2 hours).
    RootInterval time.Duration
}

PEMFileProviderOptions contains options to configure a PEMFileProvider. Note that these fields will only take effect during construction. Once the PEMFileProvider starts, changing fields in PEMFileProviderOptions will have no effect.

type RootCertificateOptions Uses

type RootCertificateOptions struct {
    // If RootCACerts is set, it will be used every time when verifying
    // the peer certificates, without performing root certificate reloading.
    RootCACerts *x509.CertPool
    // If GetRootCertificates is set, it will be invoked to obtain root certs for
    // every new connection.
    GetRootCertificates func(params *GetRootCAsParams) (*GetRootCAsResults, error)
    // If RootProvider is set, we will use the root certs from the Provider's
    // KeyMaterial() call in the new connections. The Provider must have initial
    // credentials if specified. Otherwise, KeyMaterial() will block forever.
    RootProvider certprovider.Provider
}

RootCertificateOptions contains options to obtain root trust certificates for both the client and the server. At most one option could be set. If none of them are set, we use the system default trust certificates.

type ServerOptions Uses

type ServerOptions struct {
    // IdentityOptions is REQUIRED on server side.
    IdentityOptions IdentityCertificateOptions
    // VerifyPeer is a custom verification check after certificate signature
    // check.
    // If this is set, we will perform this customized check after doing the
    // normal check(s) indicated by setting VType.
    VerifyPeer CustomVerificationFunc
    // RootOptions is OPTIONAL on server side. This field only needs to be set if
    // mutual authentication is required(RequireClientCert is true).
    RootOptions RootCertificateOptions
    // If the server want the client to send certificates.
    RequireClientCert bool
    // VType is the verification type on the server side.
    VType VerificationType
}

ServerOptions contains the fields needed to be filled by the server.

type VerificationFuncParams Uses

type VerificationFuncParams struct {
    // The target server name that the client connects to when establishing the
    // connection. This field is only meaningful for client side. On server side,
    // this field would be an empty string.
    ServerName string
    // The raw certificates sent from peer.
    RawCerts [][]byte
    // The verification chain obtained by checking peer RawCerts against the
    // trust certificate bundle(s), if applicable.
    VerifiedChains [][]*x509.Certificate
    // The leaf certificate sent from peer, if choosing to verify the peer
    // certificate(s) and that verification passed. This field would be nil if
    // either user chose not to verify or the verification failed.
    Leaf *x509.Certificate
}

VerificationFuncParams contains parameters available to users when implementing CustomVerificationFunc. The fields in this struct are read-only.

type VerificationResults Uses

type VerificationResults struct{}

VerificationResults contains the information about results of CustomVerificationFunc. VerificationResults is an empty struct for now. It may be extended in the future to include more information.

type VerificationType Uses

type VerificationType int

VerificationType is the enum type that represents different levels of verification users could set, both on client side and on server side.

const (
    // CertAndHostVerification indicates doing both certificate signature check
    // and hostname check.
    CertAndHostVerification VerificationType = iota
    // CertVerification indicates doing certificate signature check only. Setting
    // this field without proper custom verification check would leave the
    // application susceptible to the MITM attack.
    CertVerification
    // SkipVerification indicates skipping both certificate signature check and
    // hostname check. If setting this field, proper custom verification needs to
    // be implemented in order to complete the authentication. Setting this field
    // with a nil custom verification would raise an error.
    SkipVerification
)

Package advancedtls imports 13 packages (graph) and is imported by 3 packages. Updated 2020-09-18. Refresh now. Tools for package owners.