security

package
v1.0.0-rc2 Latest Latest
Warning

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

 Go to latest Published: Nov 11, 2023 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Index

Constants

View Source 
const (

	// DefaultCertChainFilePath is the well-known path for an existing certificate chain file
	DefaultCertChainFilePath = "./etc/certs/cert-chain.pem"

	// DefaultKeyFilePath is the well-known path for an existing key file
	DefaultKeyFilePath = "./etc/certs/key.pem"

	// DefaultRootCertFilePath is the well-known path for an existing root certificate file
	DefaultRootCertFilePath = "./etc/certs/root-cert.pem"

	// WorkloadIdentitySocketPath is the well-known path to the Unix Domain Socket for SDS.
	WorkloadIdentitySocketPath = "./var/run/secrets/workload-spiffe-uds/socket"

	// WorkloadIdentityCredentialsPath is the well-known path to a folder with workload certificate files.
	WorkloadIdentityCredentialsPath = "./var/run/secrets/workload-spiffe-credentials"

	// WorkloadIdentityCertChainPath is the well-known path to a workload certificate chain file.
	WorkloadIdentityCertChainPath = WorkloadIdentityCredentialsPath + "/cert-chain.pem"

	// WorkloadIdentityKeyPath is the well-known path to a workload key file.
	WorkloadIdentityKeyPath = WorkloadIdentityCredentialsPath + "/key.pem"

	// WorkloadIdentityRootCertPath is the well-known path to a workload root certificate file.
	WorkloadIdentityRootCertPath = WorkloadIdentityCredentialsPath + "/root-cert.pem"

	// GkeWorkloadCertChainFilePath is the well-known path for the GKE workload certificate chain file.
	// Quoted from https://cloud.google.com/traffic-director/docs/security-proxyless-setup#create-service:
	// "On creation, each Pod gets a volume at /var/run/secrets/workload-spiffe-credentials."
	GkeWorkloadCertChainFilePath = WorkloadIdentityCredentialsPath + "/certificates.pem"

	// GkeWorkloadKeyFilePath is the well-known path for the GKE workload certificate key file
	GkeWorkloadKeyFilePath = WorkloadIdentityCredentialsPath + "/private_key.pem"

	// GkeWorkloadRootCertFilePath is the well-known path for the GKE workload root certificate file
	GkeWorkloadRootCertFilePath = WorkloadIdentityCredentialsPath + "/ca_certificates.pem"

	// SystemRootCerts is special case input for root cert configuration to use system root certificates.
	SystemRootCerts = "SYSTEM"

	// RootCertReqResourceName is resource name of discovery request for root certificate.
	RootCertReqResourceName = "ROOTCA"

	// WorkloadKeyCertResourceName is the resource name of the discovery request for workload
	// identity.
	// TODO: change all the pilot one reference definition here instead.
	WorkloadKeyCertResourceName = "default"

	// GCE is Credential fetcher type of Google plugin
	GCE = "GoogleComputeEngine"

	// JWT is a Credential fetcher type that reads from a JWT token file
	JWT = "JWT"

	// Mock is Credential fetcher type of mock plugin
	Mock = "Mock" // testing only

	// GoogleCAProvider uses the Google CA for workload certificate signing
	GoogleCAProvider = "GoogleCA"

	// GoogleCASProvider uses the Google certificate Authority Service to sign workload certificates
	GoogleCASProvider = "GoogleCAS"

	// GkeWorkloadCertificateProvider uses the GKE workload certificates
	GkeWorkloadCertificateProvider = "GkeWorkloadCertificate"

	// FileRootSystemCACert is a unique resource name signaling that the system CA certificate should be used
	FileRootSystemCACert = "file-root:system"
)
View Source 
const (
	BearerTokenPrefix = "Bearer "

	K8sTokenPrefix = "Istio "

	// CertSigner info
	CertSigner = "CertSigner"
)
View Source 
const (
	ResourceSeparator = "~"
)

Variables

