summaryrefslogtreecommitdiffhomepage
path: root/src/prj/totp/index.html
blob: aa040d4fa62123e7a7fe5ab4739fc01e0a225dd5 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
<!DOCTYPE html>
<html lang="en">
  <head>
		m4_include(head.html)
  </head>
  <body>
		<header>
			<div>
				<h1>Easy Password Generation</h1>
				m4_include(nav.html)
			</div>

			<figure class="quote">
				<blockquote>
					<p>The C preprocessor is worse than m4, and I would kill myself
					before I had to use m4.</p>
				</blockquote>
				<figcaption>
					Arav K.
				</figcaption>
			</figure>
		</header>

		<main>
			<p>
				<em>
					You can find the <code>totp</code> git repository over at
					<a href="https://git.sr.ht/~mango/totp" target="_blank">sourcehut</a>
					or <a href="https://github.com/Mango0x45/totp"
					target="_blank">GitHub</a>.
				</em>
			</p>

			<h2>Table of Contents</h2>

			<ul>
        <li><a href="#prologue">Prologue</a></li>
        <li><a href="#terms">Terminology</a></li>
        <li><a href="#usage">Basic Usage</a></li>
        <li><a href="#qr">Working with QR Codes</a></li>
			</ul>

			<h2 id="prologue">Prologue</h2>
			<p>
				<abbr class="totp">TOTP</abbr> codes are pretty cool, and really easy to
				do.  They’re also the backbone of modern two-factor authentication.
				With <code>totp</code> I hope to make
				handling <abbr class="totp">TOTP</abbr> codes as easy and extensible as
				possible.
			</p>

			<h2 id="terms">Terminology</h2>
			<p>
				There are a few terms that I will be using throughout this post, so it’s
				good to make sure that we’re all on the same page about what I’m
				referring to.
			</p>

			<dl>
				<dt>Secret</dt>
				<dd>
					<p>
						Your <em>secret</em> is
						a <a href="https://en.wikipedia.org/wiki/Base32"
						target="_blank">base32</a> encoded secret key that you should under
						no circumstances share with anyone else.  It is from this secret key
						that we can generate valid <abbr class="totp">TOTP</abbr> codes.
					</p>
				</dd>

				<dt>Digits</dt>
				<dd>
					<p>
						Your <em>digits</em> is the length of the generated
						<abbr class="totp">TOTP</abbr> in digits.  If <em>digits</em> is 8,
						then your generated key could be ‘01234567’.  When dealing
						with <abbr class="tfa">2FA</abbr> this is typically 6.
					</p>
				</dd>

				<dt>Period</dt>
				<dd>
					<p>
						Your <em>period</em> it the duration for which the generated key is
						valid in seconds.  When working with <abbr class="tfa">2FA</abbr>
						this is typically 30.
					</p>
				</dd>
			</dl>

			<h2 id="usage">Basic Usage</h2>
			<p>
				<code>totp</code> takes secret keys as command-line arguments, but also
				reads them from the standard input if none are provided.  It assumes
				that <em>digits</em> is 6 and <em>period</em> is 30.  These defaults can
				be changed with the <code>-d</code> and <code>-p</code> flags.
			</p>

			<figure>
				<pre>m4_fmt_code(basic-usage.sh.html)</pre>
			</figure>

			<aside>
				<p>
					I’m using <code>mkpass</code> to generate a random secret.  You can
					see my post about <code>mkpass</code> <a href="/prj/mkpass">here</a>.
				</p>
			</aside>

			<h2 id="qr">Working with <abbr class="qr">QR</abbr> Codes</h2>
			<p>
				Often times when enabling <abbr class="tfa">2FA</abbr> on your account
				on some website or platform, you will be shown
				a <abbr class="qr">QR</abbr> code you can scan with
				your <abbr class="tfa">2FA</abbr> mobile application.
				These <abbr class="qr">QR</abbr> codes
				contain <em>otpauth</em> <abbr class="uri">URI</abbr>s.  We can extract
				these from downloaded images using utilities such
				as <code>zbarimg</code> and use them in <code>totp</code> using
				the <code>-u</code> flag to enable ‘<abbr class="uri">URI</abbr> mode’
			</p>

			<figure>
				<pre>m4_fmt_code(zbarimg.sh.html)</pre>
			</figure>

			…and that’s all!  There’s nothing else you need.  You can use secret keys
			and otpauth <abbr class="uri">URI</abbr>s, and you can configure
			the <em>digits</em> and <em>period</em> of the generated codes.  You can
			generate multiple keys at once, and all outputs are printed to the
			standard output.
		</main>

		<hr>

		<footer>
			m4_footer
		</footer>
	</body>
</html>