Authentication

macSCP authenticates over SSH with a password, a key from a file, or your SSH agent. S3 and WebDAV sessions authenticate with credentials (access key/secret key, or user name and password with Basic, Digest, or TLS authentication).

Passwords

A saved session stores its password in the macOS Keychain — never in a file. The CLI looks it up in a defined order; see Command line.

SSH keys

macSCP authenticates with:

ed25519, RSA, and ECDSA keys, with or without a passphrase.
Keys from a file or from your SSH agent.
PEM-format private keys — see below.

PEM private keys

A private key in PEM format connects the same way an OpenSSH-format key does, in the app and in the command-line tool:

File starts with	Key types read
`-----BEGIN RSA PRIVATE KEY-----` (PKCS#1)	RSA
`-----BEGIN EC PRIVATE KEY-----` (SEC1)	ECDSA on P-256, P-384, P-521
`-----BEGIN PRIVATE KEY-----` (PKCS#8)	RSA, ECDSA (the same three curves), ed25519
`-----BEGIN ENCRYPTED PRIVATE KEY-----` (PKCS#8, encrypted)	the same as above

Passphrase-protected PEM keys are read when they use AES-128, AES-192 or AES-256 encryption, either the older OpenSSL header style or the PKCS#8 password scheme. A wrong passphrase is reported as a wrong passphrase, not as a broken file.

When a PEM key cannot be read

Some PEM files use a feature macSCP does not read — DES or 3DES encryption, the scrypt password scheme, a DSA key, or a PuTTY key file. The failed connection then says what stops it, for example “its DES-EDE3-CBC encryption is not supported”, and offers two buttons:

Copy command — copies an ssh-keygen -p -f '<your key file>' command. Run it in a terminal and it rewrites your original file in place, in OpenSSH format.
Convert key… — opens the key manager’s Import SSH Key sheet for that file. macSCP converts a copy and leaves your original file untouched. The copy is stored in macSCP’s own key folder, readable by you alone, and keeps the passphrase it had. A passphrase you type in the sheet is saved in the Keychain with the new key.

After Convert key… finishes, macSCP points the session at the converted copy and connects again. For a session that uses a login set, it asks first — see below. For a connection that was never saved, the converted key goes into the form, and you connect yourself.

You can also load the key into your SSH agent and choose the agent as the login.

The key manager

Sessions → SSH Keys… opens the key manager. Generate… creates a new key; Import… sits in the More actions menu (the ⋯ button).

Importing a PEM file converts it to OpenSSH format on the way in, so every key the manager stores is in the same format and can be exported.
Generating, reading or converting a key stops after 10 minutes and says so — “Generating the key took too long and was stopped. Nothing was saved.” — instead of waiting forever. Only very heavily protected keys come near that limit.

A login set is a saved login — user name and key or password — that several sessions share. Manage them under Sessions → Logins… (⇧⌘L); in the connection form, choose Login set instead of Manual.

When you convert a PEM key for a session that uses a login set, macSCP asks Update the login set ”…”? and tells you how many sessions use that set, directly or as their jump host:

Button	What it does
Update login set	Points the login set at the converted key, for every session that uses it, and connects again. If the set cannot be saved, nothing else changes.
This attempt only	Changes nothing that is saved. The converted key goes into this tab’s form, and you connect from there.

The count is taken at the moment the question appears, so a session added in the meantime is included.

Managed key passphrases

A key the key manager stores keeps its passphrase in the Keychain. macSCP now uses that passphrase wherever a key needs one and no other passphrase is saved:

in the command-line tool, as the last place it looks (see Secrets),
when you export sessions: a login whose key’s passphrase is already in the Keychain no longer counts under “Exported without password”. The export file still does not contain it.

If macSCP’s list of managed keys (managed_keys.json) cannot be read, the connection says so — “The SSH key is encrypted, and its saved passphrase could not be looked up…” — rather than reporting a missing passphrase. Enter the passphrase by hand, or check the file.

Correcting or changing a key’s passphrase

The key manager’s context menu — right-click a key in Sessions → SSH Keys… — offers two actions for a key’s passphrase. They do different things, and which one you want depends on whether the key file itself is right:

Action	Use it when	What it touches
Correct the stored passphrase…	You know the passphrase that opens the key, but macSCP asks for it every time, or was saved with the wrong one.	Only what macSCP remembers. The key file is not changed.
Change the key’s passphrase…	You want the key itself protected by a different passphrase — for example because the old one was shared, or because the key has none yet.	The key file is rewritten, and macSCP’s saved passphrase follows it.

Correct the stored passphrase… takes one field. macSCP tries the passphrase against the key before saving it: a passphrase that does not open the key is refused — “That passphrase doesn’t open this key. Nothing was saved.” — so a guess can never overwrite a passphrase that was right. Nothing on disk changes either way. The action is greyed out for a key that has no passphrase, because there is nothing to remember; and if it turns out that the key file is not protected at all, it refuses rather than saving something that would never be used.

Change the key’s passphrase… asks for the current passphrase, the new one, and the new one again. The current passphrase is checked first, so a typo is reported as a typo and the key file is left alone. A key that has no passphrase yet can be given one: leave the current passphrase empty. An empty new passphrase is not accepted — this action protects a key, it does not unprotect one.

Before it rewrites anything, macSCP copies the key file aside, and puts the copy back if the rewrite is cancelled, stopped, or fails. Cancelling — with the button, with Escape, or by closing the window — therefore leaves the key exactly as it was. The copy is deleted as soon as the rewrite succeeds.

If a rewrite is stopped or goes wrong, macSCP says so and asks you to check: “The key tool took too long and was stopped. Check that the current passphrase still opens this key before trying again.” That wording is deliberate. Putting the copy back is the one step macSCP cannot promise — a disk that refuses to rename it will defeat it — so it tells you to look rather than telling you nothing happened. If you ever find neither passphrase opening a key, look in macSCP’s key folder for a file whose name begins with .macscp-rollback-: that is the copy, and it is the key as it was before.

If the key file is rewritten but macSCP cannot finish saving the new passphrase, it says so: “The key file now uses the new passphrase — from now on only that opens it. macSCP couldn’t finish saving it, so it may be asked for on the next connection.” The new passphrase is the real one from that moment; type it at the next connection, or use Correct the stored passphrase… to save it again.

Both actions apply only to keys the key manager itself holds. A key elsewhere on disk is changed with ssh-keygen -p -f '<your key file>' in a terminal.

Jump hosts

A jump host that logs in with a key the key manager stores uses that key’s saved passphrase, in preference to any passphrase saved for the jump host itself. The jump host’s own saved passphrase is used only when the key has none — because it is not one of the key manager’s keys, because it is not passphrase-protected, because no passphrase was saved with it, or because the list of managed keys could not be read at all — on a jump host that last case falls back to the jump host’s own passphrase without a word while connecting, where the connection’s own key says so in words. Check connection does name it for the jump host: see Sessions behind a jump host.

One passphrase therefore lives in one place, and a passphrase saved for a jump host before the key was replaced can no longer keep that jump host from connecting.

A passphrase you type into a jump host’s passphrase field is kept — it used to be discarded without a word whenever the key had a passphrase of its own. It is used when the key has none. While the key has one, the key’s passphrase wins; to change what macSCP has saved for the key itself, use one of the two actions in Correcting or changing a key’s passphrase.

Leaving the field as macSCP filled it in saves no second copy of the key’s passphrase, and changing a jump host’s key clears a passphrase macSCP filled in rather than carrying it to the new key. A passphrase you typed yourself is yours: it stays in the field across a key change, and is then saved for the key the jump host names. Clear it yourself if that is not what you want.

SSH agent

Choose agent authentication and macSCP uses the identities already loaded in your local agent — the private key never leaves it.

`~/.ssh/config`

Entries from ~/.ssh/config appear automatically in the connection form, so you can start from a host block you already maintain.

Host keys

Host keys are pinned per connection:

The first connect shows the fingerprint and asks you to confirm it.
An unknown key is refused unless you explicitly consent.
A changed key is a hard stop — the user decider is never consulted, and no setting or CLI flag can wave it through. Verify the change out of band, then update the entry in Sessions → Known Hosts (⌘⇧K).

The host-key question is never hidden: while it waits for your answer, the tab shows it on the connection form, even when a session is selected in the sidebar.