View Source 
var (
	// Require3PToken disables the use of K8S 1P tokens. Note that 1P tokens can be used to request
	// 3P TOKENS. A 1P token is the token automatically mounted by Kubelet and used for authentication with
	// the Apiserver.
	Require3PToken = env.RegisterBoolVar("REQUIRE_3P_TOKEN", false,
		"Reject k8s default tokens, without audience. If false, default K8S token will be accepted")

	// TokenAudiences specifies a list of audiences for SDS trustworthy JWT. This is to make sure that the CSR requests
	// contain the JWTs intended for Citadel.
	TokenAudiences = strings.Split(env.RegisterStringVar("TOKEN_AUDIENCES", "istio-ca",
		"A list of comma separated audiences to check in the JWT token before issuing a certificate. "+
			"The token is accepted if it matches with one of the audiences").Get(), ",")
)

TODO: For 1.8, make sure MeshConfig is updated with those settings, they should be dynamic to allow migrations without restart. Both are critical.

View Source 
var CARetryOptions = []retry.CallOption{
	retry.WithMax(5),
	retry.WithBackoff(wrapBackoffWithMetrics(retry.BackoffExponentialWithJitter(100*time.Millisecond, 0.1))),
	retry.WithCodes(codes.Canceled, codes.DeadlineExceeded, codes.ResourceExhausted, codes.Aborted, codes.Internal, codes.Unavailable),
}

CARetryOptions returns the default retry options recommended for CA calls This includes 5 retries, with backoff from 100ms -> 1.6s with jitter.

Functions

func CARetryInterceptor 

func CARetryInterceptor() grpc.DialOption

CARetryInterceptor is a grpc UnaryInterceptor that adds retry options, as a convenience wrapper around CARetryOptions. If needed to chain with other interceptors, the CARetryOptions can be used directly.

func CheckWorkloadCertificate 

func CheckWorkloadCertificate(certChainFilePath, keyFilePath, rootCertFilePath string) bool

CheckWorkloadCertificate returns true when the workload certificate files are present under the provided paths. Otherwise, return false.

func ExtractBearerToken 

func ExtractBearerToken(ctx context.Context) (string, error)

func ExtractRequestToken 

func ExtractRequestToken(req *http.Request) (string, error)

func GetOSRootFilePath 

func GetOSRootFilePath() string

GetOSRootFilePath returns the first file path detected from a list of known CA certificate file paths. If none of the known CA certificate files are found, a warning in printed and an empty string is returned.

Types

type AuthSource 

type AuthSource int

AuthSource represents where authentication result is derived from. 

const (
	AuthSourceClientCertificate AuthSource = iota
	AuthSourceIDToken
)

type Authenticator 

type Authenticator interface {
	Authenticate(ctx context.Context) (*Caller, error)
	AuthenticatorType() string
	AuthenticateRequest(req *http.Request) (*Caller, error)
}

type Caller 

type Caller struct {
	AuthSource AuthSource
	Identities []string
}

Caller carries the identity and authentication source of a caller.

type Client 

type Client interface {
	CSRSign(csrPEM []byte, certValidTTLInSec int64) ([]string, error)
	Close()
	// Retrieve CA root certs If CA publishes API endpoint for this
	GetRootCertBundle() ([]string, error)
}

Client interface defines the clients need to implement to talk to CA for CSR. The Agent will create a key pair and a CSR, and use an implementation of this interface to get back a signed certificate. There is no guarantee that the SAN in the request will be returned - server may replace it.

type CredFetcher 

type CredFetcher interface {
	// GetPlatformCredential fetches workload credential provided by the platform.
	GetPlatformCredential() (string, error)

	// GetIdentityProvider returns the name of the IdentityProvider that can authenticate the workload credential.
	GetIdentityProvider() string

	// Stop releases resources and cleans up.
	Stop()
}

type DirectSecretManager 

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

func NewDirectSecretManager 

func NewDirectSecretManager() *DirectSecretManager

func (*DirectSecretManager) GenerateSecret 

func (d *DirectSecretManager) GenerateSecret(resourceName string) (*SecretItem, error)

func (*DirectSecretManager) Set 

func (d *DirectSecretManager) Set(resourceName string, secret *SecretItem)

type FakeAuthenticator 

type FakeAuthenticator struct {
	AllowedToken string
	AllowedCert  string
	Name         string

	Successes *atomic.Int32
	Failures  *atomic.Int32
	// contains filtered or unexported fields
}

func NewFakeAuthenticator 

func NewFakeAuthenticator(name string) *FakeAuthenticator

