🔐 gitswitch

Core Concepts

Understanding these foundational concepts will help you configure gitswitch effectively and understand how it protects your credentials.

Select a subtopic from the sidebar to learn about Git identities, configuration scopes, and key isolation.

Git Identities

A Git identity consists of a name and email address stored in git configuration. These values appear in commit metadata and are used for attribution. gitswitch manages these identities as "accounts" that can include additional SSH and GPG configuration.

Local vs Global Scope

Git configuration exists at three levels: system, global, and local. gitswitch operates at two of these:

• Local scope - Configuration stored in .git/config within a repository. Only affects that repository.
• Global scope - Configuration stored in ~/.gitconfig. Affects all repositories for the user.

Local scope is the default because it prevents accidentally using the wrong identity in a repository you haven't explicitly configured.

Key Isolation

The primary security feature of gitswitch is key isolation. When you switch accounts:

1. Previous account's SSH agent is stopped (if owned by gitswitch)
2. A new SSH agent is started with only the new account's key
3. GPG's GNUPGHOME is pointed to an isolated directory
4. The new account's GPG key is imported into the isolated environment

This ensures that even if you're in the wrong directory or forget which account is active, you can't accidentally use credentials from another account.

SSH Management

gitswitch provides comprehensive SSH key management with isolated agents per account.

Select a subtopic to learn about agent isolation, key configuration, and host aliases.

Isolated SSH Agents

gitswitch runs a separate ssh-agent process for each account. The agent's socket is stored at:

A symlink at ~/.config/gitswitch-ssh/current.sock always points to the active account's socket. This symlink is what gitswitch uses to detect the currently active account.

Key Configuration

SSH keys must be readable by the current user with mode 600. gitswitch supports all key types that your SSH installation supports:

• Ed25519 (recommended)
• RSA (2048-bit minimum, 4096-bit recommended)
• ECDSA
• DSA (deprecated, not recommended)

Host Aliases

For services like GitHub that don't support multiple accounts on the same hostname, use SSH host aliases. Configure these in ~/.ssh/config and reference them in gitswitch with the ssh_host option.

When a host alias is configured, gitswitch will test SSH connectivity during account switch to verify the key is accepted:

GPG Management

gitswitch provides isolated GPG environments to ensure commits are signed with the correct key.

Select a subtopic to learn about GPG isolation, commit signing, and key setup.

GPG Isolation Modes

gitswitch uses isolated GPG environments to prevent signing with the wrong key. When GPG is enabled for an account, gitswitch creates a separate GNUPGHOME:

If XDG_RUNTIME_DIR is not set (common on macOS), it falls back to /tmp/gitswitch-gpg-$UID/.

Commit Signing

When gpg_signing_enabled is true, gitswitch configures git to automatically sign commits:

• Sets user.signingkey to the account's GPG key ID
• Enables commit.gpgsign = true
• Tests signing capability before completing the switch

GPG Key Setup

GPG keys must exist in your system keyring before configuring them in gitswitch. To find your key ID:

Use the 16-character key ID after the algorithm (e.g., ABCD1234EFGH5678).

Workflows

Common workflow patterns for using gitswitch effectively.

Select a subtopic to see configuration examples for different scenarios.

Work/Personal Split

The most common use case is separating work and personal GitHub accounts:

1. Generate separate SSH keys for each account
2. Configure SSH host aliases in ~/.ssh/config
3. Add both accounts to gitswitch with their respective keys
4. Clone work repos using git@github.com-work:org/repo.git
5. Clone personal repos using git@github.com-personal:user/repo.git
6. Switch accounts before working in each repository

Multi-Organization

For developers working across multiple organizations (consulting, open source maintainers):

• Create an account for each organization
• Use descriptive names (e.g., "Acme Corp", "BigCo", "OSS Maintainer")
• Configure GPG signing for organizations that require it
• Use local scope to prevent cross-contamination

Contractor Setup

Contractors often need to access multiple client Git servers with different credentials:

