ui_pageant » Revisions »
Differences
This shows you the differences between the selected revisions of the page.
| ui_pageant 2016-01-21 | ui_pageant 2024-09-25 (current) | ||
| Line 3: | Line 3: | ||
| ===== Obtaining and Starting Pageant ===== | ===== Obtaining and Starting Pageant ===== | ||
| - | Pageant is included in [[installation|WinSCP installation package]]. You can also download it separately from [[&download|WinSCP download page]]. | + | Pageant is included in [[ui_installer_selectcomponents|WinSCP installation package]]. You can also download it separately from [[&downloads#putty_additional|WinSCP download page]]. |
| - | Pageant originates from PuTTY and is also part of PuTTY installation package. It does not matter if you use Pageant from WinSCP or PuTTY installation package; they are identical. ((The latest versions of WinSCP are compatible with Pageant 0.61 and later.)) | + | Pageant originates from PuTTY and is also part of PuTTY installation package. It does not matter if you use Pageant from WinSCP or PuTTY installation package; they are identical. |
| To start Pageant, go to //Tools > Pageant// on [[ui_login|Login dialog]]. | To start Pageant, go to //Tools > Pageant// on [[ui_login|Login dialog]]. | ||
| Line 12: | Line 12: | ||
| Before you run Pageant, you need to have a [[public_key#private|private key]] in ''.ppk'' format. | Before you run Pageant, you need to have a [[public_key#private|private key]] in ''.ppk'' format. | ||
| - | When you run Pageant, it will put an icon of a computer wearing a hat into the System tray. It will then sit and do nothing, until you load a private key into it. | + | When you run Pageant, it will put an icon of a computer wearing a hat into the System tray. It will then sit and do nothing, until you load a private key into it. (You may need to use Windows' //Show hidden icons// arrow to see the Pageant icon.) |
| &screenshotpict(pageant_tray) | &screenshotpict(pageant_tray) | ||
| Line 29: | Line 29: | ||
| When you want to shut down Pageant, click the right button on the Pageant icon in the System tray, and select //Exit// from the menu. Closing the Pageant main window does not shut down Pageant. | When you want to shut down Pageant, click the right button on the Pageant icon in the System tray, and select //Exit// from the menu. Closing the Pageant main window does not shut down Pageant. | ||
| + | |||
| + | If you want Pageant to stay running but forget all the keys it has acquired, select //Remove All Keys// from the System tray menu. | ||
| ===== The Pageant Main Window ===== | ===== The Pageant Main Window ===== | ||
| Line 36: | Line 38: | ||
| - | ==== The Key List Box ==== | + | ==== [[list]] The Key List Box ==== |
| The large list box in the Pageant main window lists the private keys that are currently loaded into Pageant. The list might look something like this: | The large list box in the Pageant main window lists the private keys that are currently loaded into Pageant. The list might look something like this: | ||
| <code> | <code> | ||
| - | ssh-dsa 2048 22:c3:68:3b:09:41:36:c3:39:83:91:ae:71:b2:0f:04 k1 | + | Ed25519 ···SHA256:TddlQk20DVs4LRcAsIfDN9pInKpY06D+h4kSHwWAj4w |
| - | ssh-rsa 2048 74:63:08:82:95:75:e1:7c:33:31:bb:cb:00:c0:89:8b k2 | + | RSA 2048 ·SHA256:8DFtyHm3kQihgy52nzX96qMcEVOq7/yJmmwQQhBWYFg |
| </code> | </code> | ||
| For each key, the list box will tell you: | For each key, the list box will tell you: | ||
| - | * The type of the key. Currently, this can be ''ssh-rsa'' (an RSA key for use with the SSH-2 protocol), ''ssh-dss'' (a DSA key for use with the %%SSH-2%% protocol), ''ecdsa-sha2-*'' (an ECDSA key for use with the %%SSH-2%% protocol), or ''ssh-ed25519'' (an Ed25519 key for use with the %%SSH-2%% protocol) or ''ssh1'' (an RSA key for use with the SSH-1 protocol). | + | * The type of the key. Currently, this can be ''RSA'', ''DSA'', ''NIST'' (an ECDSA key), ''Ed25519'', ''Ed448'', or ''SSH-1'' (an RSA key for use with the deprecated SSH-1 protocol, not supported by WinSCP). (If the key has an associated certificate, this is shown here with a ''cert'' suffix.) |
| - | * The size (in bits) of the key. | + | * The size (in bits) of the key, for key types that come in different sizes. (For ECDSA NIST keys, this is indicated as ''p256'' or ''p384'' or ''p521''.) |
| - | * The fingerprint for the public key. This should be the same fingerprint given by [[ui_puttygen|PuTTYgen]], and also the same fingerprint shown by remote utilities such as ''ssh-keygen'' when applied to your ''authorized_keys'' file. | + | * The fingerprint for the public key. This should be the same fingerprint given by [[ui_puttygen|PuTTYgen]], and also the same fingerprint shown by remote utilities such as ''ssh-keygen'' when applied to your ''authorized_keys'' file. \\ By default this is shown in the SHA-256 format. You can change to the older MD5 format (which looks like ''aa:bb:cc:...'') with the //Fingerprint type// drop-down, but bear in mind that this format is less secure and should be avoided for comparison purposes where possible. \\ If some of the keys loaded into Pageant have certificates attached, then Pageant will default to showing the fingerprint of the underlying key. This way, a certified and uncertified version of the same key will have the same fingerprint, so you can see that they match. You can instead use the //Fingerprint type// drop-down to ask for a different fingerprint to be shown for certified keys, which includes the certificate as part of the fingerprinted data. That way you can tell two certificates apart. |
| * The comment attached to the key. | * The comment attached to the key. | ||
| + | * The state of [[#deferred_decryption|deferred decryption]], if enabled for this key. | ||
| ==== The Add Key Button ==== | ==== The Add Key Button ==== | ||
| Line 74: | Line 77: | ||
| <code> | <code> | ||
| - | "C:\Program Files\WinSCP\PuTTY\pageant.exe" d:\main.ppk d:\secondary.ppk | + | "C:\Program Files (x86)\WinSCP\PuTTY\pageant.exe" d:\main.ppk d:\secondary.ppk |
| </code> | </code> | ||
| Line 80: | Line 83: | ||
| If Pageant is already running, this syntax loads keys into the existing Pageant. | If Pageant is already running, this syntax loads keys into the existing Pageant. | ||
| + | |||
| + | You can specify the ''%%--encrypted%%'' option to [[#deferred_decryption|defer decryption]] of these keys. | ||
| ==== Making Pageant Run Another Program ==== | ==== Making Pageant Run Another Program ==== | ||
| Line 87: | Line 92: | ||
| <code> | <code> | ||
| - | "C:\Program Files\WinSCP\PuTTY\pageant.exe" d:\main.ppk -c C:\PuTTY\putty.exe | + | "C:\Program Files (x86)\WinSCP\PuTTY\pageant.exe" d:\main.ppk -c "C:\Program Files (x86)\WinSCP\WinSCP.exe" |
| </code> | </code> | ||
| + | |||
| + | ==== [[openssh]] Integrating with Windows OpenSSH ==== | ||
| + | |||
| + | Windows's own port of OpenSSH uses the same mechanism as Pageant to talk to its SSH agent (Windows named pipes). This means that Windows OpenSSH can talk directly to Pageant, if it knows where to find Pageant's named pipe. | ||
| + | |||
| + | When Pageant starts up, it can optionally write out a file containing an OpenSSH configuration directive that tells the Windows ''ssh.exe'' where to find Pageant. If you include this file from your Windows SSH configuration, then ''ssh.exe'' should automatically use Pageant as its agent, so that you can keep your keys in one place and have both SSH clients able to use them. | ||
| + | |||
| + | The option is ''%%--openssh-config%%'', and you follow it with a filename. | ||
| + | |||
| + | To refer to this file from your main OpenSSH configuration, you can use the ''Include'' directive. For example, you might run Pageant like this (with your own username substituted, of course): &winpath | ||
| + | <code> | ||
| + | pageant --openssh-config C:\Users\martin\.ssh\pageant.conf | ||
| + | </code> | ||
| + | |||
| + | and then add a directive like this to your main ''.ssh\config'' file (assuming that lives in the same directory that you just put | ||
| + | ''pageant.conf''): | ||
| + | <code> | ||
| + | Include pageant.conf | ||
| + | </code> | ||
| + | Note: this technique only works with Windows's port of OpenSSH, which lives at ''%SYSTEMROOT%\System32\OpenSSH\ssh.exe'' if you have it installed. (If not, it can be installed as a Windows optional feature, e.g., via //Settings > Apps & features > Optional features > Add a feature > OpenSSH Client//.) &wincp &winpath | ||
| + | |||
| + | There are other versions of OpenSSH for Windows, notably the one that comes with Windows Git. Those will likely not work with the same configuration, because they tend to depend on Unix emulation layers like MinGW or MSys, so they won't speak Windows native pathname syntax or understand named pipes. The above instructions will only work with Windows's own version of OpenSSH. | ||
| + | |||
| + | So, if you want to use Windows Git with an SSH key held in Pageant, you'll have to set the environment variable ''GIT_SSH'', to point at a different program. You could point it at ''C:\Windows\System32\OpenSSH\ssh.exe'' once you've done this setup – but it's just as easy to point it at Plink! | ||
| + | |||
| + | ==== Unix-domain sockets: integrating with WSL 1 ==== | ||
| + | |||
| + | Pageant can listen on the WinSock implementation of Unix-domain sockets. These interoperate with the Unix-domain sockets found in the original Windows Subsystem for Linux (now known as WSL 1). So if you ask Pageant to listen on one of these, then your WSL 1 processes can talk directly to Pageant. | ||
| + | |||
| + | To configure this, run Pageant with the option ''--unix'', followed with a pathname. Then, in WSL 1, set the environment variable ''SSH_AUTH_SOCK'' to point at the WSL translation of that pathname. | ||
| + | |||
| + | For example, you might run | ||
| + | <code> | ||
| + | pageant --unix C:\Users\Simon\.ssh\agent.sock | ||
| + | </code> | ||
| + | and in WSL 1, set the environment variable | ||
| + | <code> | ||
| + | SSH_AUTH_SOCK=/mnt/c/Users/Simon/.ssh/agent.sock | ||
| + | </code> | ||
| + | Alternatively, you can add a line to your ''.ssh/config'' file inside WSL that says | ||
| + | <code> | ||
| + | IdentityAgent /mnt/c/Users/Simon/.ssh/agent.sock | ||
| + | </code> | ||
| + | although doing it like that may mean that ''ssh-add'' commands won't find the agent, even though ''ssh'' itself will. | ||
| + | |||
| + | Security note: Unix-domain sockets are protected against access by other users by the file protections on their containing directory. So if your Windows machine is multiuser, make sure you create the socket inside a directory that other users can't access at all. (In fact, that's a good idea on general principles.) | ||
| + | |||
| + | Compatibility note: WSL 2 processes cannot talk to Pageant by this mechanism, because WSL 2's Unix-domain sockets are managed by a separate Linux kernel, and not by the same kernel that WinSock talks to. | ||
| + | |||
| + | ==== Starting with the Key List Visible ==== | ||
| + | |||
| + | Start Pageant with the ''%%--keylist%%'' option to show the main window as soon as it starts up. | ||
| ===== Using Agent Forwarding ===== | ===== Using Agent Forwarding ===== | ||
| Agent forwarding is a mechanism that allows applications on your SSH server machine to talk to the agent on your client machine. | Agent forwarding is a mechanism that allows applications on your SSH server machine to talk to the agent on your client machine. | ||
| - | Note that at present, agent forwarding in SSH-2 is only available when your SSH server is OpenSSH. The ssh.com server uses a different agent protocol, which WinSCP does not yet support. | + | Note that at present, whether agent forwarding in SSH is available depends on your server. Pageant's protocol is compatible with the OpenSSH server, but the ssh.com server uses a different agent protocol, which WinSCP does not yet support. |
| To enable agent forwarding, first start Pageant. Then set up a WinSCP SSH session in which //[[ui_login_authentication|Allow agent forwarding]]// is enabled. Open the session as normal. | To enable agent forwarding, first start Pageant. Then set up a WinSCP SSH session in which //[[ui_login_authentication|Allow agent forwarding]]// is enabled. Open the session as normal. | ||
| Line 107: | Line 164: | ||
| If the result line comes up blank, agent forwarding has not been enabled at all. | If the result line comes up blank, agent forwarding has not been enabled at all. | ||
| - | Now if you run ssh on the server and use it to connect through to another server that accepts one of the keys in Pageant, you should be able to log in without a password: | + | Now if you run ''ssh'' on the server and use it to connect through to another server that accepts one of the keys in Pageant, you should be able to log in without a password: |
| <code> | <code> | ||
| Line 118: | Line 175: | ||
| </code> | </code> | ||
| - | If you enable agent forwarding on that SSH connection as well (see the manual for your server-side SSH client to find out how to do this), your authentication keys will still be available on the next machine you connect to - two SSH connections away from where they're actually stored. | + | If you enable agent forwarding on that SSH connection as well (see the manual for your server-side SSH client to find out how to do this), your authentication keys will still be available on the next machine you connect to -- two SSH connections away from where they're actually stored. |
| In addition, if you have a private key on one of the SSH servers, you can send it all the way back to Pageant using the local ''ssh-add'' command: | In addition, if you have a private key on one of the SSH servers, you can send it all the way back to Pageant using the local ''ssh-add'' command: | ||
| Line 132: | Line 189: | ||
| and then it's available to every machine that has agent forwarding available (not just the ones downstream of the place you added it). | and then it's available to every machine that has agent forwarding available (not just the ones downstream of the place you added it). | ||
| - | ===== Security Considerations ===== | + | ===== [[deferred_decryption]] Loading Keys without Decrypting Them ===== |
| + | |||
| + | You can add keys to Pageant without decrypting them. The key file will be held in Pageant's memory still encrypted, and when a client program first tries to use the key, Pageant will display a dialog box prompting for the passphrase so that the key can be decrypted. | ||
| + | |||
| + | This works the same way whether the key is used by an instance of WinSCP or PuTTY running locally, or a remote client connecting to Pageant through agent forwarding. | ||
| + | |||
| + | To add a key to Pageant in this encrypted form, press the //Add Key (encrypted)// button in the Pageant main window, or alternatively right-click on the Pageant icon in the system tray and select //Add Key (encrypted)// from there. Pageant will bring up a file dialog, in just the same way as it would for the plain //Add Key// button. But it won't ask for a passphrase. Instead, the key will be listed in the main window with //(encrypted)// after it. | ||
| + | |||
| + | To start Pageant up in the first place with encrypted keys loaded into it, you can use the ''%%--encrypted%%'' option on the command line. For example: | ||
| + | <code> | ||
| + | "C:\Program Files (x86)\WinSCP\PuTTY\pageant.exe" --encrypted d:\main.ppk | ||
| + | </code> | ||
| + | After a key has been decrypted for the first use, it remains decrypted, so that it can be used again. The main window will list the key with //(re-encryptable)// after it. You can revert it to the previous state, where a passphrase is required, using the //Re-encrypt// button in the Pageant main window. | ||
| + | |||
| + | You can also 're-encrypt' all keys that were added encrypted by choosing //Re-encrypt All Keys// from the System tray menu. (Note that this does not discard cleartext keys that were not previously added encrypted!) | ||
| + | |||
| + | Caution: When Pageant displays a prompt to decrypt an already-loaded key, it cannot give keyboard focus to the prompt dialog box. As far as we know this is a deliberate defensive measure by Windows, against malicious software. So make sure you click in the prompt window before typing your passphrase, or else the passphrase might be sent to somewhere you didn't want to trust with it! | ||
| + | |||
| + | ===== [[security_considerations]] Security Considerations ===== | ||
| Using Pageant for public-key authentication gives you the convenience of being able to open multiple SSH sessions without having to type a passphrase every time, but also gives you the security benefit of never storing a decrypted private key on disk. Many people feel this is a good compromise between security and convenience. | Using Pageant for public-key authentication gives you the convenience of being able to open multiple SSH sessions without having to type a passphrase every time, but also gives you the security benefit of never storing a decrypted private key on disk. Many people feel this is a good compromise between security and convenience. | ||
| Line 142: | Line 217: | ||
| Similarly, use of agent forwarding is a security improvement on other methods of one-touch authentication, but not perfect. Holding your keys in Pageant on your Windows box has a security advantage over holding them on the remote server machine itself (either in an agent or just unencrypted on disk), because if the server machine ever sees your unencrypted private key then the sysadmin or anyone who cracks the machine can steal the keys and pretend to be you for as long as they want. | Similarly, use of agent forwarding is a security improvement on other methods of one-touch authentication, but not perfect. Holding your keys in Pageant on your Windows box has a security advantage over holding them on the remote server machine itself (either in an agent or just unencrypted on disk), because if the server machine ever sees your unencrypted private key then the sysadmin or anyone who cracks the machine can steal the keys and pretend to be you for as long as they want. | ||
| - | However, the sysadmin of the server machine can always pretend to be you on that machine. So if you forward your agent to a server machine, then the sysadmin of that machine can access the forwarded agent connection and request signatures from your private keys, and can therefore log in to other machines as you. They can only do this to a limited extent - when the agent forwarding disappears they lose the ability - but using Pageant doesn't actually prevent the sysadmin (or hackers) on the server from doing this. | + | However, the sysadmin of the server machine can always pretend to be you on that machine. So if you forward your agent to a server machine, then the sysadmin of that machine can access the forwarded agent connection and request signatures from any of your private keys, and can therefore log in to other machines as you. They can only do this to a limited extent -- when the agent forwarding disappears they lose the ability -- but using Pageant doesn't actually prevent the sysadmin (or hackers) on the server from doing this. |
| Therefore, if you don't trust the sysadmin of a server machine, you should never use agent forwarding to that machine. (Of course you also shouldn't store private keys on that machine, type passphrases into it, or log into other machines from it in any way at all; Pageant is hardly unique in this respect.) | Therefore, if you don't trust the sysadmin of a server machine, you should never use agent forwarding to that machine. (Of course you also shouldn't store private keys on that machine, type passphrases into it, or log into other machines from it in any way at all; Pageant is hardly unique in this respect.) | ||