Write a bit of documentation

diff --git a/README b/README
index c3750c0a7191f4bf59990b37b99f6acda8d58fb4..a68fcfcd79a6fdde9d80b2a9c4a7d68ac2562204 100644 (file)
--- a/README
+++ b/README
@@ -17,4 +17,58 @@ group=yubikeyd
 dbdef=dbname=yubikey port=5433
 port=8000
 
+Getting started
+===============
 
+yubikey-server-c stores raw bytes in some of the tables rather than a
+Base64 or hex encoded representation. PostgreSQL has (at least) two
+ways to insert this kind of data:
+
+- Use decode('encoded_string_goes_here', 'encoding')
+
+- Use quoted byte strings: E'\\000\\000\\000\\000\\000\\000'.  The
+  numbers are octal
+
+To authenticate an OTP the Yubikey needs to exist in the database and
+the client asking yubikey-server-c must be allowed access.  Each
+client (typically each service) that authenticates needs its own
+shared secret.  To set this up, do
+
+  INSERT INTO shared_secret (secret, active) VALUES
+    (decode('MQ6fOy1t/add/wisbu2O+LpPiMs=', 'base64'), 't');
+
+The base64 string in the middle is the base64 encoded version of the
+secret as we store the raw bytes in the database.  Depending on the
+client, it might accept a base64 encoded version or it might want hex
+or something else (in its configuration file).
+
+For each yubikey, you need to insert a row into the yubikey table
+like:
+
+INSERT INTO yubikey
+  (active, public_id, secret_uid, secret_key, session_counter, session_use)
+  VALUES
+  ('t', 'tfheen', E'\\000\\000\\000\\000\\000\\000',
+   decode('baef43c254e9d2217912e80ed71a7b4a', 'hex'),
+   0, 0);
+
+The public id is the fixed part of the yubikey OTP. It is generally
+not the user name.  It is what you set using the -o fixed=ffffffff option
+to ykpersonalize.  It is between 0 and 16 charcters long.
+
+The secret uid is set using the -o uid=uuuuuu to ykpersonalize. It is
+always six bytes (or 12 modhex characters).
+
+The secret key is either randomly generated by ykpersonalize based on
+a passphrase or it can be set using the -a option.
+
+The session counter and session use generally start at 0 so they don't
+need to be changed.
+
+After this has been inserted, you should be able to authenticate using
+ykclient like:
+
+ykclient --url http://localhost:7443/verify?id=%%d&otp=%%s \
+        --apikey $shared_secret \
+        $id_of_client \
+        $otp