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 -