summaryrefslogtreecommitdiff
path: root/projects
diff options
context:
space:
mode:
authorSam Chudnick <sam@chudnick.com>2022-12-08 20:44:37 -0500
committerSam Chudnick <sam@chudnick.com>2022-12-08 20:44:37 -0500
commit3fb2b9563d9b58a9683808c6620832dc71f76b20 (patch)
tree9c208db70957ba26fbcc2d87f3b91df7117617c8 /projects
Initial commit
Diffstat (limited to 'projects')
-rw-r--r--projects/mfa.html150
-rw-r--r--projects/template.html107
2 files changed, 257 insertions, 0 deletions
diff --git a/projects/mfa.html b/projects/mfa.html
new file mode 100644
index 0000000..2a89856
--- /dev/null
+++ b/projects/mfa.html
@@ -0,0 +1,150 @@
1<!DOCTYPE html>
2<html lang=en>
3 <head>
4 <title></title>
5 <meta charset="utf-8"/>
6 <link rel="shortcut icon" href="favicon.ico"/>
7 <link rel='stylesheet' type='text/css' href='style.css'/>
8 <meta name="viewport" content="width=device-width, initial-scale=1">
9 </head>
10<body>
11 <header><h1 class=pagetop>Projects</h1></header>
12 <main>
13 <h2>mfa</h2>
14 <p><em>Check out the source code here - </em>
15 <a href=https://git.chudnick.com/mfa>git.chudnick.com/mfa</a></p>
16
17 <p><strong>mfa</strong> is a system for out-of-band multi-factor
18 authentication with PAM.
19 My original reason for working on this was to get MFA functionality for
20 a Postfix/Dovecot mail server that uses PAM for authentication.
21 Solutions such as pam_oath are not feasible
22 for this purpose because a mail client has no way of exposing an
23 interface for the oath challenge-response.
24 Therefore a way to circumvent the original application to get the request
25 to the user is needed, which is what mfa does.</p>
26
27 <p>The design of mfa is not novel, it works the same way as Cisco's Duo.
28 Duo does have open source modules for achieving this objective, but all
29 the authentication requests are
30 sent back to their proprietary "cloud" service. I'm sure that most
31 free software
32 enthusiasts see this as a major red flag, especially for small personal
33 use cases.</p>
34
35 <h3>Design</h3>
36
37 <p>mfa is primarily composed of three parts - the server, the client,
38 and the PAM module.
39 The server listens for connections from both clients and PAM
40 modules. The server receives a
41 request from a PAM module that includes the username of the user
42 attempting to authenticate,
43 the hostname of the computer, and the service being accessed. The
44 server then correlates the
45 combination of user, host, and service to a particular client, and
46 attempts to push a request.
47 The server will then evaluate the client's response, and either
48 return to the PAM module that
49 the user is authenticated or denied.</p>
50
51 <p>The server itself consists of two parts that I've called
52 <strong>mfad</strong> and
53 <strong>mfac</strong>. mfad is the program responsible for doing
54 what I've described above.
55 mfac is a command line utility that the administrator uses to
56 configure the server. mfac is used
57 to enroll clients in the system and to provision applications. A
58 client is enrolled by using the
59 --add-client option and providing an alias for that user. The
60 server then assigns that user an
61 identifying key that is used to connect and a TOTP secret key. With
62 the client enrolled, the
63 administrator can then assign applications to that client. With the
64 --add-app command, the
65 administrator ties a username, hostname, and service combination to
66 a client alias, so that
67 when that combination is seen the server knows who to ask for
68 authentication. The administrator
69 also identifies which MFA methods are valid for this combination
70 (currently either or both of
71 push and/or totp). The example below shows the process of
72 enrolling a new client called
73 'tux' and then provisioning MFA for SSH attempts to
74 tux@linux.example.org.</p>
75
76 <pre><code><em># Enroll a client named tux</em>
77mfac --add-client tux
78alias: tux
79client key: VA32LB3SF2HG2FDWJS5XIOFVWTMBQYRSQ3PK3OOPA3FBIQMSMJZCXYJQCYKYUWUU
80totp secret: TGGG3QCXA4MR2S2X6B33GSYN
81uri: otpauth://totp/tux%40mfad?secret=TGGG3QCXA4MR2S2X6B33GSYN
82
83<em># Provision MFA for SSH tux@linux.example.org allowing for both push
84authentication or TOTP</em>
85mfac --add-app --user tux --host linux.example.org --service sshd --alias tux
86--methods push totp
87 </code></pre>
88
89 <p>The PAM module of mfa also consists of two parts: the actual PAM
90 module
91 <strong>pam_mfa.so</strong> that gets called in the PAM stack and a
92 helper
93 program that interacts with mfad. The job of pam_mfa.so is to
94 retrieve the
95 necessary information (user and service) from PAM and then invoke
96 the helper
97 program with that data. It then waits for the MFA process to
98 complete, retrieves
99 the result, and returns either success or failure to the PAM stack.
100 The helper
101 program initiates a connetion to mfad when run and then passes
102 username, hostname,
103 and service information to the server. It too receives a success
104 or failure response
105 and then relays that information to the PAM module. Here is an
106 example of using
107 pam_mfa.so in the PAM stack for sshd.</p>
108
109 <pre><code><strong>/etc/pam.d/sshd</strong>
110auth requisite pam_mfa.so</code></pre>
111
112 <p>The client program is what the end user interacts with to
113 provide authentication responses.
114 Currently it is only a very simple terminal program but expanding
115 on this is high on the
116 TODO list. The client opens a connection to the server and
117 identifies itself with the client
118 key that was generated during enrollment. The client waits for a
119 prompt from the server, and
120 when it receives one, informs the user. The client receives the
121 users input and sends it back
122 to the server. The client performs this loop continuously until it
123 is closed.</p>
124
125 <h2>clibrary</h2>
126
127 <p><em>Check out the source code here -</em>
128 <a href=https://git.chudnick.com/clibrary>git.chudnick.com/clibrary</a></p>
129
130 <h2>mail-tools</h2>
131 <p>
132 <a href=https://git.chudnick.com/mail-tools>git.chudnick.com/mail-tools</a>
133 </p>
134
135 <h2>deploy-scripts</h2>
136 <p>
137 <a href=https://git.chudnick.com/deploy-scripts>
138 git.chudnick.com/deploy-scripts</a>
139 </p>
140
141 <h2>server-scripts</h2>
142 <p>
143 <a href=https://git.chudnick.com/server-scripts>
144 git.chudnick.com/server-scripts</a>
145 </p>
146 </main>
147 <footer><a href=index.html>www.chudnick.com</a></footer>
148</body>
149</html>
150
diff --git a/projects/template.html b/projects/template.html
new file mode 100644
index 0000000..77b6c6a
--- /dev/null
+++ b/projects/template.html
@@ -0,0 +1,107 @@
1<!DOCTYPE html>
2<html lang=en>
3 <head>
4 <title></title>
5 <meta charset="utf-8"/>
6 <link rel="shortcut icon" href="favicon.ico"/>
7 <link rel='stylesheet' type='text/css' href='style.css'/>
8 <meta name="viewport" content="width=device-width, initial-scale=1">
9 </head>
10<body>
11 <header><h1 class=pagetop>Projects</h1></header>
12 <main>
13 <h2>mfa</h2>
14 <p><em>Check out the source code here - </em>
15 <a href=https://git.chudnick.com/mfa>git.chudnick.com/mfa</a></p>
16
17 <p><strong>mfa</strong> is a system for out-of-band multi-factor authentication with PAM.
18 My original reason for working on this was to get MFA functionality for a Postfix/Dovecot
19 mail server that uses PAM for authentication. Solutions such as pam_oath are not feasible
20 for this purpose because a mail client has no way of exposing an interface for the oath
21 challenge-response. Therefore a way to circumvent the original application to get the request
22 to the user is needed, which is what mfa does.</p>
23
24 <p>The design of mfa is not novel, it works the same way as Cisco's Duo. Duo does have open
25 source modules for achieving this objective, but all the authentication requests are
26 sent back to their proprietary "cloud" service. I'm sure that most free software
27 enthusiasts see this as a major red flag, especially for small personal use cases.</p>
28
29 <h3>Design</h3>
30
31 <p>mfa is primarily composed of three parts - the server, the client, and the PAM module.
32 The server listens for connections from both clients and PAM modules. The server receives a
33 request from a PAM module that includes the username of the user attempting to authenticate,
34 the hostname of the computer, and the service being accessed. The server then correlates the
35 combination of user, host, and service to a particular client, and attempts to push a request.
36 The server will then evaluate the client's response, and either return to the PAM module that
37 the user is authenticated or denied.</p>
38
39 <p>The server itself consists of two parts that I've called <strong>mfad</strong> and
40 <strong>mfac</strong>. mfad is the program responsible for doing what I've described above.
41 mfac is a command line utility that the administrator uses to configure the server. mfac is used
42 to enroll clients in the system and to provision applications. A client is enrolled by using the
43 --add-client option and providing an alias for that user. The server then assigns that user an
44 identifying key that is used to connect and a TOTP secret key. With the client enrolled, the
45 administrator can then assign applications to that client. With the --add-app command, the
46 administrator ties a username, hostname, and service combination to a client alias, so that
47 when that combination is seen the server knows who to ask for authentication. The administrator
48 also identifies which MFA methods are valid for this combination (currently either or both of
49 push and/or totp). The example below shows the process of enrolling a new client called
50 'tux' and then provisioning MFA for SSH attempts to tux@linux.example.org.</p>
51
52 <pre><code><em># Enroll a client named tux</em>
53mfac --add-client tux
54alias: tux
55client key: VA32LB3SF2HG2FDWJS5XIOFVWTMBQYRSQ3PK3OOPA3FBIQMSMJZCXYJQCYKYUWUU
56totp secret: TGGG3QCXA4MR2S2X6B33GSYN
57uri: otpauth://totp/tux%40mfad?secret=TGGG3QCXA4MR2S2X6B33GSYN
58
59<em># Provision MFA for SSH tux@linux.example.org allowing for both push authentication or TOTP</em>
60mfac --add-app --user tux --host linux.example.org --service sshd --alias tux --methods push totp
61 </code></pre>
62
63 <p>The PAM module of mfa also consists of two parts: the actual PAM module
64 <strong>pam_mfa.so</strong> that gets called in the PAM stack and a helper
65 program that interacts with mfad. The job of pam_mfa.so is to retrieve the
66 necessary information (user and service) from PAM and then invoke the helper
67 program with that data. It then waits for the MFA process to complete, retrieves
68 the result, and returns either success or failure to the PAM stack. The helper
69 program initiates a connetion to mfad when run and then passes username, hostname,
70 and service information to the server. It too receives a success or failure response
71 and then relays that information to the PAM module. Here is an example of using
72 pam_mfa.so in the PAM stack for sshd.</p>
73
74 <pre><code><strong>/etc/pam.d/sshd</strong>
75auth requisite pam_mfa.so</code></pre>
76
77 <p>The client program is what the end user interacts with to provide authentication responses.
78 Currently it is only a very simple terminal program but expanding on this is high on the
79 TODO list. The client opens a connection to the server and identifies itself with the client
80 key that was generated during enrollment. The client waits for a prompt from the server, and
81 when it receives one, informs the user. The client receives the users input and sends it back
82 to the server. The client performs this loop continuously until it is closed.</p>
83
84 <h2>clibrary</h2>
85
86 <p><em>Check out the source code here -</em>
87 <a href=https://git.chudnick.com/clibrary>git.chudnick.com/clibrary</a></p>
88
89 <h2>mail-tools</h2>
90 <p>
91 <a href=https://git.chudnick.com/mail-tools>git.chudnick.com/mail-tools</a>
92 </p>
93
94 <h2>deploy-scripts</h2>
95 <p>
96 <a href=https://git.chudnick.com/deploy-scripts>git.chudnick.com/deploy-scripts</a>
97 </p>
98
99 <h2>server-scripts</h2>
100 <p>
101 <a href=https://git.chudnick.com/server-scripts>git.chudnick.com/server-scripts</a>
102 </p>
103 </main>
104 <footer><a href=index.html>www.chudnick.com</a></footer>
105</body>
106</html>
107