README.publickeys
How to use SSH 2 public-key authentication


## Support ##

pssh supports public-key authentication using RSA or DSA keys. 
The private key data stored on the handheld may be encrypted 
using a passphrase, or it may be passphrase-less. (See the 
Security Note below.)

pssh cannot generate keypairs itself. pssh cannot currently 
change the passphrase of an existing key pair. 


## Security Note ##

Passphrase-less key pairs are more convenient (you don't have to 
type any password when logging in), but they are MORE INSECURE than 
passphrase-protected key pairs. Specifically, any person or program 
with access to your handheld or its Backup data can easily steal your 
private key and use it to connect as you. With passphrase-protected 
keys, a stolen key pair is not useful unless the attacker also can 
steal or guess your passphrase.


## Authentication procedure ##

When you connect to a server, pssh attempts to authenticate using 
any available public keys before prompting for an ordinary password. 
The procedure is as follows:
1. pssh determines whether the server supports public-key authentication. 
   If the server does not, public-key authentication is skipped.
2. pssh attempts to authenticate using every passphrase-less key 
   available. 
3. pssh asks the server whether any of the available passphrase-
   protected keys would be accepted for authentication.
4. pssh asks you for the passphrase for a passphrase-protected 
   key. If multiple passphrase-protected keys are acceptable on 
   the server, pssh allows you to choose which one to use.
5. If all public-key authentication attempts fail, pssh prompts you 
   for an ordinary (non-public-key) password.

It's possible that step #2 will cause trouble if you have many 
passphrase-less keys and are attempting to connect to a paranoid 
server that rejects the connection after a small number of failed 
public-key authentication attempts. There is currently no workaround 
for this; contact the author of pssh if you encounter this problem.


## Key import ##

pssh does not generate key pairs itself. Instead, key pairs must be 
imported from outside. Currently pssh can import OpenSSH-formatted 
private key files via Memo Pad memos. A memo containing a key must 
start with a one-line name, followed by the OpenSSH private key data. 

With OpenSSH on Unix, these key files can be generated by `ssh-keygen`. 
PuTTY on Windows can generate keys and export them in OpenSSH format.

Example Memo Pad memo (a passphrase-less RSA key):

   This first line will be pssh's name for the key.
   -----BEGIN RSA PRIVATE KEY-----
   MIICWwIBAAKBgQCuWCQLxeyBlv1hu/rOWRYe8tBJ3HUQ8NEXbEgCm/4bmZaJ1WbS
   0HTR3KXilKHp4rsBfWVkSNnn3oezo6ik6gCiR/5sijGSJnQti9yMu/lFZ3gVRO8A
   ngus2CnQLmbGfZj/XnkP6f051hhyP0pO7kwZkaWWpuNTdHupFDVb50zNaQIBIwKB
   gHeM5YRqdko7pm7nTOVEZvCmgDKlzJ3m9cbrKhBq92NiANOLBK3QxSIw5sdBWRVo
   Rbfg9RGRCnMcP8ujbFPTqKioF46iMjw9AKbujDF8UrqAztIBOJKEunNHyE8QQovZ
   linugtlkybgFLBIdEdFNG7ngtSfgui/SEFusdfkyngkSYgfygNUfsuKFNuynkfus
   5j87FydxkPHqOe5UYXa4nhvUXvXnahw2E1uvQ4LRkLxek+0oOdTq4or5D5LNaVIM
   zIiPXwJBAMFQZOPb+zL4Jsd4fqsWulR4XBzf62KNcFiu+ZiUkNdC1WjJH3MUWpov
   OnfU26P9IIgOAoueyRf5E1hRZkvKADcCQQCyG0rslk/EAMXD0jXsIiZFD8yjA8NR
   QtNhIRITkc+2+DYtSPaD9kVf9zPzT3wo+MdCjk7MBM7C3vY7TeydyG6ZAkAQkdzD
   EtsEXmm5U3iSUme+GPHz2K3Gnmi3JPDSkGQvtUV+ApxLsUmYL+8RlebwzI3ChNul
   kURvxORmp+QyYcWBAkEArW8tp3XMT9vHDncfiW8sxOp/IYhoyUef7QrSaR4DsitE
   okRGOSIIpGRAPVOpZvVpAGuFdeYLiYC9I90TZSFx0Q==
   -----END RSA PRIVATE KEY-----

Example (a passphrase-protected DSA key):

   me@ssh-server.example.com's key
   -----BEGIN DSA PRIVATE KEY-----
   Proc-Type: 4,ENCRYPTED
   DEK-Info: DES-EDE3-CBC,D0FCEE0E84F8608C
   
   hYNAqkX7115lYiEpcBEE6i/gGKllDxapL/iNpx93Aj+fofksrlTRbbKEdLBOVyuf
   2OMdzuQ56Wk96YE1gWHEdbK9QxyXL0rBQL5jMFJ1svKzRAgIo7VYPrSem+YjkC9u
   GQex2zIwvbBh1CyQqtezQlxD2nmdPMEicvTbo0t14SoedXPUNI6wMsv/64mGbDfd
   r0FYBXOyNn1yglNbkAOUMusrUfdzEa7oR1VG9pugXYzdDRx+bspJ9xm+4AZD2cwu
   WsJN21U5ezJMQk763ImuFkyzw5TXKY1ZFUI22CWUrJpB4j87NScWUecFgfUGFYPn
   nXonMAPNi65Kdr4ynx5GsNgxhoOWuWL+Qz0B2PPYS7dmJUdBmc6F71qquASsnpgu
   sSLeLTm/GUt8gFVFc5WdURWQsIpt42dZx8/FXgVblZ2FSSuoOVEqgn9/ENh2Hz1S
   Ft6fVnpSPyx11gqZlKYvGkHAyrf6Fr2+cnDBoK0AZ3wf8b5DYekEKmCKQFlAKBYs
   YSeup9p1Qk3c9qxyOyWMM86/jqWbds3KZg7AfCJgUT/aAAaATHZKZWU2m/RINS/y
   UoPPL7evby2FTjkW82Atrg==
   -----END DSA PRIVATE KEY-----