diff options
author | Franklin Wei <frankhwei536@gmail.com> | 2016-05-25 21:43:32 -0400 |
---|---|---|
committer | Franklin Wei <frankhwei536@gmail.com> | 2016-06-05 14:25:09 -0400 |
commit | 30d7ead6af5c28ff72d6e47bab7e044657be7ce6 (patch) | |
tree | 57b38d872bb37cf361fb2777ba5da48d5fc14a3c /manual/plugins/otp.tex | |
parent | 59ae562a3280105595e690ebff772ea4f7790970 (diff) | |
download | rockbox-30d7ead6af5c28ff72d6e47bab7e044657be7ce6.tar.gz rockbox-30d7ead6af5c28ff72d6e47bab7e044657be7ce6.zip |
One-Time Password client (HOTP and TOTP)
* Implements RFC 4226 (HOTP) and RFC 6238 (TOTP)
* Adds sha1.c to apps/plugins/lib (orignally tools/hmac-sha1.c)
* See manual entry for more information
Change-Id: Ia4a4031b29f97361b541e71438aa7f3ea82212f2
Diffstat (limited to 'manual/plugins/otp.tex')
-rw-r--r-- | manual/plugins/otp.tex | 72 |
1 files changed, 72 insertions, 0 deletions
diff --git a/manual/plugins/otp.tex b/manual/plugins/otp.tex new file mode 100644 index 0000000000..5b1a29f8c2 --- /dev/null +++ b/manual/plugins/otp.tex | |||
@@ -0,0 +1,72 @@ | |||
1 | % $Id$ % | ||
2 | \subsection{One-Time Password Client} | ||
3 | This plugin provides the ability to generate one-time passwords (OTPs) | ||
4 | for authentication purposes. It implements an HMAC-based One-Time | ||
5 | Password Algorithm (RFC 4226), and on targets which support it, a | ||
6 | Time-based One-Time Password Algorithm (RFC 6238). | ||
7 | |||
8 | \subsubsection{Adding Accounts} | ||
9 | The plugin supports two methods of adding accounts: URI import, and | ||
10 | manual entry. | ||
11 | |||
12 | \opt{rtc}{ It is important to note that for TOTP (time-based) accounts | ||
13 | to work properly, the clock on your device MUST be accurate to no | ||
14 | less than 30 seconds from the time on the authentication server, and | ||
15 | the correct time zone must be configured in the plugin. See | ||
16 | \reference{ref:Timeanddateactual} for more information. } | ||
17 | |||
18 | \subsubsection{URI Import} | ||
19 | This method of adding an account reads a list of URIs from a file. It | ||
20 | expects each URI to be on a line by itself in the following format: | ||
21 | |||
22 | \begin{verbatim} | ||
23 | otpauth://[hotp OR totp]/[account name]?secret=[Base32 secret][&counter=X][&period=X][&digits=X] | ||
24 | \end{verbatim} | ||
25 | |||
26 | An example is shown below, provisioning a TOTP key for an account called ``bob'': | ||
27 | |||
28 | \begin{verbatim} | ||
29 | otpauth://totp/bob?secret=JBSWY3DPEHPK3PXP | ||
30 | \end{verbatim} | ||
31 | |||
32 | Any other URI options are not supported and will be ignored. | ||
33 | |||
34 | Most services will provide a scannable QR code that encodes a OTP | ||
35 | URI. In order to use those, first scan the QR code separately and save | ||
36 | the URI to a file on your device. If necessary, rewrite the URI so it | ||
37 | is in the format shown above. For example, GitHub's URI has a slash | ||
38 | after the provider. In order for this URI to be properly parsed, you | ||
39 | must rewrite the account name so that it does not contain a slash. | ||
40 | |||
41 | \subsubsection{Manual Import} | ||
42 | If direct URI import is not possible, the plugin supports the manual | ||
43 | entry of data associated with an account. After you select the | ||
44 | ``Manual Entry'' option, it will prompt you for an account name. You | ||
45 | may type anything you wish, but it should be memorable. It will then | ||
46 | prompt you for the Base32-encoded secret. Most services will provide | ||
47 | this to you directly, but some may only provide you with a QR code. In | ||
48 | these cases, you must scan the QR code separately, and then enter the | ||
49 | string following the ``secret='' parameter on your Rockbox device | ||
50 | manually. | ||
51 | |||
52 | On devices with a real-time clock, \opt{rtc}{like yours,} the plugin | ||
53 | will ask whether the account is a time-based account | ||
54 | (TOTP). \opt{rtc}{If you answer ``yes'' to this question, it will ask | ||
55 | for further information regarding the account. Usually it is safe to | ||
56 | accept the defaults here. } However, if your device lacks a | ||
57 | real-time clock, the plugin's functionality will be restricted to | ||
58 | HMAC-based (HOTP) accounts only. If this is the case, the plugin will | ||
59 | prompt you for information regarding the HOTP setup. | ||
60 | |||
61 | \opt{rtc} { | ||
62 | \subsection{Advanced Settings} | ||
63 | \subsubsection{Time Zone Configuration} | ||
64 | In order for TOTP accounts to work properly, the plugin must be able | ||
65 | to determine the current UTC time. This means that, first, your | ||
66 | device's clock must be synchronized with UTC time, and second, that | ||
67 | the plugin knows what time zone the clock is using. The plugin will | ||
68 | prompt you on its first run for this piece of information. However, | ||
69 | should this setting need changing at a later time, possibly due to | ||
70 | Daylight Saving Time adjustment, it is located under the | ||
71 | ``Advanced'' submenu. NOTE: in the UI simulator, use the ``UTC'' | ||
72 | setting no matter what the clock may read. } | ||