Documentation
¶
Overview ¶
Package common provides internal shared utilities for the ARK SDK.
This package contains internal implementations including a basic keyring system for secure password storage using AES encryption. The BasicKeyring provides file-based storage with MAC (Message Authentication Code) validation to ensure data integrity.
Index ¶
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
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BasicAuthTransport ¶
type BasicAuthTransport struct {
// Transport is the underlying http.RoundTripper to wrap
Transport http.RoundTripper
// Username is the username for Basic Authentication
Username string
// Password is the password for Basic Authentication
Password string
}
BasicAuthTransport is a custom HTTP transport that adds Basic Authentication to requests.
BasicAuthTransport wraps an existing http.RoundTripper and automatically adds HTTP Basic Authentication headers to every HTTP request using the provided username and password credentials. This is useful for APIs that require Basic Authentication for all requests.
The transport preserves the behavior of the underlying transport while ensuring that the Authorization header is set with properly encoded Basic Authentication credentials on outgoing requests.
Example:
transport := &BasicAuthTransport{
Transport: http.DefaultTransport,
Username: "myuser",
Password: "mypassword",
}
func (*BasicAuthTransport) RoundTrip ¶
RoundTrip implements the http.RoundTripper interface and adds Basic Authentication to the request.
RoundTrip sets the Authorization header on the provided request using HTTP Basic Authentication with the configured username and password. The credentials are automatically encoded using base64 as required by the HTTP Basic Authentication standard. After setting the authentication header, it delegates to the underlying Transport's RoundTrip method to perform the actual HTTP request.
Parameters:
- req: The HTTP request to modify and execute
Returns the HTTP response from the underlying transport and any error encountered.
Example:
transport := &BasicAuthTransport{
Transport: http.DefaultTransport,
Username: "myuser",
Password: "mypassword",
}
resp, err := transport.RoundTrip(req)
type BasicKeyring ¶
type BasicKeyring struct {
// contains filtered or unexported fields
}
BasicKeyring is a simple keyring implementation that uses AES encryption to store passwords.
BasicKeyring 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 NewBasicKeyring ¶
func NewBasicKeyring() *BasicKeyring
NewBasicKeyring creates a new BasicKeyring instance with initialized folder and file paths.
NewBasicKeyring initializes the keyring folder structure and returns a new BasicKeyring 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 BasicKeyring 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 := NewBasicKeyring()
if keyring == nil {
// Handle keyring initialization failure
}
func (*BasicKeyring) DeletePassword ¶
func (b *BasicKeyring) DeletePassword(serviceName, 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 (*BasicKeyring) GetPassword ¶
func (b *BasicKeyring) GetPassword(serviceName, 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 (*BasicKeyring) SetPassword ¶
func (b *BasicKeyring) SetPassword(serviceName, username, 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 HeaderTransport ¶
type HeaderTransport struct {
// Transport is the underlying http.RoundTripper to wrap
Transport http.RoundTripper
// Headers is a map of header names to values that will be added to every request
Headers map[string]string
}
HeaderTransport is a custom HTTP transport that adds headers to requests.
HeaderTransport wraps an existing http.RoundTripper and automatically adds specified headers to every HTTP request. This is useful for adding common headers like User-Agent, Content-Type, or custom API headers to all requests made through the transport.
The transport preserves the behavior of the underlying transport while ensuring that all specified headers are set on outgoing requests. If a header already exists in the request, it will be overwritten with the value from the Headers map.
Example:
transport := &HeaderTransport{
Transport: http.DefaultTransport,
Headers: map[string]string{
"User-Agent": "MyApp/1.0",
"X-API-Key": "secret-key",
},
}
func (*HeaderTransport) RoundTrip ¶
RoundTrip implements the http.RoundTripper interface and adds headers to the request.
RoundTrip iterates through all headers in the Headers map and sets them on the provided request using req.Header.Set(). This overwrites any existing headers with the same name. After setting all headers, it delegates to the underlying Transport's RoundTrip method to perform the actual HTTP request.
Parameters:
- req: The HTTP request to modify and execute
Returns the HTTP response from the underlying transport and any error encountered.
Example:
transport := &HeaderTransport{
Transport: http.DefaultTransport,
Headers: map[string]string{"User-Agent": "MyApp/1.0"},
}
resp, err := transport.RoundTrip(req)
Source Files