mfa

Check out the source code here - + git.chudnick.com/mfa

+ +

mfa is a system for out-of-band multi-factor authentication with PAM. + My original reason for working on this was to get MFA functionality for a Postfix/Dovecot + mail server that uses PAM for authentication. Solutions such as pam_oath are not feasible + for this purpose because a mail client has no way of exposing an interface for the oath + challenge-response. Therefore a way to circumvent the original application to get the request + to the user is needed, which is what mfa does.

+ +

The design of mfa is not novel, it works the same way as Cisco's Duo. Duo does have open + source modules for achieving this objective, but all the authentication requests are + sent back to their proprietary "cloud" service. I'm sure that most free software + enthusiasts see this as a major red flag, especially for small personal use cases.

+ +

Design

+ +

mfa is primarily composed of three parts - the server, the client, and the PAM module. + The server listens for connections from both clients and PAM modules. The server receives a + request from a PAM module that includes the username of the user attempting to authenticate, + the hostname of the computer, and the service being accessed. The server then correlates the + combination of user, host, and service to a particular client, and attempts to push a request. + The server will then evaluate the client's response, and either return to the PAM module that + the user is authenticated or denied.

+ +

The server itself consists of two parts that I've called mfad and + mfac. mfad is the program responsible for doing what I've described above. + mfac is a command line utility that the administrator uses to configure the server. mfac is used + to enroll clients in the system and to provision applications. A client is enrolled by using the + --add-client option and providing an alias for that user. The server then assigns that user an + identifying key that is used to connect and a TOTP secret key. With the client enrolled, the + administrator can then assign applications to that client. With the --add-app command, the + administrator ties a username, hostname, and service combination to a client alias, so that + when that combination is seen the server knows who to ask for authentication. The administrator + also identifies which MFA methods are valid for this combination (currently either or both of + push and/or totp). The example below shows the process of enrolling a new client called + 'tux' and then provisioning MFA for SSH attempts to tux@linux.example.org.

+ +

# Enroll a client named tux
+mfac --add-client tux
+alias: tux
+client key: VA32LB3SF2HG2FDWJS5XIOFVWTMBQYRSQ3PK3OOPA3FBIQMSMJZCXYJQCYKYUWUU
+totp secret: TGGG3QCXA4MR2S2X6B33GSYN
+uri: otpauth://totp/tux%40mfad?secret=TGGG3QCXA4MR2S2X6B33GSYN
+
+# Provision MFA for SSH tux@linux.example.org allowing for both push authentication or TOTP
+mfac --add-app --user tux --host linux.example.org --service sshd --alias tux --methods push totp
+

+ +

The PAM module of mfa also consists of two parts: the actual PAM module + pam_mfa.so that gets called in the PAM stack and a helper + program that interacts with mfad. The job of pam_mfa.so is to retrieve the + necessary information (user and service) from PAM and then invoke the helper + program with that data. It then waits for the MFA process to complete, retrieves + the result, and returns either success or failure to the PAM stack. The helper + program initiates a connetion to mfad when run and then passes username, hostname, + and service information to the server. It too receives a success or failure response + and then relays that information to the PAM module. Here is an example of using + pam_mfa.so in the PAM stack for sshd.

+ +

/etc/pam.d/sshd 
+auth requisite pam_mfa.so

+ +

The client program is what the end user interacts with to provide authentication responses. + Currently it is only a very simple terminal program but expanding on this is high on the + TODO list. The client opens a connection to the server and identifies itself with the client + key that was generated during enrollment. The client waits for a prompt from the server, and + when it receives one, informs the user. The client receives the users input and sends it back + to the server. The client performs this loop continuously until it is closed.

+ +

clibrary

+ +

Check out the source code here - + git.chudnick.com/clibrary

+ +

mail-tools

+ git.chudnick.com/mail-tools +

+ +

deploy-scripts

+ git.chudnick.com/deploy-scripts +

+ +

server-scripts

+ git.chudnick.com/server-scripts +