provider
Folders and files
Name | Name | Last commit date | ||
---|---|---|---|---|
parent directory.. | ||||
NameID libauth ============== The authentication component (including its RPC interface to namecoind) of NameID can be used separately from the rest. This is a deliberate choice in order to allow site owners to include Namecoin login into their projects directly--without the need to go through OpenID or to use nameid.org (or another such site) as intermediate party for logins. Only this enables truly independent and trust-free logins. Login Protocol -------------- The "protocol" used for NameID logins is very simple: The server generates a "nonce" value, which is just a random string, to prevent replay-attacks. In NameID, the nonce is stored with the client's session. In order to prove ownership of a claimed identity at login, the client has to sign a challenge message with the Namecoin address holding the identity's name. The format of the challenge message is (without the indentation whitespace): login FULL-ID NONCE where NONCE is the nonce value the server told it, and FULL-ID is the full identity URI that is also used as OpenID with NameID. It is SERVER-URI?name=IDENTITY where SERVER-URI is the service's URI in the case of NameID (but can be chosen in principle arbitrarily for your service, see below) and IDENTITY is the identity name without the leading "id" namespace prefix. (In fact, other prefixes than "id" are also possible--this can be configured, see below.) Client Side ----------- You must write out a login form (or something like that) which tells the client its nonce and gets back the client's claimed identity as well as the challenge message signature. It is up to your application to handle how this communication is done, but if you follow the practices outlined below, the NameID add-on can be utilised to automatically sign the challenge messages (if it is available on the client side). All communication between your page and the add-on should be done using the predefined JS library in js/NameId.js. The basic usage looks like this: var nameid = new NameId (URL, NONCE); nameid.requestApi (); ... /* To try to sign the challenge for a user with identity ID, you can use the following code. It could be called, for instance, in the "onsubmit" event handler of your login form. */ if (nameid.hasApi ()) { var SIG = nameid.signChallenge (ID); /* Do something with the signature in SIG. Set a form element's value to SIG and submit the form, or whatever else. */ } See also NameID's own login page, with the code in pages/loginForm.php. The "nameid" object above provides also the method "nameid.getChallenge (ID)", which can be used (even if the add-on is not available) to construct the challenge message in the required format for the given identity. Server Side ----------- For the server side of your application, the files provided in libauth can be used to check authentication. They are self-contained and don't need any other files from NameID. Generation of the nonce (see lib/session.inc.php and in particular Session::generateNonce for how NameID does it) must be implemented by you however you like to do it, and also sending the nonce and retrieving the login data back from the client is out of the scope of libauth. For checking received authentication data, you can use code according to the following overview: require_once ("libauth/authenticator.inc.php"); require_once ("libauth/namecoin_interface.inc.php"); require_once ("libauth/namecoin_rpc.inc.php"); $rpc = new HttpNamecoin (RPC-HOST, RPC-PORT, RPC-USER, RPC-PASSWORD); $nc = new NamecoinInterface ($rpc, NAMESPACE-PREFIX); $auth = new Authenticator ($nc, SERVER-URI); try { $res = $auth->login (CLAIMED-IDENTITY, SIGNATURE, NONCE); assert ($res === TRUE); /* Authentication succeeded, log the user into your system. */ } catch (LoginFailure $err) { /* Authentication failed, abort the login process. You may want to show $err->getMessage () to the user to tell them more details. */ } $nc->close (); This code can be found in NameID's index.php. The values RPC-* denote the connection settings to the Namecoin JSON-RPC server that should be used for Namecoin operations (usually, "localhost" at port 8336 with username/password according to the namecoin.conf file). NAMESPACE-PREFIX is the namespace to be used for identities, which should probably be "id". SERVER-URI is a unique identifier for your service, and can for instance be your service's URI. It is "https://nameid.org/" in case of NameID. Finally, CLAIMED-IDENTITY is the user's claimed identity as which he/she tries to log in (without the "id" prefix, just like "domob" for the Namecoin identity "id/domob"), SIGNATURE the challenge message signature by your user, and NONCE the user's login nonce as stored by you for the current session. The Authenticator::login method throws LoginFailure (or a RpcException) in case of failure to authenticate (or if the Namecoin communication fails) and returns TRUE without exceptions in case the authentication is successful. Note that libauth also provides code to communicate with Namecoin not via the HTTP JSON-RPC interface but by executing the "namecoind" binary, in which case the class HttpNamecoin above should be replaced by Namecoind. This is not recommended, though, and the Namecoind code is no longer maintained.