ansiblings/packages/cubes-core/cubes/ssh/keygen/README.md

ssh-keygen

Generate SSH key for a given user

Purpose

This cube generates a new SSH key pair for a specified user, which can be used for secure, passwordless authentication to remote servers and services like GitHub, GitLab, or other SSH-accessible systems.

What are SSH Keys?

SSH keys provide a more secure and convenient way to authenticate compared to passwords:

• Public key: Shared with servers/services you want to access (like GitHub)
• Private key: Kept secret on your local machine, never shared
• Passphrase-free: This cube generates keys without a passphrase for automation
• Algorithm support: RSA (traditional) or Ed25519 (modern, recommended)

What This Cube Does

1. Creates the .ssh directory with proper permissions (700)
2. Generates an SSH key pair using the specified algorithm
3. Saves the keys as id_{SUFFIX} and id_{SUFFIX}.pub
4. Logs the public key to the console for easy copying

Configuration

Parameters

• SUFFIX (string, default: 'ed25519')

  • Suffix for keyname (e.g., github → id_github.pub)
  • Helps identify the purpose of the key

• EMAIL (string, default: 'undefined@bitsquare.dev')

  • Email address to associate with the SSH key
  • Used as a comment in the public key

• ALGORITHM (enum: 'rsa' | 'ed25519', default: 'ed25519')

  • SSH key algorithm type
  • Ed25519: Modern, faster, more secure (recommended)
  • RSA: Traditional, widely supported

• USER (string, default: 'vagrant')

  • Username for which to generate the SSH key
  • Inherited from user-add dependency

Dependencies

• user-add - Creates the user account first

Post-Installation

After the key is generated:

1. The public key will be logged to the console

2. Copy the public key and add it to the target service:

   • GitHub: Settings → SSH and GPG keys → New SSH key
   • GitLab: Preferences → SSH Keys
   • Remote server: Add to ~/.ssh/authorized_keys

3. SSH config is automatically set up for the key

Key Locations

• Private key: /home/{USER}/.ssh/id_{SUFFIX}
• Public key: /home/{USER}/.ssh/id_{SUFFIX}.pub

Algorithm Comparison

Ed25519 (Recommended):

• Smaller keys (256-bit)
• Faster generation and verification
• More secure against certain attacks
• Not supported on very old systems

RSA:

• Larger keys (2048-4096 bit)
• Universally supported
• Slower than Ed25519
• Well-tested and trusted

Example Usage

Generate a key for GitHub access:

exec('ssh-keygen', {
  SUFFIX: 'github',
  EMAIL: 'myemail@example.com',
  ALGORITHM: 'ed25519',
  USER: 'myuser'
})

This creates id_github and id_github.pub in /home/myuser/.ssh/.