Skip to content
WordPress Maintenance

‘not a valid OPENSSH private key file’ — building a compat layer for seven SSH private-key formats

If you wire SSH into WordPress maintenance automation, you’ll meet this error sooner or later:

SSHException: not a valid OPENSSH private key file

“I configured the key file — why?” is the usual reaction. Tracing several real SSH-connection-test failures, the root issue becomes clear: paramiko alone can’t read SSH private keys outside the OpenSSH format.

In production, hosting providers and key-generation tools produce different formats, and paramiko’s standard loader rejects many of them. Here’s the design of a “seven-format compat loader” we built to handle this.

Far more SSH key formats than you’d guess

“SSH key” usually conjures up -----BEGIN OPENSSH PRIVATE KEY-----, but in practice the keys you receive fall into:

  1. OpenSSH new format (-----BEGIN OPENSSH PRIVATE KEY-----)
  2. PKCS#1 RSA (-----BEGIN RSA PRIVATE KEY-----)
  3. SEC 1 EC (-----BEGIN EC PRIVATE KEY-----)
  4. PKCS#8 plain (-----BEGIN PRIVATE KEY-----)
  5. PKCS#8 encrypted (-----BEGIN ENCRYPTED PRIVATE KEY-----)
  6. Legacy PEM encrypted (-----BEGIN RSA PRIVATE KEY----- + Proc-Type: 4,ENCRYPTED)
  7. PuTTY .ppk (v2 / v3 — common from Windows users)

paramiko.from_private_key_file() handles OpenSSH and PKCS#1, but PKCS#8 and .ppk are out of scope. For instance, Sakura Internet’s control-panel option to “generate and register a key pair” currently produces ECDSA + PKCS#8 — and paramiko’s regex rejects it outright.

The approach — let cryptography pre-read it, then re-serialize as OpenSSH

Extending paramiko directly is hard, so the compat loader takes a detect → normalize → hand off to paramiko approach. We added core/ssh_key_loader.py:

def load_any_ssh_key(path: str, passphrase: str | None = None) -> paramiko.PKey:
    """
    Load one of seven SSH private-key formats and normalize to paramiko.PKey.
    Supported: OpenSSH / PKCS#1 RSA / SEC 1 EC / PKCS#8 plain /
               PKCS#8 encrypted / legacy PEM encrypted / PuTTY .ppk (v2 / v3)
    """
    raw = open(path, "rb").read()
    fmt = _detect_format(raw)
    pem_openssh = _to_openssh_pem(raw, fmt, passphrase)
    return paramiko.RSAKey.from_private_key(io.BytesIO(pem_openssh))

_detect_format() looks at the first bytes, PEM headers, and the PuTTY-specific PuTTY-User-Key-File-2/3: line to identify which of the seven formats it is. After detection, the cryptography library reads the key object and re-serializes it as an OpenSSH-compatible PEM, which then gets handed to paramiko. From paramiko’s perspective, it’s always “the OpenSSH format I know.”

PuTTY .ppk — a hand-rolled parser, no extra dependency

PuTTY’s .ppk is supported by neither paramiko nor cryptography, so it gets a dependency-free, hand-rolled parser:

  • v2: SHA1 + HMAC-SHA1 authentication; base64-encoded public key plus an encrypted private-key section that needs decryption
  • v3: Argon2id + HMAC-SHA256 (a newer KDF); different passphrase handling

The .ppk parser is about 200 lines on its own, but pulling in something like pyppk would add binary size and a separate compatibility surface to maintain. A hand-rolled parser turned out lighter operationally.

Designing the “unknown format” error

When _detect_format() matches none of the seven, the original error was a vague “format unknown” — leaving the user with no idea what to do.

Alongside the seven-format support, the error message itself was rewritten:

Could not identify the format of the key file.
Accepted formats: OpenSSH / PKCS#1 RSA / SEC 1 EC /
                  PKCS#8 / PuTTY .ppk
First bytes detected: <hex dump>
Recommended next step: regenerate an OpenSSH-format key with
  `ssh-keygen -t rsa -f new_key`, then re-register the public key
  on the server.

A consistent pattern: what arrived, what is accepted, and what to do next — three pieces in every failure case. Error messages that only say “something happened” are the biggest source of support tickets.

Takeaway — library constraints can be absorbed in a layer just in front

paramiko’s narrow format support was solved by inserting a classic detect-and-normalize layer in front of it. Seven formats now look like “the same old OpenSSH key” from the app’s side. The change is smaller and the regression tests are simpler than patching paramiko itself would have been.

The error-message pattern — “what arrived, what’s accepted, what to do next” — is something we want to spread well beyond SSH. A library’s constraints disappear from the user’s view if you slip a single absorbing layer in front of it. That’s the lesson worth recording from this round.