Documentation
¶
Overview ¶
Package keyring provides keyring utilities for the ARK SDK.
This package contains internal implementations including a basic keyring system for secure password storage using AES encryption. The ArkBasicKeyring provides file-based storage with MAC (Message Authentication Code) validation to ensure data integrity.
Package keyring provides keyring utilities for the ARK SDK.
This package implements cross-platform keyring support with automatic fallback mechanisms for different environments including Docker containers, WSL, and various operating systems. The keyring handles token expiration, automatic cleanup, and secure storage of authentication credentials for ARK SDK applications.
Package keyring provides keyring utilities for the ARK SDK.
This package contains internal implementations including a OS based keyring system for secure password storage. The ArkOSProvidedKeyring provides OS based storage.
Index ¶
- Constants
- Variables
- type ArkBasicKeyring
- func (b *ArkBasicKeyring) ClearAllPasswords() error
- func (b *ArkBasicKeyring) DeletePassword(serviceName string, username string) error
- func (b *ArkBasicKeyring) GetPassword(serviceName string, username string) (string, error)
- func (b *ArkBasicKeyring) SetPassword(serviceName string, username string, password string) error
- type ArkKeyring
- func (a *ArkKeyring) GetKeyring(enforceBasicKeyring bool) (ArkKeyringImpl, error)
- func (a *ArkKeyring) LoadToken(profile *models.ArkProfile, postfix string, enforceBasicKeyring bool) (*auth.ArkToken, error)
- func (a *ArkKeyring) SaveToken(profile *models.ArkProfile, token *auth.ArkToken, postfix string, ...) error
- type ArkKeyringImpl
- type ArkOSProvidedKeyring
- func (b *ArkOSProvidedKeyring) ClearAllPasswords() error
- func (b *ArkOSProvidedKeyring) DeletePassword(serviceName string, username string) error
- func (b *ArkOSProvidedKeyring) GetPassword(serviceName string, username string) (string, error)
- func (b *ArkOSProvidedKeyring) SetPassword(serviceName string, username string, password string) error
Constants ¶
const ( // DefaultBasicKeyringFolder is the default folder path relative to HOME directory // where the basic keyring files are stored. DefaultBasicKeyringFolder = ".ark_cache/keyring" // ArkBasicKeyringFolderEnvVar is the environment variable name that can be used // to override the default keyring folder location. ArkBasicKeyringFolderEnvVar = "ARK_KEYRING_FOLDER" )
Keyring configuration constants
const ( ArkBasicKeyringOverrideEnvVar = "ARK_BASIC_KEYRING" DBusSessionEnvVar = "DBUS_SESSION_BUS_ADDRESS" DefaultExpirationGraceDeltaSeconds = 60 MaxKeyringRecordTimeHours = 12 )
Env vars and definitions
Variables ¶
var OSKeyringOpen = keyring.Open
OSKeyringOpen is a variable that points to the keyring.Open function from the go-keyring package.
Functions ¶
This section is empty.
Types ¶
type ArkBasicKeyring ¶
type ArkBasicKeyring struct {
ArkKeyringImpl
// contains filtered or unexported fields
}
ArkBasicKeyring is a simple keyring implementation that uses AES encryption to store passwords.
ArkBasicKeyring provides secure password storage using AES-GCM encryption with the hostname as the encryption key. Passwords are stored in a JSON file with MAC (Message Authentication Code) validation to ensure data integrity. The keyring supports multiple services and usernames within each service.
The encryption key is derived from the system hostname and padded using PKCS7 padding to ensure consistent key length. Each password entry is encrypted separately with its own nonce for security.
File Structure:
- keyring: JSON file containing encrypted password data
- mac: File containing SHA256 hash of keyring file for integrity validation
func NewArkBasicKeyring ¶
func NewArkBasicKeyring() *ArkBasicKeyring
NewArkBasicKeyring creates a new ArkBasicKeyring instance with initialized folder and file paths.
NewArkBasicKeyring initializes the keyring folder structure and returns a new ArkBasicKeyring instance. The folder location is determined by the ArkBasicKeyringFolderEnvVar environment variable, or defaults to DefaultBasicKeyringFolder within the user's HOME directory.
The function automatically creates the keyring folder if it doesn't exist. If folder creation fails, the function returns nil.
Returns a new ArkBasicKeyring instance or nil if folder creation fails.
Environment Variables:
- ARK_KEYRING_FOLDER: Override default keyring folder location
- HOME: Used for default keyring folder path construction
Example:
keyring := NewArkBasicKeyring()
if keyring == nil {
// Handle keyring initialization failure
}
func (*ArkBasicKeyring) ClearAllPasswords ¶
func (b *ArkBasicKeyring) ClearAllPasswords() error
ClearAllPasswords removes all stored passwords and MAC validation files from the keyring.
ClearAllPasswords deletes the keyring file and its associated MAC file, effectively clearing all stored passwords for all services and users. If either file does not exist, the function returns nil without error (idempotent behavior).
Returns an error if file removal fails for either the keyring or MAC file.
Example:
err := keyring.ClearAllPasswords()
if err != nil {
// Handle error
}
func (*ArkBasicKeyring) DeletePassword ¶
func (b *ArkBasicKeyring) DeletePassword(serviceName string, username string) error
DeletePassword deletes a password for a given service and username from the keyring.
DeletePassword removes the specified password entry from the keyring and updates the MAC file to maintain data integrity. If the keyring file doesn't exist, the service doesn't exist, or the username doesn't exist, the function returns nil without error (idempotent behavior).
Parameters:
- serviceName: The name of the service to delete password from
- username: The username to delete password for
Returns an error if file operations, JSON marshaling, or MAC update fails.
Example:
err := keyring.DeletePassword("github", "myuser")
if err != nil {
// Handle deletion error
}
func (*ArkBasicKeyring) GetPassword ¶
func (b *ArkBasicKeyring) GetPassword(serviceName string, username string) (string, error)
GetPassword retrieves a password for a given service and username from the keyring.
GetPassword decrypts and returns the stored password for the specified service and username combination. The function validates the keyring MAC before accessing the data to ensure integrity. If the keyring file doesn't exist, the service doesn't exist, or the username doesn't exist, an empty string is returned without error.
Parameters:
- serviceName: The name of the service to retrieve password for
- username: The username to retrieve password for
Returns the decrypted password string and any error encountered during retrieval. Returns empty string with nil error if the entry doesn't exist.
Example:
password, err := keyring.GetPassword("github", "myuser")
if err != nil {
// Handle retrieval error
}
if password == "" {
// Password not found
}
func (*ArkBasicKeyring) SetPassword ¶
func (b *ArkBasicKeyring) SetPassword(serviceName string, username string, password string) error
SetPassword sets a password for a given service and username in the keyring.
SetPassword encrypts and stores a password for the specified service and username combination. The password is encrypted using AES-GCM with a key derived from the system hostname. If a keyring file already exists, it loads the existing data and adds the new entry. The function updates the MAC file after successful storage to maintain data integrity validation.
Parameters:
- serviceName: The name of the service (e.g., "github", "aws")
- username: The username for the service
- password: The password to encrypt and store
Returns an error if encryption, file operations, or MAC update fails.
Example:
err := keyring.SetPassword("github", "myuser", "mypassword")
if err != nil {
// Handle password storage error
}
type ArkKeyring ¶
type ArkKeyring struct {
// contains filtered or unexported fields
}
ArkKeyring represents a keyring for storing and retrieving authentication tokens.
ArkKeyring provides a secure storage mechanism for authentication tokens with automatic fallback to basic keyring when system keyrings are unavailable. It supports different keyring backends based on the operating system and environment, including Docker containers and WSL environments.
The keyring handles token expiration, refresh token management, and automatic cleanup of expired tokens based on configurable time limits.
func NewArkKeyring ¶
func NewArkKeyring(serviceName string) *ArkKeyring
NewArkKeyring creates a new instance of ArkKeyring with the specified service name.
The service name is used as a namespace for storing tokens in the keyring, allowing multiple applications or services to use the same keyring without conflicts.
Parameters:
- serviceName: The name used to identify this service's tokens in the keyring
Returns a new ArkKeyring instance configured with the provided service name and a logger for keyring operations.
Example:
keyring := NewArkKeyring("myapp")
func (*ArkKeyring) GetKeyring ¶
func (a *ArkKeyring) GetKeyring(enforceBasicKeyring bool) (ArkKeyringImpl, error)
GetKeyring returns a keyring instance based on the operating system and environment.
GetKeyring automatically selects the most appropriate keyring backend based on the current environment. It falls back to basic keyring in Docker containers, WSL environments, when the ARK_BASIC_KEYRING environment variable is set, or when enforceBasicKeyring is true. For Windows, macOS, and Linux systems with proper D-Bus session, it attempts to use system-specific secure storage.
Parameters:
- enforceBasicKeyring: When true, forces the use of basic keyring regardless of environment
Returns a ArkBasicKeyring instance configured for the current environment, or an error if keyring initialization fails.
Example:
keyring, err := arkKeyring.GetKeyring(false)
if err != nil {
// handle error
}
func (*ArkKeyring) LoadToken ¶
func (a *ArkKeyring) LoadToken(profile *models.ArkProfile, postfix string, enforceBasicKeyring bool) (*auth.ArkToken, error)
LoadToken loads an authentication token from the keyring for the specified profile and postfix.
LoadToken retrieves and validates a stored authentication token from the keyring. It performs automatic token expiration checking and cleanup. For tokens without refresh capability that are expired beyond the grace period, the token is removed and nil is returned. For tokens with refresh capability that have been cached too long, they are also removed and nil is returned. If the initial load fails and enforceBasicKeyring is false, it automatically falls back to basic keyring.
Parameters:
- profile: The ARK profile containing the profile name used as the keyring username
- postfix: A suffix added to the service name to match the key used during SaveToken
- enforceBasicKeyring: When true, uses basic keyring without attempting system keyring first
Returns the loaded token if found and valid, nil if no token exists or token is expired, or an error if the keyring operation fails.
Example:
token, err := keyring.LoadToken(profile, "access", false)
if err != nil {
// handle load error
}
if token == nil {
// no valid token found, need to authenticate
}
func (*ArkKeyring) SaveToken ¶
func (a *ArkKeyring) SaveToken(profile *models.ArkProfile, token *auth.ArkToken, postfix string, enforceBasicKeyring bool) error
SaveToken saves an authentication token to the keyring for the specified profile and postfix.
SaveToken stores the provided token in the keyring using a composite key format of "serviceName-postfix" and the profile name. The token is serialized to JSON before storage. If the initial save fails and enforceBasicKeyring is false, it automatically falls back to basic keyring storage.
Parameters:
- profile: The ARK profile containing the profile name used as the keyring username
- token: The authentication token to store in the keyring
- postfix: A suffix added to the service name to create unique keys for different token types
- enforceBasicKeyring: When true, uses basic keyring without attempting system keyring first
Returns an error if the token cannot be saved to any available keyring backend.
Example:
err := keyring.SaveToken(profile, token, "access", false)
if err != nil {
// handle save error
}
type ArkKeyringImpl ¶
type ArkKeyringImpl interface {
SetPassword(serviceName string, username string, password string) error
GetPassword(serviceName string, username string) (string, error)
DeletePassword(serviceName string, username string) error
ClearAllPasswords() error
}
ArkKeyringImpl defines the interface for keyring operations.
type ArkOSProvidedKeyring ¶
type ArkOSProvidedKeyring struct {
ArkKeyringImpl
// contains filtered or unexported fields
}
ArkOSProvidedKeyring provides an OS-based keyring implementation for secure password storage.
ArkOSProvidedKeyring wraps the underlying OS keyring and falls back to a basic keyring implementation if the OS keyring is unavailable or encounters errors. It is intended for use in environments where secure credential storage is required.
Fields:
- ArkKeyringImpl: Embedded base implementation for keyring operations.
- fallbackKeyring: The fallback keyring implementation used if OS keyring fails.
- logger: Logger instance for warning and error messages.
func NewArkOSProvidedKeyring ¶
func NewArkOSProvidedKeyring(fallbackKeyring ArkKeyringImpl) *ArkOSProvidedKeyring
NewArkOSProvidedKeyring creates a new ArkOSProvidedKeyring instance.
NewArkOSProvidedKeyring initializes the OS-based keyring with a fallback keyring implementation. The fallbackKeyring is used if the OS keyring is unavailable or encounters errors.
Parameters:
- fallbackKeyring: ArkKeyringImpl. The fallback keyring implementation to use.
Returns a pointer to the initialized ArkOSProvidedKeyring.
Example:
fallback := NewBasicKeyring() keyring := NewArkOSProvidedKeyring(fallback)
func (*ArkOSProvidedKeyring) ClearAllPasswords ¶
func (b *ArkOSProvidedKeyring) ClearAllPasswords() error
ClearAllPasswords removes all stored passwords from the OS keyring and the fallback keyring.
ClearAllPasswords attempts to remove all password entries from the OS keyring that match the ARK SDK prefix. If the OS keyring cannot be opened or keys cannot be listed, it logs a warning and falls back to the basic keyring's ClearAllPasswords method. The function is idempotent and will not return an error if no entries exist.
Returns an error if removal fails for either the OS keyring or the fallback keyring.
Example:
err := keyring.ClearAllPasswords()
if err != nil {
// Handle error
}
func (*ArkOSProvidedKeyring) DeletePassword ¶
func (b *ArkOSProvidedKeyring) DeletePassword(serviceName string, username string) error
DeletePassword removes a password from the OS keyring for the specified service and username.
DeletePassword attempts to delete the password using the OS keyring. If the OS keyring operation fails, it logs a warning and falls back to the provided basic keyring implementation.
Parameters:
- serviceName: string. The name of the service for which the password is deleted.
- username: string. The username associated with the password.
Returns an error if the password could not be deleted from either the OS keyring or the fallback keyring.
Example:
err := keyring.DeletePassword("my_service", "user1")
if err != nil {
// handle error
}
func (*ArkOSProvidedKeyring) GetPassword ¶
func (b *ArkOSProvidedKeyring) GetPassword(serviceName string, username string) (string, error)
GetPassword retrieves a password from the OS keyring for the specified service and username.
GetPassword attempts to retrieve the password using the OS keyring. If the OS keyring operation fails, it logs a warning and falls back to the provided basic keyring implementation.
Parameters:
- serviceName: string. The name of the service for which the password is retrieved.
- username: string. The username associated with the password.
Returns the password as a string and an error if retrieval fails from both the OS keyring and the fallback keyring.
Example:
password, err := keyring.GetPassword("my_service", "user1")
if err != nil {
// handle error
}
func (*ArkOSProvidedKeyring) SetPassword ¶
func (b *ArkOSProvidedKeyring) SetPassword(serviceName string, username string, password string) error
SetPassword stores a password in the OS keyring for the specified service and username.
SetPassword attempts to securely store the password using the OS keyring. If the OS keyring operation fails, it logs a warning and falls back to the provided basic keyring implementation.
Parameters:
- serviceName: string. The name of the service for which the password is stored.
- username: string. The username associated with the password.
- password: string. The password to store.
Returns an error if the password could not be stored in either the OS keyring or the fallback keyring.
Example:
err := keyring.SetPassword("my_service", "user1", "secret")
if err != nil {
// handle error
}
Source Files