Understanding Vault SSH certificate authentication

This guide demonstrates how to configure HashiCorp Vault's SSH Secret Engine to sign SSH certificates using ED25519 keys instead of RSA, specifically for z/OS Unix System Services (USS) environments.

What you'll learn

This guide will walk you through:

  1. Setting up Vault as an SSH Certificate Authority (CA) - Configure Vault to sign SSH certificates.
  2. Creating certificate signing roles - Define who can get certificates and for how long.
  3. Signing SSH certificates - Generate short-lived certificates for SSH access.
  4. Configuring z/OS USS - Set up the mainframe to trust Vault-signed certificates.
  5. Connecting securely - Use signed certificates to access z/OS USS without password prompts.

How it works

┌─────────────────┐         ┌──────────────────┐          ┌─────────────────┐
│   User/Client   │         │   Vault Server   │          │   z/OS USS      │
│                 │         │   (SSH CA)       │          │   SSH Server    │
└────────┬────────┘         └────────┬─────────┘          └────────┬────────┘
         │                           │                             │
         │ 1. Request certificate    │                             │
         │ (with public key)         │                             │
         ├──────────────────────────>│                             │
         │                           │                             │
         │ 2. Return signed cert     │                             │
         │ (valid for 10 minutes)    │                             │
         │<──────────────────────────┤                             │
         │                           │                             │
         │ 3. SSH with certificate   │                             │
         ├────────────────────────────────────────────────────────>│
         │                           │                             │
         │                           │ 4. Verify cert signature    │
         │                           │    using trusted CA key     │
         │                           │<────────────────────────────┤
         │                           │                             │
         │ 5. Access granted         │                             │
         │<────────────────────────────────────────────────────────┤

Key Concepts:

  • Certificate Authority (CA): Vault acts as a trusted authority that signs SSH certificates.
  • Signed Certificate: A time-limited credential that proves your identity to the SSH server.
  • ED25519: A modern, fast, and secure cryptographic algorithm for SSH keys.
  • z/OS USS: Unix System Services on IBM z/OS mainframe, providing a Unix-like environment.

Overview

The SSH Secret Engine allows Vault to act as a Certificate Authority (CA) for SSH certificates. This approach provides:

  • Centralized SSH key management across mainframe and distributed systems.
  • Short-lived certificates with automatic expiration.
  • Audit trail of SSH access to z/OS USS.
  • No need to distribute public keys to z/OS target servers.
  • Compliance with enterprise security policies for mainframe access.

z/OS USS considerations

z/OS Unix System Services (USS) provides a Unix-like environment on IBM z/OS mainframes, allowing you to run Unix applications and use familiar Unix commands alongside traditional mainframe workloads.

Important z/OS Terminology:

  • RACF/ACF2/Top Secret: Mainframe security systems that control user authentication and authorization (similar to LDAP/Active Directory on distributed systems).
  • EBCDIC vs ASCII: z/OS uses EBCDIC character encoding by default, while Unix/Linux uses ASCII. SSH configuration files must be in ASCII format.
  • HFS/zFS: Unix-style file systems on z/OS (Hierarchical File System / z/OS File System).
  • USS: Unix System Services - the Unix environment within z/OS.
  • Started Task: A z/OS job that runs continuously (like a Unix daemon/service).

When implementing SSH certificate authentication on z/OS USS:

  • OpenSSH on z/OS USS supports certificate-based authentication.
  • ED25519 keys are supported on z/OS V2R3 and later with OpenSSH 7.4+.
  • File permissions and ownership are critical in USS environments.
  • RACF/ACF2/Top Secret integration handles user authentication (the certificate validates the SSH connection).
  • Always verify EBCDIC/ASCII encoding for configuration files after transfer.

Security considerations

ED25519 vs RSA

Why ED25519?

  • Faster: Significantly faster key generation and signing operations.
  • Smaller keys: 256-bit keys provide equivalent security to 3072-bit RSA keys.
  • More secure: Resistant to timing attacks and other side-channel attacks.
  • Modern standard: Recommended by security experts and widely supported.

Certificate TTL

The example uses a 10-minute TTL (ttl="10m0s"). Consider:

  • Short TTL: More secure, requires frequent re-signing.
  • Longer TTL: More convenient, but increases risk if compromised.
  • Best practice: Use the shortest TTL that meets operational needs.

Token security

The example shows a Vault token placeholder in the curl command. In production:

  • Use Vault authentication methods (LDAP, OIDC, AppRole, etc.).
  • Never hardcode tokens in scripts.
  • Use environment variables or secure secret management.
  • Implement token rotation policies.

Additional resources

Vault CLI commands quick reference


# List all roles
vault list ssh-client-signer/roles

# Read role configuration
vault read ssh-client-signer/roles/sshrole

# Delete a role
vault delete ssh-client-signer/roles/sshrole

# Disable the SSH secret engine
vault secrets disable ssh-client-signer

Example: multiple valid principals


vault write ssh-client-signer/sign/sshrole \
  public_key=@$HOME/.ssh/id_ed25519.pub \
  valid_principals="<username1>,<username2>,<username3>"

This allows the certificate to be used for multiple usernames on the target server.

Quick reference: complete example workflow

Here's a complete end-to-end example with placeholder values. Replace myuser and server.example.com with your actual values:

  1. Enable SSH secret engine in Vault.
  2. Generate CA signing key.
  3. Create a role with certificate parameters.
  4. Sign your SSH public key.
  5. Use the signed certificate to connect.

# 1. Enable SSH secret engine
vault secrets enable -path=ssh-client-signer ssh

# 2. Configure CA with ED25519
vault write ssh-client-signer/config/ca \
  generate_signing_key=true \
  key_type=ed25519

# 3. Create role
vault write ssh-client-signer/roles/sshrole \
  allow_user_certificates=true \
  allowed_users="myuser" \
  key_type="ca" \
  default_user="myuser" \
  ttl="10m0s"

# 4. Sign public key
vault write -field=signed_key \
  ssh-client-signer/sign/sshrole \
  public_key=@$HOME/.ssh/id_ed25519.pub \
  valid_principals="myuser" > signed-key

# 5. Set permissions
chmod 600 signed-key

# 6. Connect to server
ssh -o CertificateFile=signed-key myuser@server.example.com

What happens next?

  • The certificate is valid for 10 minutes (as configured in the role).
  • After expiration, request a new certificate by repeating step 4.
  • No password prompts - the certificate authenticates you automatically.

References

Official documentation

SSH and cryptography

Security best practices

Vault authentication and authorization

Advanced topics

Integration examples

Community resources