istio: Index | Files

package security

import ""


Package Files

mock.go retry.go security.go


const (

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

    // 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"

    // LocalSDS is the location of the in-process SDS server - must be in a writeable dir.
    DefaultLocalSDSPath = "./etc/istio/proxy/SDS"

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

    // Credential fetcher type
    GCE  = "GoogleComputeEngine"
    Mock = "Mock" // testing only
const (
    // IdentityTemplate is the SPIFFE format template of the identity.
    IdentityTemplate = "spiffe://%s/ns/%s/sa/%s"


var (
    // Require 3P TOKEN 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(), ",")

    XDSTokenType = env.RegisterStringVar("XDS_TOKEN_TYPE", "Bearer",
        "Token type in the Authorization header.").Get()

    BearerTokenPrefix = XDSTokenType + " "

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

var CARetryOptions = []retry.CallOption{
    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.

func CARetryInterceptor Uses

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 ExtractBearerToken Uses

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

type AuthSource Uses

type AuthSource int

AuthSource represents where authentication result is derived from.

const (
    AuthSourceClientCertificate AuthSource = iota

type Authenticator Uses

type Authenticator interface {
    Authenticate(ctx context.Context) (*Caller, error)
    AuthenticatorType() string

type Caller Uses

type Caller struct {
    AuthSource AuthSource
    Identities []string

Caller carries the identity and authentication source of a caller.

type Client Uses

type Client interface {
    CSRSign(csrPEM []byte, certValidTTLInSec int64) ([]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 Uses

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

    // GetType returns credential fetcher type. Currently the supported type is "GoogleComputeEngine".
    GetType() string

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

type DirectSecretManager Uses

type DirectSecretManager struct {
    // contains filtered or unexported fields

func NewDirectSecretManager Uses

func NewDirectSecretManager() *DirectSecretManager

func (*DirectSecretManager) GenerateSecret Uses

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

func (*DirectSecretManager) Set Uses

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

type FakeAuthenticator Uses

type FakeAuthenticator struct {
    AllowedToken string
    AllowedCert  string
    Name         string

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

func NewFakeAuthenticator Uses

func NewFakeAuthenticator(name string) *FakeAuthenticator

func (*FakeAuthenticator) Authenticate Uses

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

func (*FakeAuthenticator) AuthenticatorType Uses

func (f *FakeAuthenticator) AuthenticatorType() string

func (*FakeAuthenticator) Set Uses

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

type Options Uses

type Options struct {
    // WorkloadUDSPath is the unix domain socket through which SDS server communicates with workload proxies.
    WorkloadUDSPath string

    // CAEndpoint is the CA endpoint to which node agent sends CSR request.
    CAEndpoint string

    // The CA provider name.
    CAProviderName string

    // TrustDomain corresponds to the trust root of a system.
    TrustDomain string

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

    // Location of JWTPath to connect to CA.
    JWTPath string

    // 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
    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

    // 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

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 SecretItem Uses

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 Uses

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 Uses

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

type TokenExchanger Uses

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 Uses

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.

Package security imports 18 packages (graph) and is imported by 27 packages. Updated 2021-01-26. Refresh now. Tools for package owners.