Start documentation

user.capnp

@@ -48,9 +48,26 @@ struct User
 
     cardDESFire @2 :CardDESFire;
     interface CardDESFire $CSharp.name("CardDESFireInterface") {
+        # Card authentication using NXP/MiFare DESFire cards.
+        # These cards have the ability to restrict access for data on the cards using symmetric
+        # encryption and using a keyed Diffie-Hellman to prevent eavesdropping by any relaying
+        # party.
+
         getPIDList @0 () -> ( pids :List(Text) );
-        getNewURL @1 () -> ( url :Text );
+        # Get a list of all user URL currently bound to an user. This will generally be the number
-        bind @2 ( pid :Text, auth_key :Text ) -> ();
+        # of cards they use.
-        revoke @3 ( pid :Text ) -> ();
+
+        genUserURL @1 () -> ( url :Text );
+        # Generate a new URL that can be used to access an user in a pseudonymized fashion.
+        # This call is extremely cheap to make as the server will not store the URL.
+
+        bind @2 ( url :Text, auth_key :Data ) -> ();
+        # Bind a given URL to a given auth key. The server will store both URL and key, so using
+        # this frequently will force the server to store large amounts of data. 
+        # Trying to bind a new key to an existing URL will fail.
+
+        revoke @3 ( url :Text ) -> ();
+        # Revoke the key associated with the given URL. This will fail all future attempts to use
+        # the card with the associated key.
     }
 }