24 |
29 |
30 |
31 |
32 |
--------------------------------------------------------------------------------
/doc/05.multilineFiles.md:
--------------------------------------------------------------------------------
1 | # Multiline files
2 |
3 | {{insert-args}}
4 |
5 | .
6 |
7 | {{insert-noecho}}
8 |
9 | read -s, `<<<`
10 |
11 | {{insert-echo}}
12 |
13 | read -e
14 |
15 | {{insert-multiline}}
16 |
17 | .
18 |
19 | {{prepare-edit}}
20 |
21 | $EDITOR
22 |
23 | {{edit-args}}
24 |
25 | .
26 |
27 | {{edit}}
28 |
29 | mktemp, diff
30 |
31 | {{tmpdir-shm}}
32 |
33 | -d,-w,-x checks, /dev/shm, trap
34 |
35 | {{tmpdir-noshm}}
36 |
37 | /tmp, find -exec, shred
38 |
39 | {{macos-tmpdir}}
40 |
41 | umount, diskutil, hdid, newfs_hfs, mount, srm
42 |
43 | {{freebsd-shred}}
44 |
45 | rm -P
46 |
47 | {{openbsd-tmpdir}}
48 |
49 | sysctl, mount, umount
50 |
51 | {{use-tmpdir}}
52 |
53 | .
54 |
55 | {{show-line-number}}
56 |
57 | :: in getopt, tail, head
58 |
59 | {{generate-inplace}}
60 |
61 | $RANDOM, sed
62 |
63 | {{prepare-mv}}
64 |
65 | .
66 |
67 | {{mv}}
68 |
69 | mv -i, interpreting path as file or directory
70 |
71 | {{cp}}
72 |
73 | .
74 |
75 | {{prepare-grep}}
76 |
77 | .
78 |
79 | {{grep}}
80 |
81 | string expansions, find arguments, escape codes
82 |
83 |
--------------------------------------------------------------------------------
/ORDER.txt:
--------------------------------------------------------------------------------
1 | ***PASSWORD GENERATOR***
2 | cmd_generate()
3 | cmd_version()
4 | cmd_usage()
5 | die()
6 |
7 | ***PERSIST TO DISK***
8 | cmd_generate() persists to disk
9 | yesno()
10 | check_sneaky_paths()
11 | cmd_show() (with ls)
12 | cmd_find()
13 | cmd_delete()
14 |
15 | ***ENCRYPTION***
16 | cmd_init()
17 | set $GPG, $GPG_OPTS, etc.
18 | set_gpg_recipients()
19 | encrypt in cmd_generate()
20 | decrypt in cmd_show()
21 |
22 | ***GETOPT***
23 | clip()
24 | getopt
25 | qrcode()
26 | cmd_generate() options
27 | cmd_delete() options
28 |
29 | ***MULTILINE FILES***
30 | cmd_insert()
31 | cmd_edit()
32 | tmpdir()
33 | -c,-q with line number
34 | -i option to cmd_generate()
35 | cmd_copy_move()
36 | cmd_grep()
37 |
38 | ***GIT SUPPORT***
39 | set_git()
40 | git_commit()
41 | git_add_file()
42 | cmd_git()
43 | git support for all commands
44 |
45 | ***SIGNING & VERIFICATION***
46 | verify_file()
47 | sign file in cmd_init()
48 | sign git commits
49 |
50 | ***MULTIPLE PASSWORD STORES***
51 | multiple .gpg-id files
52 | git support for cmd_init()
53 | reencrypt_path()
54 |
55 | ***EXTENSION SUPPORT***
56 | cmd_extension()
57 | pass-update extension
58 |
59 | ***COMPLETION***
60 | shell completion
61 |
62 |
--------------------------------------------------------------------------------
/doc/02.storingPlaintextPasswords.md:
--------------------------------------------------------------------------------
1 | # Storing plaintext passwords
2 |
3 | {{prefix}}
4 |
5 | $HOME, what $PREFIX is for
6 |
7 | {{generate-path-arg}}
8 |
9 | new usage, length is now $2
10 |
11 | {{persist}}
12 |
13 | mkdir, dirname, command expansion, echo redirection
14 |
15 | {{generate-nargs}}
16 |
17 | $#, what $COMMAND is for
18 |
19 | {{generate-pass-name-usage}}
20 |
21 | .
22 |
23 | {{yesno}}
24 |
25 | -t check, reading from user with prompt, [yY] pattern
26 |
27 | {{use-yesno}}
28 |
29 | -e check
30 |
31 | {{sneaky-paths}}
32 |
33 | for loops, why 4 patterns for '..'
34 |
35 | {{print-password}}
36 |
37 | printf, %s, escape sequences (1m, 37m, 4m, 24m, 0m, 93m)
38 |
39 | {{prepare-show}}
40 |
41 | the nop
42 |
43 | {{show}}
44 |
45 | -f check
46 |
47 | {{default}}
48 |
49 | .
50 |
51 | {{ls}}
52 |
53 | -d check, -z check, % string expansion, tree, tail, sed
54 |
55 | {{prepare-find}}
56 |
57 | .
58 |
59 | {{find}}
60 |
61 | IFS, eval, $*, tree options, glob patterns
62 |
63 | {{prepare-rm}}
64 |
65 | .
66 |
67 | {{rm-file}}
68 |
69 | rm, rmdir -p, /dev/null
70 |
71 | {{rm-dir}}
72 |
73 | .
74 |
75 | {{exit-success}}
76 |
77 | why we're forcing a successful exit status
78 |
79 |
--------------------------------------------------------------------------------
/doc/04.getopt.md:
--------------------------------------------------------------------------------
1 | # Getopt
2 |
3 | {{generic-clip}}
4 |
5 | xclip
6 |
7 | {{cygwin-clip}}
8 |
9 | /dev/clipboard
10 |
11 | {{macos-clip}}
12 |
13 | pbcopy, darwin
14 |
15 | {{c-switch-help}}
16 |
17 | .
18 |
19 | {{c-switch}}
20 |
21 | .
22 |
23 | {{use-clip}}
24 |
25 | .
26 |
27 | {{clear-clipboard}}
28 |
29 | &, disown, exec, trap, kill %1, TERM, sleep, wait, (), qdbus, klipper
30 |
31 | {{restore-clipboard}}
32 |
33 | base64
34 |
35 | {{reset-clip-timer}}
36 |
37 | $DISPLAY, pkill, exec -a
38 |
39 | {{cygwin-clip-secure}}
40 |
41 | no trap
42 |
43 | {{macos-clip-secure}}
44 |
45 | no trap, id -u, pbpaste, openssl base64
46 |
47 | {{generic-getopt}}
48 |
49 | getopt
50 |
51 | {{macos-getopt}}
52 |
53 | brew, gnu-getopt, port, /opt/local
54 |
55 | {{freebsd-getopt}}
56 |
57 | FreeBSD
58 |
59 | {{openbsd-getopt}}
60 |
61 | gnugetopt, OpenBSD
62 |
63 | {{clip-option-usage}}
64 |
65 | .
66 |
67 | {{show-getopt}}
68 |
69 | .
70 |
71 | {{generate-getopt}}
72 |
73 | .
74 |
75 | {{generic-qrcode}}
76 |
77 | $DISPLAY, $WAYLAND_DISPLAY, qrencode, type, feh, gm, display, gm display
78 |
79 | {{macos-qrcode}}
80 |
81 | imgcat
82 |
83 | {{show-qrcode}}
84 |
85 | .
86 |
87 | {{generate-qrcode}}
88 |
89 | .
90 |
91 | {{generate-options-help}}
92 |
93 | .
94 |
95 | {{generate-options}}
96 |
97 | .
98 |
99 | {{rm-options-help}}
100 |
101 | .
102 |
103 | {{rm-options}}
104 |
105 | .
106 |
107 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Build Your Own Password Manager
2 |
3 | This is a (work-in-progress) tutorial that will teach you shell scripting by
4 | showing you how to build the [pass](https://www.passwordstore.org/) password
5 | manager in small steps.
6 |
7 | ## Assumptions
8 |
9 | * Basic shell knowledge (`cd`, `ls`)
10 | * Basic programming experience (variables, functions, conditionals, loops)
11 | * Basic understanding of `git` will help in the section where we add git
12 | support (not too important)
13 |
14 | ## The Plan
15 |
16 | 1. A password generator
17 | * Step 1: `echo "correcthorsebatterystaple"`
18 | * Generate a random string
19 | * The `generate` command
20 | * The `version` command
21 | * The `help` command
22 | 2. Storing plaintext passwords
23 | * Save generated password to `$PREFIX`
24 | * The `show` command
25 | * Make `show` the default command
26 | * The `insert` command
27 | * The `rm` command
28 | * The `mv` command
29 | * The `cp` command
30 | 3. Encryption
31 | * The `init` command
32 | * GPG options and whether to use `gpg2`
33 | * `gpg_winpath()` for Cygwin
34 | * `set_gpg_recipients()`
35 | * Encrypt with `generate` and `insert` commands
36 | * Decrypt with `show` command
37 | * Reencrypt using `init` command
38 | 4. Copy to clipboard
39 | * Generic `clip()`
40 | * Cygwin `clip()`
41 | * macOS `clip()`
42 | * `-c` option for `generate` and `show` commands
43 | * Clear clipboard after 45 seconds
44 | * Reset 45-second timer before starting a new one
45 | * Restore previous clipboard contents
46 | 5. Getopt
47 | * Find GNU getopt for the platform
48 | * Use it for `-c/--clip` switch
49 | * More switches
50 | 5. QR codes
51 | * Generic `qrcode()`
52 | * macOS `qrcode()`
53 | * `-q` option for `generate` and `show` commands
54 | 6. Secure text editing
55 | * The `edit` command
56 | * Generic `tmpdir()`
57 | * macOS `tmpdir()`
58 | * FreeBSD `$SHRED`
59 | * OpenBSD `tmpdir()`
60 | 7. Listing and searching
61 | * The `ls` command
62 | * The `find` command
63 | * The `grep` command
64 | 8. Git
65 | * The `git` command
66 | * `set_git()`
67 | * `git_add_file()`
68 | * `git_commit()`
69 | * Add git support to `generate` and `insert` commands
70 | * Add git support to `edit`, `rm`, `mv`, `cp` commands
71 | 9. Completion
72 | * `bash` completion
73 | * `zsh` completion
74 | * `fish` completion
75 | 10. Signing and verification
76 | * Sign `.gpg_id` in `init` command
77 | * `verify_file()`
78 | * Sign git commits
79 | 11. Multiple users
80 | * `--path` option for `init` command
81 | 12. User extensions
82 | * `cmd_extension()`
83 | * An example: `pass-update`
84 |
85 |
--------------------------------------------------------------------------------
/doc/html_in/fonts.css:
--------------------------------------------------------------------------------
1 | /* fira-mono-regular - latin */
2 | @font-face {
3 | font-family: 'Fira Mono';
4 | font-style: normal;
5 | font-weight: 400;
6 | src: url('fonts/fira-mono-v5-latin-regular.eot'); /* IE9 Compat Modes */
7 | src: url('fonts/fira-mono-v5-latin-regular.eot?#iefix') format('embedded-opentype'), /* IE6-IE8 */
8 | url('fonts/fira-mono-v5-latin-regular.woff2') format('woff2'), /* Super Modern Browsers */
9 | url('fonts/fira-mono-v5-latin-regular.woff') format('woff'), /* Modern Browsers */
10 | url('fonts/fira-mono-v5-latin-regular.ttf') format('truetype'), /* Safari, Android, iOS */
11 | url('fonts/fira-mono-v5-latin-regular.svg#FiraMono') format('svg'); /* Legacy iOS */
12 | }
13 |
14 | /* fira-mono-500 - latin */
15 | @font-face {
16 | font-family: 'Fira Mono';
17 | font-style: normal;
18 | font-weight: 500;
19 | src: url('fonts/fira-mono-v5-latin-500.eot'); /* IE9 Compat Modes */
20 | src: url('fonts/fira-mono-v5-latin-500.eot?#iefix') format('embedded-opentype'), /* IE6-IE8 */
21 | url('fonts/fira-mono-v5-latin-500.woff2') format('woff2'), /* Super Modern Browsers */
22 | url('fonts/fira-mono-v5-latin-500.woff') format('woff'), /* Modern Browsers */
23 | url('fonts/fira-mono-v5-latin-500.ttf') format('truetype'), /* Safari, Android, iOS */
24 | url('fonts/fira-mono-v5-latin-500.svg#FiraMono') format('svg'); /* Legacy iOS */
25 | }
26 |
27 | /* pt-serif-regular - latin */
28 | @font-face {
29 | font-family: 'PT Serif';
30 | font-style: normal;
31 | font-weight: 400;
32 | src: url('fonts/pt-serif-v8-latin-regular.eot'); /* IE9 Compat Modes */
33 | src: url('fonts/pt-serif-v8-latin-regular.eot?#iefix') format('embedded-opentype'), /* IE6-IE8 */
34 | url('fonts/pt-serif-v8-latin-regular.woff2') format('woff2'), /* Super Modern Browsers */
35 | url('fonts/pt-serif-v8-latin-regular.woff') format('woff'), /* Modern Browsers */
36 | url('fonts/pt-serif-v8-latin-regular.ttf') format('truetype'), /* Safari, Android, iOS */
37 | url('fonts/pt-serif-v8-latin-regular.svg#PTSerif') format('svg'); /* Legacy iOS */
38 | }
39 |
40 | /* pt-serif-700 - latin */
41 | @font-face {
42 | font-family: 'PT Serif';
43 | font-style: normal;
44 | font-weight: 700;
45 | src: url('fonts/pt-serif-v8-latin-700.eot'); /* IE9 Compat Modes */
46 | src: url('fonts/pt-serif-v8-latin-700.eot?#iefix') format('embedded-opentype'), /* IE6-IE8 */
47 | url('fonts/pt-serif-v8-latin-700.woff2') format('woff2'), /* Super Modern Browsers */
48 | url('fonts/pt-serif-v8-latin-700.woff') format('woff'), /* Modern Browsers */
49 | url('fonts/pt-serif-v8-latin-700.ttf') format('truetype'), /* Safari, Android, iOS */
50 | url('fonts/pt-serif-v8-latin-700.svg#PTSerif') format('svg'); /* Legacy iOS */
51 | }
52 |
53 | /* pt-serif-italic - latin */
54 | @font-face {
55 | font-family: 'PT Serif';
56 | font-style: italic;
57 | font-weight: 400;
58 | src: url('fonts/pt-serif-v8-latin-italic.eot'); /* IE9 Compat Modes */
59 | src: url('fonts/pt-serif-v8-latin-italic.eot?#iefix') format('embedded-opentype'), /* IE6-IE8 */
60 | url('fonts/pt-serif-v8-latin-italic.woff2') format('woff2'), /* Super Modern Browsers */
61 | url('fonts/pt-serif-v8-latin-italic.woff') format('woff'), /* Modern Browsers */
62 | url('fonts/pt-serif-v8-latin-italic.ttf') format('truetype'), /* Safari, Android, iOS */
63 | url('fonts/pt-serif-v8-latin-italic.svg#PTSerif') format('svg'); /* Legacy iOS */
64 | }
65 |
66 | /* work-sans-700 - latin */
67 | @font-face {
68 | font-family: 'Work Sans';
69 | font-style: normal;
70 | font-weight: 700;
71 | src: url('fonts/work-sans-v2-latin-700.eot'); /* IE9 Compat Modes */
72 | src: url('fonts/work-sans-v2-latin-700.eot?#iefix') format('embedded-opentype'), /* IE6-IE8 */
73 | url('fonts/work-sans-v2-latin-700.woff2') format('woff2'), /* Super Modern Browsers */
74 | url('fonts/work-sans-v2-latin-700.woff') format('woff'), /* Modern Browsers */
75 | url('fonts/work-sans-v2-latin-700.ttf') format('truetype'), /* Safari, Android, iOS */
76 | url('fonts/work-sans-v2-latin-700.svg#WorkSans') format('svg'); /* Legacy iOS */
77 | }
78 |
79 |
--------------------------------------------------------------------------------
/doc/html_in/style.css:
--------------------------------------------------------------------------------
1 | @import url('https://fonts.googleapis.com/css?family=PT+Serif:400,400i,700|Work+Sans:700|Fira+Mono:400,500');
2 |
3 | * {
4 | margin: 0;
5 | padding: 0;
6 | box-sizing: border-box;
7 | }
8 |
9 | body {
10 | font-family: 'PT Serif', Utopia, Georgia, Times, 'Apple Symbols', serif;
11 | line-height: 140%;
12 | color: #333;
13 | font-size: 18px;
14 | }
15 |
16 | #container {
17 | width: 850px;
18 | margin: 18px auto;
19 | }
20 |
21 | .bar {
22 | display: block;
23 | width: 100%;
24 | background-color: #ceb;
25 | box-shadow: 0px 0px 15px 1px #ddd;
26 | }
27 |
28 | .bar > nav {
29 | display: flex;
30 | justify-content: space-between;
31 | width: 850px;
32 | margin: 0 auto;
33 | }
34 |
35 | footer.bar > nav {
36 | justify-content: center;
37 | }
38 |
39 | .bar > nav > a {
40 | display: block;
41 | padding: 2px 0 4px 0;
42 | color: #152;
43 | }
44 |
45 | #version {
46 | text-align: right;
47 | font-size: 12px;
48 | font-family: 'Fira Mono', monospace;
49 | padding-right: 5px;
50 | }
51 |
52 | #version a {
53 | color: #333;
54 | }
55 |
56 | h1, h2, h3, h4, h5, h6 {
57 | font-family: 'Work Sans', Futura, Helvetica, Arial, sans-serif;
58 | color: #222;
59 | line-height: 100%;
60 | margin-top: 32px;
61 | }
62 |
63 | h2 a, h3 a, h4 a {
64 | color: inherit;
65 | text-decoration: none;
66 | }
67 |
68 | h2 a::before, h3 a::before, h4 a::before {
69 | content: '#';
70 | color: #fff;
71 | font-weight: normal;
72 | transition: color 0.15s ease;
73 | display: block;
74 | float: left;
75 | width: 32px;
76 | margin-left: -32px;
77 | }
78 |
79 | h2 a:hover::before, h3 a:hover::before, h4 a:hover::before {
80 | color: #ccc;
81 | }
82 |
83 | h1 {
84 | margin-top: 0;
85 | font-size: 38px;
86 | border-bottom: 3px solid #e7c;
87 | display: inline-block;
88 | }
89 |
90 | h2 {
91 | font-size: 26px;
92 | }
93 |
94 | p {
95 | margin-top: 18px;
96 | }
97 |
98 | ul, ol {
99 | margin-top: 18px;
100 | margin-left: 36px;
101 | }
102 |
103 | hr {
104 | border: none;
105 | border-bottom: 1px solid #888;
106 | }
107 |
108 | a {
109 | color: #26d;
110 | }
111 |
112 | code {
113 | font-family: 'Fira Mono', monospace;
114 | font-size: inherit;
115 | }
116 |
117 | p code, h1 code, h2 code, h3 code, h4 code, h5 code, h6 code {
118 | white-space: nowrap;
119 | background-color: #eff4ea;
120 | padding: 1px 3px;
121 | }
122 |
123 | h1 code, h2 code, h3 code, h4 code, h5 code, h6 code {
124 | font-weight: normal;
125 | }
126 |
127 | kbd {
128 | font-family: 'Fira Mono', monospace;
129 | border-radius: 3px;
130 | padding: 2px 3px;
131 | box-shadow: 1px 1px 1px #777;
132 | margin: 2px;
133 | font-size: 14px;
134 | background: #f7f7f7;
135 | font-weight: 500;
136 | color: #555;
137 | white-space: nowrap;
138 | }
139 |
140 | h1 kbd, h2 kbd, h3 kbd, h4 kbd, h5 kbd, h6 kbd {
141 | font-size: 80%;
142 | }
143 |
144 | .diff code {
145 | font-size: 14px;
146 | line-height: 20px;
147 | background-color: none;
148 | padding: 0;
149 | margin-bottom: 18px;
150 | white-space: inherit;
151 | }
152 |
153 | .diff pre {
154 | background-color: #fffcfa;
155 | padding: 5px 0;
156 | }
157 |
158 | .diff {
159 | border: 1px solid #ede7e3;
160 | border-radius: 3px;
161 | margin-top: 18px;
162 | }
163 |
164 | .diff .diff-header {
165 | display: flex;
166 | justify-content: space-between;
167 | padding: 0 5px;
168 | background-color: #ede7e3;
169 | font-size: 16px;
170 | color: #666;
171 | }
172 |
173 | .diff .step-number {
174 | font-weight: bold;
175 | }
176 |
177 | .diff .step-filename {
178 | font-weight: bold;
179 | }
180 |
181 | .diff .step-name {
182 | font-family: 'Fira Mono', monospace;
183 | font-size: 12px;
184 | }
185 |
186 | .diff .diff-header a {
187 | text-decoration: none;
188 | color: #666;
189 | }
190 |
191 | .diff .diff-header a:hover {
192 | text-decoration: underline;
193 | }
194 |
195 | .diff .step-filename a {
196 | text-decoration: underline;
197 | }
198 |
199 | .diff .diff-footer {
200 | background-color: #ede7e3;
201 | }
202 |
203 | .diff .diff-footer > div {
204 | font-size: 12px;
205 | line-height: 16px;
206 | height: 16px;
207 | padding-right: 5px;
208 | text-align: right;
209 | }
210 |
211 | .diff .diff-tag-c0 {
212 | color: #b33;
213 | }
214 |
215 | .diff .diff-tag-c1 {
216 | color: #33b;
217 | }
218 |
219 | .diff .diff-tag-c2 {
220 | color: #3b3;
221 | }
222 |
223 | .diff .diff-tag-c-unknown {
224 | color: #a62;
225 | }
226 |
227 | .diff .line {
228 | display: block;
229 | height: 20px;
230 | padding: 0 5px;
231 | position: relative;
232 | }
233 |
234 | .diff .line.folded {
235 | background-color: #eef;
236 | opacity: 0.5;
237 | }
238 |
239 | .diff ins.line {
240 | background-color: #ffd;
241 | text-decoration: none;
242 | }
243 |
244 | .diff ins.line::after {
245 | display: block;
246 | content: '';
247 | width: 20px;
248 | height: 20px;
249 | background-image: url('i/arrow.png');
250 | background-size: 20px 20px;
251 | position: absolute;
252 | right: -24px;
253 | top: 0;
254 | }
255 |
256 | .diff del.line {
257 | background-color: #fdd;
258 | text-decoration: line-through;
259 | }
260 |
261 | .diff del.line::after {
262 | display: block;
263 | content: '';
264 | width: 20px;
265 | height: 20px;
266 | background-image: url('i/x.png');
267 | background-size: 20px 20px;
268 | position: absolute;
269 | right: -24px;
270 | top: 0;
271 | }
272 |
273 | @media screen and (max-width: 850px) {
274 | #container {
275 | width: auto;
276 | margin: 18px 0;
277 | padding: 0 5px;
278 | }
279 |
280 | .bar > nav {
281 | width: auto;
282 | margin: 0;
283 | padding: 0 5px;
284 | }
285 |
286 | .highlight {
287 | overflow-x: scroll;
288 | }
289 |
290 | .diff .line {
291 | width: 850px;
292 | }
293 |
294 | .diff ins.line::after, .diff del.line::after {
295 | display: none;
296 | }
297 | }
298 |
299 |
--------------------------------------------------------------------------------
/doc/01.aPasswordGenerator.md:
--------------------------------------------------------------------------------
1 | # A password generator
2 |
3 | Create a file named `pass` and type the following code into it.
4 |
5 | {{correct-horse-battery-staple}}
6 |
7 | To run this program, you need to make it e**x**ecutable using the command
8 | `chmod +x pass`. Then you can run it by typing `./pass` and pressing
9 | Enter.
10 |
11 | It prints out a password when you run it. It prints out the same password every
12 | time, but we'll fix that soon enough.
13 |
14 | The first line (`#!/usr/bin/env bash`) is called a
15 | [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) line. (`#` is a hash
16 | character, and `!` is a bang character, so together they form a hash-bang, or
17 | shebang for short.) The shebang line allows you to run scripts the same way you
18 | run binaries, so you can type `./pass` instead of `bash pass`. When the OS
19 | goes to execute a file that begins with `#!`, it runs the program that comes
20 | after the `#!` instead, and passes the file to that program as an argument. So
21 | if the `pass` script began with `#!/bin/bash`, it would be executed using
22 | `/bin/bash pass`.
23 |
24 | However, the `bash` program might not be located at `/bin/bash` on all systems.
25 | To make `pass` more portable, the `env` program is used. `env` is a program
26 | that runs the given command, optionally in a modified **env**ironment. It is
27 | used in shebang lines because it runs commands similar to how commands are run
28 | on the shell: it looks in your `$PATH` to locate the command you gave. So with
29 | a shebang line of `#!/usr/bin/env bash`, the `bash` command will be located
30 | properly, wherever it may be on your system.
31 |
32 | The reason you can't use something like `#!bash`, and expect it to use `$PATH`
33 | to find `bash` like a shell command would, is that shebang scripts are
34 | [handled by the OS](https://lwn.net/Articles/630727/) at a very
35 | [low level](http://lxr.free-electrons.com/source/fs/binfmt_script.c?v=3.18).
36 |
37 | `bash` stands for **B**ourne-**a**gain **sh**ell, which was written to replace
38 | the [Bourne shell](https://en.wikipedia.org/wiki/Bourne_shell) (`sh`). `bash`
39 | is very widely available, and is the default shell on most Unix systems.
40 |
41 | So that's line 1.
42 |
43 | Moving on to line 3, we have an `echo` command. `echo` is a
44 | program that just prints out the command line arguments it is given. We give it
45 | a quoted argument. The shell
46 | [removes the quotes](https://www.gnu.org/software/bash/manual/html_node/Quote-Removal.html)
47 | before passing the argument to `echo`, and `echo` prints the password to the
48 | standard output.
49 |
50 | ## Variables
51 |
52 | Let's try assigning the password to a variable, and printing out the variable.
53 |
54 | {{variable}}
55 |
56 | When the first word of a line contains an `=` character, it is interpreted as
57 | an assignment statement instead of a command. There must not be any whitespace
58 | around the `=`. If you wrote `pass = "correcthorsebatterystaple"`, then Bash
59 | would try to execute a program named `pass` and pass it the arguments `=` and
60 | `correcthorsebatterystaple`.
61 |
62 | Once again, the quotes around `"correcthorsebatterystaple"` are not necessary.
63 | The quotes are removed before assigning the value to the variable.
64 |
65 | When a `$` precedes a variable name, as in `echo "$pass"`, the variable is
66 | expanded to whatever its value is. It's good practice to put double quotes
67 | around variable expansions, as it ensures that the expanded value is passed as
68 | a single argument. If `$pass` contained the value `a b c`, then `echo $pass`
69 | would expand to `echo a b c`, while `echo "$pass"` would expand to
70 | `echo "a b c"` which is usually what you want.
71 |
72 | ## Generating a random string
73 |
74 | Now let's actually generate a random password each time the program is run.
75 |
76 | {{urandom}}
77 |
78 | There's a lot going on in this one-liner. Let's see how to build this one-liner
79 | incrementally, using the shell interactively:
80 |
81 | ```bash
82 | $ cat /dev/urandom
83 | ```
84 |
85 | (The `$` is just a prompt to show that the command is to be typed at the shell,
86 | so for this example you want to type `cat /dev/urandom`.)
87 |
88 | [`/dev/random`](https://en.wikipedia.org/wiki//dev/random) is a special device
89 | file that produces an infinite stream of random bytes. If it doesn't have
90 | enough environmental noise to generate cryptographically secure random numbers,
91 | then it will [block](https://en.wikipedia.org/wiki/Blocking_(computing)) until
92 | until it does. `/dev/urandom` is an alternative to `/dev/random` that never
93 | blocks, at the cost of being possibly slightly less random. It is still
94 | intended to be used for cryptographic purposes though, so `pass` uses
95 | `/dev/urandom` as its source of randomness.
96 |
97 | You'll get a lot of garbage output from the above command because a lot of the
98 | bytes won't be printable ASCII characters. Press Ctrl-C to make it
99 | stop.
100 |
101 | ```bash
102 | $ LC_ALL=C tr -dc "[:graph:]" < /dev/urandom
103 | ```
104 |
105 | This command uses [`tr`](https://en.wikipedia.org/wiki/Tr_(Unix)) to remove all
106 | the non-**graph**ical characters from the random stream of bytes. A graphical
107 | character is any ordinary ASCII character that isn't whitespace. `tr` is
108 | typically used to **tr**anslate characters, as in `tr 013 ole <<. All Rights Reserved.
2 |
3 | This program is free software; you can redistribute it and/or modify
4 | it under the terms of the GNU General Public License as published by
5 | the Free Software Foundation; either version 2 of the License, or
6 | (at your option) any later version.
7 |
8 | This program is distributed in the hope that it will be useful,
9 | but WITHOUT ANY WARRANTY; without even the implied warranty of
10 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 | GNU General Public License for more details.
12 |
13 |
14 |
15 | GNU GENERAL PUBLIC LICENSE
16 | Version 2, June 1991
17 |
18 | Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
19 | 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
20 | Everyone is permitted to copy and distribute verbatim copies
21 | of this license document, but changing it is not allowed.
22 |
23 | Preamble
24 |
25 | The licenses for most software are designed to take away your
26 | freedom to share and change it. By contrast, the GNU General Public
27 | License is intended to guarantee your freedom to share and change free
28 | software--to make sure the software is free for all its users. This
29 | General Public License applies to most of the Free Software
30 | Foundation's software and to any other program whose authors commit to
31 | using it. (Some other Free Software Foundation software is covered by
32 | the GNU Lesser General Public License instead.) You can apply it to
33 | your programs, too.
34 |
35 | When we speak of free software, we are referring to freedom, not
36 | price. Our General Public Licenses are designed to make sure that you
37 | have the freedom to distribute copies of free software (and charge for
38 | this service if you wish), that you receive source code or can get it
39 | if you want it, that you can change the software or use pieces of it
40 | in new free programs; and that you know you can do these things.
41 |
42 | To protect your rights, we need to make restrictions that forbid
43 | anyone to deny you these rights or to ask you to surrender the rights.
44 | These restrictions translate to certain responsibilities for you if you
45 | distribute copies of the software, or if you modify it.
46 |
47 | For example, if you distribute copies of such a program, whether
48 | gratis or for a fee, you must give the recipients all the rights that
49 | you have. You must make sure that they, too, receive or can get the
50 | source code. And you must show them these terms so they know their
51 | rights.
52 |
53 | We protect your rights with two steps: (1) copyright the software, and
54 | (2) offer you this license which gives you legal permission to copy,
55 | distribute and/or modify the software.
56 |
57 | Also, for each author's protection and ours, we want to make certain
58 | that everyone understands that there is no warranty for this free
59 | software. If the software is modified by someone else and passed on, we
60 | want its recipients to know that what they have is not the original, so
61 | that any problems introduced by others will not reflect on the original
62 | authors' reputations.
63 |
64 | Finally, any free program is threatened constantly by software
65 | patents. We wish to avoid the danger that redistributors of a free
66 | program will individually obtain patent licenses, in effect making the
67 | program proprietary. To prevent this, we have made it clear that any
68 | patent must be licensed for everyone's free use or not licensed at all.
69 |
70 | The precise terms and conditions for copying, distribution and
71 | modification follow.
72 |
73 | GNU GENERAL PUBLIC LICENSE
74 | TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
75 |
76 | 0. This License applies to any program or other work which contains
77 | a notice placed by the copyright holder saying it may be distributed
78 | under the terms of this General Public License. The "Program", below,
79 | refers to any such program or work, and a "work based on the Program"
80 | means either the Program or any derivative work under copyright law:
81 | that is to say, a work containing the Program or a portion of it,
82 | either verbatim or with modifications and/or translated into another
83 | language. (Hereinafter, translation is included without limitation in
84 | the term "modification".) Each licensee is addressed as "you".
85 |
86 | Activities other than copying, distribution and modification are not
87 | covered by this License; they are outside its scope. The act of
88 | running the Program is not restricted, and the output from the Program
89 | is covered only if its contents constitute a work based on the
90 | Program (independent of having been made by running the Program).
91 | Whether that is true depends on what the Program does.
92 |
93 | 1. You may copy and distribute verbatim copies of the Program's
94 | source code as you receive it, in any medium, provided that you
95 | conspicuously and appropriately publish on each copy an appropriate
96 | copyright notice and disclaimer of warranty; keep intact all the
97 | notices that refer to this License and to the absence of any warranty;
98 | and give any other recipients of the Program a copy of this License
99 | along with the Program.
100 |
101 | You may charge a fee for the physical act of transferring a copy, and
102 | you may at your option offer warranty protection in exchange for a fee.
103 |
104 | 2. You may modify your copy or copies of the Program or any portion
105 | of it, thus forming a work based on the Program, and copy and
106 | distribute such modifications or work under the terms of Section 1
107 | above, provided that you also meet all of these conditions:
108 |
109 | a) You must cause the modified files to carry prominent notices
110 | stating that you changed the files and the date of any change.
111 |
112 | b) You must cause any work that you distribute or publish, that in
113 | whole or in part contains or is derived from the Program or any
114 | part thereof, to be licensed as a whole at no charge to all third
115 | parties under the terms of this License.
116 |
117 | c) If the modified program normally reads commands interactively
118 | when run, you must cause it, when started running for such
119 | interactive use in the most ordinary way, to print or display an
120 | announcement including an appropriate copyright notice and a
121 | notice that there is no warranty (or else, saying that you provide
122 | a warranty) and that users may redistribute the program under
123 | these conditions, and telling the user how to view a copy of this
124 | License. (Exception: if the Program itself is interactive but
125 | does not normally print such an announcement, your work based on
126 | the Program is not required to print an announcement.)
127 |
128 | These requirements apply to the modified work as a whole. If
129 | identifiable sections of that work are not derived from the Program,
130 | and can be reasonably considered independent and separate works in
131 | themselves, then this License, and its terms, do not apply to those
132 | sections when you distribute them as separate works. But when you
133 | distribute the same sections as part of a whole which is a work based
134 | on the Program, the distribution of the whole must be on the terms of
135 | this License, whose permissions for other licensees extend to the
136 | entire whole, and thus to each and every part regardless of who wrote it.
137 |
138 | Thus, it is not the intent of this section to claim rights or contest
139 | your rights to work written entirely by you; rather, the intent is to
140 | exercise the right to control the distribution of derivative or
141 | collective works based on the Program.
142 |
143 | In addition, mere aggregation of another work not based on the Program
144 | with the Program (or with a work based on the Program) on a volume of
145 | a storage or distribution medium does not bring the other work under
146 | the scope of this License.
147 |
148 | 3. You may copy and distribute the Program (or a work based on it,
149 | under Section 2) in object code or executable form under the terms of
150 | Sections 1 and 2 above provided that you also do one of the following:
151 |
152 | a) Accompany it with the complete corresponding machine-readable
153 | source code, which must be distributed under the terms of Sections
154 | 1 and 2 above on a medium customarily used for software interchange; or,
155 |
156 | b) Accompany it with a written offer, valid for at least three
157 | years, to give any third party, for a charge no more than your
158 | cost of physically performing source distribution, a complete
159 | machine-readable copy of the corresponding source code, to be
160 | distributed under the terms of Sections 1 and 2 above on a medium
161 | customarily used for software interchange; or,
162 |
163 | c) Accompany it with the information you received as to the offer
164 | to distribute corresponding source code. (This alternative is
165 | allowed only for noncommercial distribution and only if you
166 | received the program in object code or executable form with such
167 | an offer, in accord with Subsection b above.)
168 |
169 | The source code for a work means the preferred form of the work for
170 | making modifications to it. For an executable work, complete source
171 | code means all the source code for all modules it contains, plus any
172 | associated interface definition files, plus the scripts used to
173 | control compilation and installation of the executable. However, as a
174 | special exception, the source code distributed need not include
175 | anything that is normally distributed (in either source or binary
176 | form) with the major components (compiler, kernel, and so on) of the
177 | operating system on which the executable runs, unless that component
178 | itself accompanies the executable.
179 |
180 | If distribution of executable or object code is made by offering
181 | access to copy from a designated place, then offering equivalent
182 | access to copy the source code from the same place counts as
183 | distribution of the source code, even though third parties are not
184 | compelled to copy the source along with the object code.
185 |
186 | 4. You may not copy, modify, sublicense, or distribute the Program
187 | except as expressly provided under this License. Any attempt
188 | otherwise to copy, modify, sublicense or distribute the Program is
189 | void, and will automatically terminate your rights under this License.
190 | However, parties who have received copies, or rights, from you under
191 | this License will not have their licenses terminated so long as such
192 | parties remain in full compliance.
193 |
194 | 5. You are not required to accept this License, since you have not
195 | signed it. However, nothing else grants you permission to modify or
196 | distribute the Program or its derivative works. These actions are
197 | prohibited by law if you do not accept this License. Therefore, by
198 | modifying or distributing the Program (or any work based on the
199 | Program), you indicate your acceptance of this License to do so, and
200 | all its terms and conditions for copying, distributing or modifying
201 | the Program or works based on it.
202 |
203 | 6. Each time you redistribute the Program (or any work based on the
204 | Program), the recipient automatically receives a license from the
205 | original licensor to copy, distribute or modify the Program subject to
206 | these terms and conditions. You may not impose any further
207 | restrictions on the recipients' exercise of the rights granted herein.
208 | You are not responsible for enforcing compliance by third parties to
209 | this License.
210 |
211 | 7. If, as a consequence of a court judgment or allegation of patent
212 | infringement or for any other reason (not limited to patent issues),
213 | conditions are imposed on you (whether by court order, agreement or
214 | otherwise) that contradict the conditions of this License, they do not
215 | excuse you from the conditions of this License. If you cannot
216 | distribute so as to satisfy simultaneously your obligations under this
217 | License and any other pertinent obligations, then as a consequence you
218 | may not distribute the Program at all. For example, if a patent
219 | license would not permit royalty-free redistribution of the Program by
220 | all those who receive copies directly or indirectly through you, then
221 | the only way you could satisfy both it and this License would be to
222 | refrain entirely from distribution of the Program.
223 |
224 | If any portion of this section is held invalid or unenforceable under
225 | any particular circumstance, the balance of the section is intended to
226 | apply and the section as a whole is intended to apply in other
227 | circumstances.
228 |
229 | It is not the purpose of this section to induce you to infringe any
230 | patents or other property right claims or to contest validity of any
231 | such claims; this section has the sole purpose of protecting the
232 | integrity of the free software distribution system, which is
233 | implemented by public license practices. Many people have made
234 | generous contributions to the wide range of software distributed
235 | through that system in reliance on consistent application of that
236 | system; it is up to the author/donor to decide if he or she is willing
237 | to distribute software through any other system and a licensee cannot
238 | impose that choice.
239 |
240 | This section is intended to make thoroughly clear what is believed to
241 | be a consequence of the rest of this License.
242 |
243 | 8. If the distribution and/or use of the Program is restricted in
244 | certain countries either by patents or by copyrighted interfaces, the
245 | original copyright holder who places the Program under this License
246 | may add an explicit geographical distribution limitation excluding
247 | those countries, so that distribution is permitted only in or among
248 | countries not thus excluded. In such case, this License incorporates
249 | the limitation as if written in the body of this License.
250 |
251 | 9. The Free Software Foundation may publish revised and/or new versions
252 | of the General Public License from time to time. Such new versions will
253 | be similar in spirit to the present version, but may differ in detail to
254 | address new problems or concerns.
255 |
256 | Each version is given a distinguishing version number. If the Program
257 | specifies a version number of this License which applies to it and "any
258 | later version", you have the option of following the terms and conditions
259 | either of that version or of any later version published by the Free
260 | Software Foundation. If the Program does not specify a version number of
261 | this License, you may choose any version ever published by the Free Software
262 | Foundation.
263 |
264 | 10. If you wish to incorporate parts of the Program into other free
265 | programs whose distribution conditions are different, write to the author
266 | to ask for permission. For software which is copyrighted by the Free
267 | Software Foundation, write to the Free Software Foundation; we sometimes
268 | make exceptions for this. Our decision will be guided by the two goals
269 | of preserving the free status of all derivatives of our free software and
270 | of promoting the sharing and reuse of software generally.
271 |
272 | NO WARRANTY
273 |
274 | 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
275 | FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
276 | OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
277 | PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
278 | OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
279 | MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
280 | TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
281 | PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
282 | REPAIR OR CORRECTION.
283 |
284 | 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
285 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
286 | REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
287 | INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
288 | OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
289 | TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
290 | YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
291 | PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
292 | POSSIBILITY OF SUCH DAMAGES.
293 |
294 | END OF TERMS AND CONDITIONS
295 |
296 | How to Apply These Terms to Your New Programs
297 |
298 | If you develop a new program, and you want it to be of the greatest
299 | possible use to the public, the best way to achieve this is to make it
300 | free software which everyone can redistribute and change under these terms.
301 |
302 | To do so, attach the following notices to the program. It is safest
303 | to attach them to the start of each source file to most effectively
304 | convey the exclusion of warranty; and each file should have at least
305 | the "copyright" line and a pointer to where the full notice is found.
306 |
307 |
308 | Copyright (C)
309 |
310 | This program is free software; you can redistribute it and/or modify
311 | it under the terms of the GNU General Public License as published by
312 | the Free Software Foundation; either version 2 of the License, or
313 | (at your option) any later version.
314 |
315 | This program is distributed in the hope that it will be useful,
316 | but WITHOUT ANY WARRANTY; without even the implied warranty of
317 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
318 | GNU General Public License for more details.
319 |
320 | You should have received a copy of the GNU General Public License along
321 | with this program; if not, write to the Free Software Foundation, Inc.,
322 | 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
323 |
324 | Also add information on how to contact you by electronic and paper mail.
325 |
326 | If the program is interactive, make it output a short notice like this
327 | when it starts in an interactive mode:
328 |
329 | Gnomovision version 69, Copyright (C) year name of author
330 | Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
331 | This is free software, and you are welcome to redistribute it
332 | under certain conditions; type `show c' for details.
333 |
334 | The hypothetical commands `show w' and `show c' should show the appropriate
335 | parts of the General Public License. Of course, the commands you use may
336 | be called something other than `show w' and `show c'; they could even be
337 | mouse-clicks or menu items--whatever suits your program.
338 |
339 | You should also get your employer (if you work as a programmer) or your
340 | school, if any, to sign a "copyright disclaimer" for the program, if
341 | necessary. Here is a sample; alter the names:
342 |
343 | Yoyodyne, Inc., hereby disclaims all copyright interest in the program
344 | `Gnomovision' (which makes passes at compilers) written by James Hacker.
345 |
346 | , 1 April 1989
347 | Ty Coon, President of Vice
348 |
349 | This General Public License does not permit incorporating your program into
350 | proprietary programs. If your program is a subroutine library, you may
351 | consider it more useful to permit linking proprietary applications with the
352 | library. If this is what you want to do, use the GNU Lesser General
353 | Public License instead of this License.
354 |
355 |
356 |
--------------------------------------------------------------------------------
/doc/html_in/fonts/fira-mono-v5-latin-500.svg:
--------------------------------------------------------------------------------
1 |
2 |
3 |
320 |
--------------------------------------------------------------------------------
/doc/html_in/fonts/fira-mono-v5-latin-regular.svg:
--------------------------------------------------------------------------------
1 |
2 |
3 |
323 |
--------------------------------------------------------------------------------
/doc/html_in/fonts/work-sans-v2-latin-700.svg:
--------------------------------------------------------------------------------
1 |
2 |
3 |
331 |
--------------------------------------------------------------------------------