Documentation
¶
Overview ¶
Package auth provides functionality for authenticating with container registries. It handles token retrieval and challenge URL generation for registry access.
Index ¶
- Constants
- Variables
- func GetAuthURL(challenge string, imageRef reference.Named) (*url.URL, error)
- func GetBearerHeader(ctx context.Context, challenge string, imageRef reference.Named, ...) (string, error)
- func GetChallengeRequest(ctx context.Context, url url.URL) (*http.Request, error)
- func GetChallengeURL(imageRef reference.Named) url.URL
- func GetRegistryAddress(imageRef string) (string, error)
- func GetToken(ctx context.Context, container types.Container, registryAuth string, ...) (string, string, bool, error)
- func ProcessChallenge(wwwAuthHeader, image string) (string, string, string, error)
- func TransformAuth(registryAuth string) string
- type Client
Constants ¶
const ( DockerRegistryDomain = "docker.io" DockerRegistryHost = "index.docker.io" LSCRRegistry = "lscr.io" )
Domains for Docker Hub, the default registry.
const ( DefaultTimeoutSeconds = 30 // Default timeout for HTTP requests in seconds DefaultMaxIdleConns = 100 // Maximum number of idle connections in the pool DefaultIdleConnTimeoutSeconds = 90 // Timeout for idle connections in seconds DefaultTLSHandshakeTimeoutSeconds = 10 // Timeout for TLS handshake in seconds DefaultExpectContinueTimeout = 1 // Timeout for expecting continue response in seconds DefaultDialTimeoutSeconds = 30 // Timeout for establishing TCP connections in seconds DefaultDialKeepAliveSeconds = 30 // Keep-alive probes for persistent connections in seconds DefaultMaxRedirects = 3 // Maximum number of redirects to follow (reduced from Go's default of 10) )
Constants for HTTP client configuration. These values define timeouts and connection limits for registry requests.
const ChallengeHeader = "WWW-Authenticate"
ChallengeHeader is the HTTP Header containing challenge instructions.
Variables ¶
var TLSVersionMap = map[string]uint16{ "TLS1.0": tls.VersionTLS10, "TLS1.1": tls.VersionTLS11, "TLS1.2": tls.VersionTLS12, "TLS1.3": tls.VersionTLS13, }
TLSVersionMap maps string names to TLS version constants. It provides a lookup for configuring the minimum TLS version based on user settings.
Functions ¶
func GetAuthURL ¶
GetAuthURL constructs an authentication URL from challenge instructions.
Parameters:
- challenge: Challenge string from the registry.
- imageRef: Normalized image reference.
Returns:
- *url.URL: Constructed auth URL if successful.
- error: Non-nil if parsing fails, nil on success.
func GetBearerHeader ¶
func GetBearerHeader( ctx context.Context, challenge string, imageRef reference.Named, registryAuth string, client Client, ) (string, error)
GetBearerHeader fetches a bearer token based on challenge instructions.
Parameters:
- ctx: Context for request lifecycle control, enabling cancellation or timeouts.
- challenge: Challenge string from the registry’s WWW-Authenticate header.
- imageRef: Normalized image reference for scoping the token request.
- registryAuth: Base64-encoded auth string (e.g., "username:password").
- client: Client instance for executing HTTP requests.
Returns:
- string: Bearer token header (e.g., "Bearer ...") if successful.
- error: Non-nil if the operation fails, nil on success.
func GetChallengeRequest ¶
GetChallengeRequest creates a request for retrieving challenge instructions.
Parameters:
- ctx: Context for request lifecycle control.
- url: URL for the challenge request.
Returns:
- *http.Request: Constructed request if successful.
- error: Non-nil if creation fails, nil on success.
func GetChallengeURL ¶
GetChallengeURL generates a challenge URL for accessing an image's registry.
Parameters:
- imageRef: Normalized image reference.
Returns:
- url.URL: Generated challenge URL.
func GetRegistryAddress ¶
GetRegistryAddress extracts the registry address from an image reference.
It returns the domain part of the reference, mapping Docker Hub’s default domain to its canonical host if needed.
Parameters:
- imageRef: Image reference string (e.g., "docker.io/library/alpine").
Returns:
- string: Registry address (e.g., "index.docker.io") if successful.
- error: Non-nil if parsing fails, nil on success.
func GetToken ¶
func GetToken( ctx context.Context, container types.Container, registryAuth string, client Client, ) (string, string, bool, error)
GetToken fetches a token and the challenge host for the registry hosting the provided image.
Parameters:
- ctx: Context for request lifecycle control.
- container: Container with image info.
- registryAuth: Base64-encoded auth string.
- client: Client for HTTP requests.
Returns:
- string: Authentication token (e.g., "Basic ..." or "Bearer ...").
- string: Challenge host (e.g., "ghcr.io"), empty if not applicable.
- bool: True if the challenge request was redirected, false otherwise.
- error: Non-nil if operation fails, nil on success.
func ProcessChallenge ¶
ProcessChallenge parses the WWW-Authenticate header to extract authentication details.
It supports Bearer authentication, extracting the realm, service, and optional scope for token requests.
Parameters:
- wwwAuthHeader: The WWW-Authenticate header value (e.g., 'Bearer realm="https://ghcr.io/token",service="ghcr.io",scope="repository:linuxserver/nginx:pull"').
- image: The image name for logging context.
Returns:
- string: The scope for the token request (e.g., "repository:linuxserver/nginx:pull"), or empty if not provided.
- string: The realm URL for the token request (e.g., "https://ghcr.io/token").
- string: The service identifier (e.g., "ghcr.io").
- error: Non-nil if parsing fails critically (missing realm or service), nil otherwise.
func TransformAuth ¶
TransformAuth converts a base64-encoded JSON object into a base64-encoded "username:password" string. It decodes the input, extracts username and password from a RegistryCredentials struct, and re-encodes them for use in HTTP Basic Authentication headers, ensuring compatibility with registry requirements.
Parameters:
- registryAuth: A base64-encoded string, typically a JSON object with username and password fields.
Returns:
- string: A base64-encoded "username:password" string if credentials are present, otherwise the original input.
Types ¶
type Client ¶
type Client interface {
// Do executes the provided HTTP request and returns the response or an error.
//
// Parameters:
// - req: The HTTP request to execute.
//
// Returns:
// - *http.Response: The HTTP response from the registry, if successful.
// - error: Non-nil if the request fails, nil otherwise.
Do(req *http.Request) (*http.Response, error)
}
Client defines the interface for executing HTTP requests to container registries.
This interface abstracts the HTTP client used for authentication operations, enabling dependency injection and facilitating unit testing with mock implementations.
func NewAuthClient ¶
func NewAuthClient() Client
NewAuthClient returns a cached Client for registry authentication requests.
The client is initialized once on the first call using Viper configuration values WATCHTOWER_REGISTRY_TLS_SKIP and WATCHTOWER_REGISTRY_TLS_MIN_VERSION. Subsequent calls return the same cached client instance. The client is configured with default timeouts and connection limits for registry access.
Returns:
- Client: Ready for registry authentication requests.
Source Files
Directories