Diligence is still under development and incomplete, and some this documentation is wrong. For a more comprehensive but experimental version download the Savory Framework, which was the preview release of Diligence.
Nonces Service
This is a straightforward implementation of number-used-once, or "nonce," using MongoDB atomic operations.
It allows you to issue a unique number, which you can then "check." The check will work once and only once for any issued nonce, across all nodes accessing the same MongoDB database. Furthermore, every issued nonce is given an expiration time, after which it will be considered invalid.
Nonces are often used in authentication schemes, where tokens, meant to be used only once, are purposely issued for short time periods in order to minimize security risks.
Usage
Make sure to check out the API documentation for Diligence.Nonces.
The API is very simple. To issue a 60-second nonce:
document.executeOnce('/diligence/service/nonces/') var nonce = Diligence.Nonces.create(60 1000)
To check a nonce:
if (!Diligence.Nonces.check(nonce)) { print('Your token is invalid! Perhaps it was expired? Try logging in again.') }
Note that the nonces used in the API are strings, which are hexadecimal representations of big integers. Strings are preferable in this use case, because you can be certain that precision will not be lost across various conversions and serializations. If you really need a non-hexadecimal representation, you can convert it a nonce using the following:
var nonceInteger = new java.math.BigInteger(nonce, 16) print(nonceInteger) // this will print a decimal representation of the nonce
Configuration
The service removes expired nonces only when you check them. If it's important for you to save space and remove all expired nonces, you might want to call the Diligence.Nonces.prune method regularly. You can do this in your "crontab" file. Here's an example of doing so every 15 minutes:
/15 <% document.executeOnce('/diligence/service/nonces/'); Diligence.Nonces.prune(); %>
The Diligence Manual is provided for you under the terms of the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. The complete manual is available for download as a PDF.