func (*FakeAuthenticator) Authenticate 

func (f *FakeAuthenticator) Authenticate(ctx context.Context) (*Caller, error)

func (*FakeAuthenticator) AuthenticateRequest 

func (f *FakeAuthenticator) AuthenticateRequest(req *http.Request) (*Caller, error)

func (*FakeAuthenticator) AuthenticatorType 

func (f *FakeAuthenticator) AuthenticatorType() string

func (*FakeAuthenticator) Set 

func (f *FakeAuthenticator) Set(token string, identity string) *FakeAuthenticator

type Options 

type Options struct {
	// CAEndpoint is the CA endpoint to which node agent sends CSR request.
	CAEndpoint string

	// CAEndpointSAN overrides the ServerName extracted from CAEndpoint.
	CAEndpointSAN string

	// The CA provider name.
	CAProviderName string

	// TrustDomain corresponds to the trust root of a system.
	// https://github.com/spiffe/spiffe/blob/master/standards/SPIFFE-ID.md#21-trust-domain
	TrustDomain string

	// Whether to generate PKCS#8 private keys.
	Pkcs8Keys bool

	// OutputKeyCertToDir is the directory for output the key and certificate
	OutputKeyCertToDir string

	// ProvCert is the directory for client to provide the key and certificate to CA server when authenticating
	// with mTLS. This is not used for workload mTLS communication, and is
	ProvCert string

	// ClusterID is the cluster where the agent resides.
	// Normally initialized from ISTIO_META_CLUSTER_ID - after a tortuous journey it
	// makes its way into the ClusterID metadata of Citadel gRPC request to create the cert.
	// Didn't find much doc - but I suspect used for 'central cluster' use cases - so should
	// match the cluster name set in the MC setup.
	ClusterID string

	// The type of Elliptical Signature algorithm to use
	// when generating private keys. Currently only ECDSA is supported.
	ECCSigAlg string

	// FileMountedCerts indicates whether the proxy is using file
	// mounted certs created by a foreign CA. Refresh is managed by the external
	// CA, by updating the Secret or VM file. We will watch the file for changes
	// or check before the cert expires. This assumes the certs are in the
	// well-known ./etc/certs location.
	FileMountedCerts bool

	// PilotCertProvider is the provider of the Pilot certificate (PILOT_CERT_PROVIDER env)
	// Determines the root CA file to use for connecting to CA gRPC:
	// - istiod
	// - kubernetes
	// - custom
	// - none
	PilotCertProvider string

	// secret TTL.
	SecretTTL time.Duration

	// The ratio of cert lifetime to refresh a cert. For example, at 0.10 and 1 hour TTL,
	// we would refresh 6 minutes before expiration.
	SecretRotationGracePeriodRatio float64

	// STS port
	STSPort int

	// authentication provider specific plugins, will exchange the token
	// For example exchange long lived refresh with access tokens.
	// Used by the secret fetcher when signing CSRs.
	// Optional; if not present the token will be used directly
	TokenExchanger TokenExchanger

	// credential fetcher.
	CredFetcher CredFetcher

	// credential identity provider
	CredIdentityProvider string

	// Namespace corresponding to workload
	WorkloadNamespace string

	// Name of the Service Account
	ServiceAccount string

	// XDS auth provider
	XdsAuthProvider string

	// Token manager for the token exchange of XDS
	TokenManager TokenManager

	// Cert signer info
	CertSigner string

	// Delay in reading certificates from file after the change is detected. This is useful in cases
	// where the write operation of key and cert take longer.
	FileDebounceDuration time.Duration

	// Root Cert read from the OS
	CARootPath string

	// The path for an existing certificate chain file
	CertChainFilePath string
	// The path for an existing key file
	KeyFilePath string
	// The path for an existing root certificate bundle
	RootCertFilePath string
}

Options provides all of the configuration parameters for secret discovery service and CA configuration. Used in both Istiod and Agent. TODO: ProxyConfig should have most of those, and be passed to all components (as source of truth)

type SdsCertificateConfig 

type SdsCertificateConfig struct {
	CertificatePath   string
	PrivateKeyPath    string
	CaCertificatePath string
}

func SdsCertificateConfigFromResourceName 

func SdsCertificateConfigFromResourceName(resource string) (SdsCertificateConfig, bool)