[accounts.1]
name = "John Contractor"
email = "john@contractor.io"
description = "Personal - Default"
preferred_scope = "global"

[accounts.2]
name = "John Doe"
email = "john.doe@client-a.com"
description = "Client A - Finance Corp"
ssh_enabled = true
ssh_key = "~/.ssh/id_ed25519_client_a"
ssh_host = "gitlab.client-a.com"

[accounts.3]
name = "J. Doe"
email = "jdoe@client-b.io"
description = "Client B - Tech Startup"
ssh_enabled = true
ssh_key = "~/.ssh/id_rsa_client_b"
ssh_host = "github.client-b.io"
gpg_enabled = true
gpg_key = "FEDCBA9876543210"
gpg_signing_enabled = true

Security Model

gitswitch is designed with security as a primary concern:

Build-Time Security

• Compiled with stack protection (-fstack-protector-strong)
• Control flow integrity checks enabled
• Full RELRO and NOWEXECSTACK for memory protection
• Address sanitizer available for debug builds
• All compiler warnings treated as errors

Runtime Security

• File permission validation (600 for keys and config)
• Symlink validation to prevent attacks
• Path traversal prevention in config parser
• Bounds-checked string operations throughout
• Secure memory zeroing for sensitive data
• Environment variable isolation
• Atomic file operations for config changes

Isolation Guarantees

• Each SSH agent only has access to its account's key
• GPG operations are confined to isolated GNUPGHOME
• Previous session resources are cleaned up before new session starts
• Agent processes are owned by gitswitch and properly terminated

Session Management

Session Lifecycle

Account switching follows a strict lifecycle to ensure clean transitions:

accounts_switch(ctx, account_identifier)
├── 1. Lookup account by ID/name/email/description
├── 2. Validate account configuration
├── 3. Cleanup previous session
│   ├── Stop owned SSH agents
│   ├── Restore original GNUPGHOME
│   └── Clear session state
├── 4. Configure git identity
│   ├── Set user.name
│   ├── Set user.email
│   └── Verify configuration applied
├── 5. Setup SSH isolation (if enabled)
│   ├── Create isolated agent
│   ├── Load account key
│   ├── Update current.sock symlink
│   └── Test connectivity (if host configured)
├── 6. Setup GPG isolation (if enabled)
│   ├── Create isolated GNUPGHOME
│   ├── Import key from system keyring
│   ├── Configure signing key
│   └── Test signing capability
└── 7. Update session state

Resource Cleanup

Cleanup happens at the start of a new switch, not at the end. This allows SSH agents to persist across commands while ensuring no resource leaks when switching.

• Only agents owned by gitswitch (tracked by PID) are stopped
• System SSH agents are never touched
• GPG isolation directories are ephemeral (in XDG_RUNTIME_DIR)
• Socket symlinks are atomic-replaced, never deleted

SSH Isolation

Agent Architecture

gitswitch operates in SSH_AGENT_ISOLATED mode, creating dedicated agents per account. The architecture ensures complete separation:

typedef struct {
    ssh_agent_mode_t mode;        // ISOLATED, SYSTEM, or NONE
    char agent_socket_path[4096]; // Path to agent socket
    pid_t agent_pid;              // Agent process ID
    bool agent_owned;             // Did we start this agent?
} ssh_config_t;

Socket Management

SSH agent sockets follow a predictable naming scheme:

~/.config/gitswitch-ssh/
├── ssh-agent.john-work.sock      # Account 1's agent
├── ssh-agent.johnny-personal.sock # Account 2's agent
└── current.sock -> ssh-agent.john-work.sock  # Symlink to active

The current.sock symlink serves two purposes:

• Provides stable path for SSH_AUTH_SOCK in shell config
• Allows gitswitch to detect current account from socket name

Key Loading

Keys are loaded into the agent using ssh-add with the following process:

1. Start new ssh-agent, capturing SSH_AUTH_SOCK and SSH_AGENT_PID
2. Validate key file exists and has mode 600
3. Run ssh-add {key_path} with new agent's socket
4. If host alias configured, test with ssh -T git@{host}
5. Update current.sock symlink atomically

