"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 fileEnter fullscreen modeExit fullscreen mode"I configured the key. . .
If you wire SSH into WordPress maintenance automation, you'll meet this error sooner or later:SSHException: not a valid OPENSSH private key fileEnter fullscreen modeExit fullscreen mode"I configured the key file — why?" is the usual reaction. Tracing several real SSH-connection-test failures, the root issue becomes clear:paramikoalone 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:OpenSSH new format(-----BEGIN OPENSSH PRIVATE KEY-----)PKCS#1 RSA(-----BEGIN RSA PRIVATE KEY-----)SEC 1 EC(-----BEGIN EC PRIVATE KEY-----)PKCS#8 plain(-----BEGIN PRIVATE KEY-----)PKCS#8 encrypted(-----BEGIN ENCRYPTED PRIVATE KEY-----)Legacy PEM encrypted(-----BEGIN RSA PRIVATE KEY-----+Proc-Type: 4,ENCRYPTED)PuTTY . ppk(v2 / v3 — common from Windows users)paramiko. from_private_key_file()handles OpenSSH and PKCS#1, butPKCS#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 — letcryptographypre-read it, then re-serialize as OpenSSHExtending paramiko directly is hard, so the compat loader takes adetect → normalize → hand off to paramikoapproach. We addedcore/ssh_key_loader. py:defload_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)returnparamiko. RSAKey. from_private_key(io. BytesIO(pem_openssh))Enter fullscreen modeExit fullscreen mode_detect_format()looks at the first bytes, PEM headers, and the PuTTY-specificPuTTY-User-Key-File-2/3:line to identify which of the seven formats it is. After detection, thecryptographylibrary 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 dependencyPuTTY's. ppkis supported by neither paramiko nor cryptography, so it gets adependency-free, hand-rolled parser:v2: SHA1 + HMAC-SHA1 authentication; base64-encoded public key plus an encrypted private-key section that needs decryptionv3: Argon2id + HMAC-SHA256 (a newer KDF); different passphrase handlingThe. ppkparser is about 200 lines on its own, but pulling in something likepyppkwould add binary size and a separate compatibility surface to maintain. A hand-rolled parser turned out lighter operationally. Designing the "unknown format" errorWhen_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: 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. Enter fullscreen modeExit fullscreen modeA 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 frontparamiko's narrow format support was solved by inserting a classicdetect-and-normalize layer in frontof 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.