File doc/auth.md from the latest check-in

credentials & authentication

parsav features a highly flexibly authentication system, and provides alternatives to simple per-user passwords to help users keep their accounts secure. you can create as many credentials for your account as you wish, and tie them to specific IP addresses or regions. you can even restrict the capabilities of a given credential -- for instance, you could have one password that allows full access and one that only allows posting new tweets when logged in with it.

mechanisms

you're not limited to passwords, however. parsav intends to support a very wide range of authentication mechanisms; this page lists all the mechanisms that have been implemented so far.

password auth

of course, parsav lets you access your account with passwords/passphrases like most other software. when you create a new password, you'll be asked to enter it twice to confirm that you haven't mistyped it; you'll then be able to use it by typing it into the login screen.

passwords have many disadvantages, however. they're easy to steal, easy to forget, they get more and more difficult to use the more secure they are, and people have an awful habit of writing them down. if you don't have any problems memorizing long, secure passwords, this may not be a problem for you. but even then, there's no way around the fundamental problem that passwords are static -- you only have to slip up once (say, by typing it into a username field by mistake just as the black helicopters are passing overhead) and then the password is compromised forever.

of course, if you have a static IP address, you can get around some of the insecurity by setting a netmask on the password -- it won't do mongolian bitcoin scammers much good if only IPs from mecklenburg-vorpommern are allowed to use it. netmasks are however best used on VPNs, LANs, and similar arrangements where you have an absolute guarantee of a static IP address. for other circumstances, challenge auth may be a worthwhile means of improving your security.

challenge auth

parsav also supports challenge auth, which is a form of authentication where are presented with a challenge token at login and have to provide with a response digest based on the token to authenticate yourself. this mechanism has the very useful property that the same digest can only be used for a very short period of time, after which they are permanently deactivated, giving you a bit of protection even if your HTTP session is exposed to a man-in-the-middle. due to the way they're implemented, they're effectively immune to shouldersurfing. challenge auth is generally based on cryptographic keys.

right now, the only form of challenge authentication supported is RSA asymmetric keypairs, though other methods based on elliptic curve cryptography and shared secrets are planned. an RSA keypair is a pair of very long numbers -- called the public key and the private key -- with special mathematical properties: anyone who holds the public key can encrypt data such that only the person with the private key can read it, and whoever holds the private key can place a digital signature on a piece of data such that anyone with the public key can confirm the data was endorsed by the holder of the private key. (private keys can of course be encrypted with a password; the advantage this has over normal passwords is that the password never leaves your computer's memory.) so when you log in with RSA challenge auth, you'll be given a short string to sign with your private key. all you have to do is paste the signature into the "digest" box and you'll be logged in.

keypairs are bit more complex to use than passwords, however. you have to use a special tool to create them. on linux and other unix-like systems, you can do this with the openssl command:

$ openssl genrsa 2048 -out private.pem
  # creates a reasonably secure 2048-bit private key

$ openssl genrsa 4096 -out private.pem
  # creates an *extremely* secure 4096-bit key

$ openssl genrsa 2048 -aes256 -out private.pem
  # pass -aes256 to encrypt your key

once you've created your private key with a command like one of the above, you'll need to separate out a public key. if you used the -aes256 flag, you'll be prompted for your password. (keep in mind, absent major progress in quantum computing, this password cannot be recovered if it is forgotten!)

$ openssl rsa -in private.pem -pubout -out public.pem

public.pem is the file you'll want to copy and paste into the text box when you add this keypair as a credential to your parsav account. do not ever upload private.pem anywhere! if you ever do so by accident, delete the keypair credential from every account that uses it immediately, as you have irreversibly compromised their security.

finally, you'll need to use this key to actually sign things:

$ echo -n "this is the string that will be signed" | openssl dgst -sha256 -sign private.pem | openssl base64

this command is somewhat complex, so you may want to write a short script to save yourself some time. on computers with the X windows system, you can use the following convenient command to encrypt whatever is currently in the clipboard:

$ xsel -bo | openssl dgst -sha256 -sign private.pem | openssl base64 | xsel -bi

if you later want to change the password on your private key, you can use this command to do so:

$ openssl rsa -in private.pem -aes256 -out private.pem
  # omit the -aes256 to remove the encryption

managing credentials

you can use the "security" panel in the configuration menu to manage your credentials. this panel has a wide range of options. firstly, if you suspect someone may have unwanted access to your account, you can press the "invalidate other sessions" button to instantly log out every computer but your own. of course, this will only briefly inconvenience evildoers if they hold a valid credential for your account -- it's mainly useful for instances where you forgot to log out of a public computer, or one that belongs to someone else.

you can manage existing credentials with the "revoke" button, which wipes out a selected credential so it can no longer be used to log in (and logs out every device logged in under it!), or reset, which lets you change the credentials without affecting their privilege sets.