GPG Isolation

GNUPGHOME Isolation

GPG uses the GNUPGHOME environment variable to locate its keyring and configuration. gitswitch creates isolated directories for each account:

$XDG_RUNTIME_DIR/gitswitch-gpg/
├── john-work/
│   ├── pubring.kbx
│   ├── trustdb.gpg
│   └── private-keys-v1.d/
└── johnny-personal/
    ├── pubring.kbx
    ├── trustdb.gpg
    └── private-keys-v1.d/

The runtime directory is chosen because:

• tmpfs/ramfs storage (keys never written to disk)
• Automatically cleaned on logout/reboot
• User-private with correct permissions

Key Import

Keys are imported from the system keyring to the isolated environment on each switch:

# Export from system keyring
gpg --export-secret-keys {key_id} | \
  GNUPGHOME={isolated_dir} gpg --import

# Trust the imported key
GNUPGHOME={isolated_dir} gpg --edit-key {key_id} trust quit

Signing Flow

When GPG signing is enabled, gitswitch configures git and verifies the setup:

1. Set GNUPGHOME to isolated directory
2. Run git config user.signingkey {key_id}
3. Run git config commit.gpgsign true
4. Test signing with echo test | gpg --sign
5. Report success or failure to user

Data Structures

The core data structures are defined in gitswitch.h:

account_t

typedef struct {
    uint32_t id;                    // Unique account identifier
    char name[256];                 // Git user.name
    char email[320];                // Git user.email (RFC 5321 max)
    char description[512];          // Human-readable description
    git_scope_t preferred_scope;    // LOCAL or GLOBAL

    // SSH configuration
    bool ssh_enabled;
    char ssh_key_path[4096];        // PATH_MAX
    char ssh_host_alias[256];       // Optional host for testing

    // GPG configuration
    bool gpg_enabled;
    bool gpg_signing_enabled;
    char gpg_key_id[64];            // 16-char hex + buffer
} account_t;

gitswitch_ctx_t

typedef struct {
    config_t config;                // Global settings
    account_t accounts[64];         // Account storage (max 64)
    size_t account_count;           // Number of configured accounts
    account_t *current_account;     // Pointer to active account

    // Session state
    ssh_config_t ssh;               // SSH agent state
    gpg_config_t gpg;               // GPG isolation state

    // Runtime flags
    bool verbose;
    bool dry_run;
    bool color_output;
} gitswitch_ctx_t;

active_session_t

typedef struct {
    uint32_t account_id;            // Currently active account
    pid_t ssh_agent_pid;            // PID of owned SSH agent
    char ssh_socket_path[4096];     // Path to agent socket
    char original_gnupghome[4096];  // GNUPGHOME before switch
    char isolated_gnupghome[4096];  // Current isolated GNUPGHOME
} active_session_t;

Security Measures

Input Validation

The TOML parser includes extensive security checks:

• UTF-8 validation on all string values
• File size limit (64KB) prevents DoS
• Path traversal prevention (rejects ../)
• TOML injection pattern detection
• Email format validation (RFC 5322)
• GPG key ID format validation (16-char hex)

Safe String Operations

// All string operations use safe wrappers
bool safe_strncpy(char *dest, size_t dest_size,
                  const char *src, size_t max_len);
bool safe_strncat(char *dest, size_t dest_size,
                  const char *src, size_t max_len);
bool safe_snprintf(char *dest, size_t dest_size,
                   const char *fmt, ...);

// Memory is zeroed for sensitive data
void secure_zero(void *ptr, size_t len);

Compile-Time Hardening

The Makefile includes comprehensive security flags:

SECURITY_FLAGS = -fstack-protector-strong \
                 -fcf-protection \
                 -D_FORTIFY_SOURCE=2 \
                 -Wformat -Wformat-security \
                 -fPIE

LDFLAGS = -Wl,-z,relro,-z,now \
          -Wl,-z,noexecstack \
          -pie