SdsCertificateConfigFromResourceName converts the provided resource name into a SdsCertificateConfig If the resource name is not valid, false is returned.

func SdsCertificateConfigFromResourceNameForOSCACert 

func SdsCertificateConfigFromResourceNameForOSCACert(resource string) (SdsCertificateConfig, bool)

SdsCertificateConfigFromResourceNameForOSCACert converts the OS resource name into a SdsCertificateConfig

func (SdsCertificateConfig) GetResourceName 

func (s SdsCertificateConfig) GetResourceName() string

GetResourceName converts a SdsCertificateConfig to a string to be used as an SDS resource name

func (SdsCertificateConfig) GetRootResourceName 

func (s SdsCertificateConfig) GetRootResourceName() string

GetRootResourceName converts a SdsCertificateConfig to a string to be used as an SDS resource name for the root

func (SdsCertificateConfig) IsKeyCertificate 

func (s SdsCertificateConfig) IsKeyCertificate() bool

IsKeyCertificate returns true if this config represents key certificate config.

func (SdsCertificateConfig) IsRootCertificate 

func (s SdsCertificateConfig) IsRootCertificate() bool

IsRootCertificate returns true if this config represents a root certificate config.

type SecretItem 

type SecretItem struct {
	CertificateChain []byte
	PrivateKey       []byte

	RootCert []byte

	// ResourceName passed from envoy SDS discovery request.
	// "ROOTCA" for root cert request, "default" for key/cert request.
	ResourceName string

	CreatedTime time.Time

	ExpireTime time.Time
}

SecretItem is the cached item in in-memory secret store.

type SecretManager 

type SecretManager interface {
	// GenerateSecret generates new secret for the given resource.
	//
	// The current implementation also watched the generated secret and trigger a callback when it is
	// near expiry. It will constructs the SAN based on the token's 'sub' claim, expected to be in
	// the K8S format. No other JWTs are currently supported due to client logic. If JWT is
	// missing/invalid, the resourceName is used.
	GenerateSecret(resourceName string) (*SecretItem, error)
}

SecretManager defines secrets management interface which is used by SDS.

type StsRequestParameters 

type StsRequestParameters struct {
	// REQUIRED. The value "urn:ietf:params:oauth:grant-type:token- exchange"
	// indicates that a token exchange is being performed.
	GrantType string
	// OPTIONAL. Indicates the location of the target service or resource where
	// the client intends to use the requested security token.
	Resource string
	// OPTIONAL. The logical name of the target service where the client intends
	// to use the requested security token.
	Audience string
	// OPTIONAL. A list of space-delimited, case-sensitive strings, that allow
	// the client to specify the desired Scope of the requested security token in the
	// context of the service or Resource where the token will be used.
	Scope string
	// OPTIONAL. An identifier, for the type of the requested security token.
	RequestedTokenType string
	// REQUIRED. A security token that represents the identity of the party on
	// behalf of whom the request is being made.
	SubjectToken string
	// REQUIRED. An identifier, that indicates the type of the security token in
	// the "subject_token" parameter.
	SubjectTokenType string
	// OPTIONAL. A security token that represents the identity of the acting party.
	ActorToken string
	// An identifier, that indicates the type of the security token in the
	// "actor_token" parameter.
	ActorTokenType string
}

StsRequestParameters stores all STS request attributes defined in https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16#section-2.1

type TokenExchanger 

type TokenExchanger interface {
	// ExchangeToken provides a common interface to exchange an existing token for a new one.
	ExchangeToken(serviceAccountToken string) (string, error)
}

TokenExchanger provides common interfaces so that authentication providers could choose to implement their specific logic.

type TokenManager 

type TokenManager interface {
	// GenerateToken takes STS request parameters and generates token. Returns
	// StsResponseParameters in JSON.
	GenerateToken(parameters StsRequestParameters) ([]byte, error)
	// DumpTokenStatus dumps status of all generated tokens and returns status in JSON.
	DumpTokenStatus() ([]byte, error)
	// GetMetadata returns the metadata headers related to the token
	GetMetadata(forCA bool, xdsAuthProvider, token string) (map[string]string, error)
}

TokenManager contains methods for generating token.

Source Files

View all Source files

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.