Client Certificates¶

This guide explains how to create and manage client certificates for authenticated Gemini sites.

Understanding Client Certificates¶

Some Gemini sites use client certificates for:

User identification
Access control
Persistent sessions

When a site requests a certificate, Astronomo prompts you to select or create one.

Creating a Certificate¶

When Prompted¶

Visit a site that requests a certificate
Astronomo shows a certificate selection dialog
Choose "Create New Identity"
Enter a name for this identity (e.g., "My Gemini Identity")
The certificate is generated and saved

From Settings¶

Press Ctrl+, to open Settings
Navigate to the Certificates section
Select "Create New Identity"
Enter identity details

Importing from Lagrange¶

If you've been using the Lagrange Gemini browser, you can import your existing identities into Astronomo.

How to Import¶

Press Ctrl+, to open Settings
Navigate to the Certificates section
Click "Import from Lagrange"
The modal shows all discovered identities from Lagrange
Set a name for each identity you want to import
Click "Import"

What Gets Imported¶

Certificate files (.crt)
Private key files (.key)
You set custom names during import

What Doesn't Get Imported¶

URL associations (Lagrange stores these in a proprietary binary format)
You'll need to manually associate URLs with imported identities

Supported Lagrange Installations¶

Astronomo automatically detects Lagrange's identity storage in these locations:

Platform	Standard Path	Flatpak Path
Linux	`~/.config/lagrange/idents/`	`~/.var/app/fi.skyjake.Lagrange/config/lagrange/idents/`
macOS	`~/Library/Application Support/fi.skyjake.Lagrange/idents/`	-
Windows	`%APPDATA%/fi.skyjake.Lagrange/idents/`	-

Duplicate Detection¶

If you try to import an identity that already exists in Astronomo (detected by certificate fingerprint), it will be marked as "already imported" and skipped automatically.

Selecting a Certificate¶

Proactive Selection (Session-Based)¶

When navigating to a site where you have one or more identities with matching URL prefixes:

A dialog automatically appears before the request is made
Shows all matching identities plus "Continue without identity" option
Select an identity or browse anonymously
Your choice is remembered for the current session (until you quit Astronomo)

This allows you to choose which identity to use when you have multiple options, without permanently associating an identity with the site.

Server-Requested Selection (Status 60)¶

When a site explicitly requests a certificate:

A dialog shows your available identities
Select the one to use for this site
Optionally check "Remember for this host" to permanently associate the identity
Astronomo also remembers your choice for the current session

Managing Identities¶

Viewing Identities¶

Open Settings (Ctrl+,)
Navigate to Certificates section
View list of all identities

Identity Details¶

Each identity includes:

Name (your label for it)
Creation date
Associated hosts (sites using this identity)

Deleting Identities¶

Warning

Deleting an identity removes the certificate permanently. Sites using it will no longer recognize you.

Open Settings
Navigate to Certificates
Select the identity to delete
Confirm deletion

Host Associations¶

Session Associations (Temporary)¶

When you select an identity via the proactive selection dialog:

The choice is stored in memory for the current session
Applies to the host (e.g., gemini://example.com/)
Lost when you quit Astronomo
Use this when you want to temporarily use a specific identity

Persistent Associations (Permanent)¶

When you check "Remember for this host" in the status 60 dialog:

The URL prefix is added to the identity's stored associations
Saved to disk in ~/.config/astronomo/identities.toml
Persists across sessions
Triggers the proactive selection dialog on future visits (if multiple identities match)

Changing Association¶

To use a different identity for a site:

For session associations: - Simply quit and restart Astronomo, then select a different identity

For persistent associations: 1. Open Settings (Ctrl+,) 2. Navigate to Certificates 3. Select the identity and choose "Manage URLs" 4. Remove the URL association 5. Visit the site again and select a different identity

Certificate Storage¶

Certificates are stored in ~/.config/astronomo/:

~/.config/astronomo/
├── identities.toml           # Metadata and host mappings
└── certificates/
    ├── {uuid}.pem            # Certificate file
    └── {uuid}.key            # Private key file

Security Note

Private key files contain sensitive data. Ensure appropriate file permissions and backup securely.

Backup and Restore¶

Backup¶

# Backup identity metadata and certificates
cp ~/.config/astronomo/identities.toml ~/astronomo-backup/
cp -r ~/.config/astronomo/certificates ~/astronomo-backup/

Restore¶

cp ~/astronomo-backup/identities.toml ~/.config/astronomo/
cp -r ~/astronomo-backup/certificates ~/.config/astronomo/

Troubleshooting¶

Certificate Not Accepted¶

The site may require a specific certificate format
Try creating a new identity specifically for that site
Check if the site has specific requirements in their documentation

Lost Identity¶

If you've lost access to an identity:

Create a new identity
Sites will see you as a new user
You may need to re-register on sites that require identification

Permission Errors¶

Ensure proper file permissions:

chmod 700 ~/.config/astronomo/certificates
chmod 600 ~/.config/astronomo/certificates/*.key

Best Practices¶

Use descriptive names - Label identities by purpose or site
One identity per context - Separate personal/work identities
Regular backups - Certificate loss means losing access
Secure storage - Protect the identities directory