Pilot service for Yubikey two-factor authentication

November 10, 2015

A Yubikey Cosign authentication ‘factor’

Filed under: Pilot service for Yubikey two-factor authentication — idurkacz @ 3:34 pm
Tags: , , ,

Bearing the above specification in mind, we could now write a Cosign ‘factor’/authenticator which targets Yubikeys: we’d just need to feed it with the username, as well as the one-time-password produced by the Yubikey; have it perform the authentication – by slaving that off to a back-end authentication server; and then have it produce outputs as specified by the protocol.

However: we already have a Yubico PAM module which handles the details of the back-end authentication of the Yubikey one-time-password, and it turns out that a ‘universal Cosign PAM factor adaptor’ is available – see the relevant postings on the cosign-discuss mailing list. So we can use that instead.

The relevant C code file is now part of the Cosign download tarball, but it’s not autobuilt as part of the ./configure; make process. However:

  1. find it (as file pam_factor.c in the cgi/factors directory of the distribution);
  2. build it as follows:
    gcc -lpam -o pam_factor pam_factor.c
    
  3. copy the resulting binary factor to some suitable location, e.g., /usr/lib/cosign/factors; and
  4. edit /etc/cosign.conf to add the factor.

In the /etc/cosign.conf configuration file, all this finally takes the form:

factor /usr/lib/cosign/factors/otp login passcode

where otp is a symlink to the universal Cosign PAM factor adaptor pam_factor, and a new ‘otp‘ PAM service using the Yubico PAM module has also been declared.

Note: the name of the factor is significant, and is more than just, for example, self-documentation! Recall that the factor must, on successful authentication:

  • write the factor name to stdout; and
  • exit with 0.

The universal Cosign PAM ‘factor adaptor’ is coded to emit a factor name which corresponds to its basename – i.e. in our case, it will emit the factor name of ‘otp‘ on successful authentication. So the literal factor name ‘otp‘ is what the rest of the corresponding Cosign configuration client-side must be set up to expect.

In addition: the name of the corresponding local PAM service must match that of the factor: the factor is coded to call out to the local PAM service which corresponds to its basename.

Finally, however: why call this factor ‘otp‘ rather than, say, the more mnemonic name ‘yubikey‘? After all, both of the above-mentioned pieces of configuration could be fixed up accordingly. Well, as well as ‘leaking’ less internal configuration information, it turns out that the factor ‘otp‘ is already explicitly supported by the supporting HTML and Javascript distributed in the Cosign tarball. So ‘otp‘ is just better and easier all round.

Cosign ‘factors’ – continued …

Filed under: Pilot service for Yubikey two-factor authentication — idurkacz @ 3:06 pm
Tags: ,

Bearing in mind that ‘factor’ is an overloaded term within Cosign, the “Cosign Multi-Factor Specification, 20 March 2006, Draft 6” defines the necessary behaviour of a ‘factor’ as ‘external authenticator.’ Namely:

  1. External authenticator(s) are declared as follows in /etc/cosign.conf:
    factor <pathname> [-2] <form-field1> <formfield2> …
    
  2. Any such authenticator will be invoked if (and only if) all listed form-fields contain posted data.
  3. The value of each form-field is written to the authenticator on stdin, one per line, in the order in which they are listed in the configuration.
  4. If authentication is successful, the authenticator:
    • writes the factor name to stdout
    • exits with 0

    Otherwise, the authenticator:

    • writes an error message to stdout
    • exits with 1

The -2 option to the factor keyword means that this factor is only checked after another (non -2) factor has been satisfied. It’s intended for use with factors which are vulnerable to denial-of-service attacks due to repeated authentication failures.

Cosign ‘factors’

Filed under: Pilot service for Yubikey two-factor authentication — idurkacz @ 12:29 pm
Tags: ,

In Cosign, the word ‘factor’ fundamentally means an ‘authentication type.’ However, ‘factor’ is an overloaded term, which also refers to:

  • an arbitrary string which is returned by an external authenticator on success;
  • the external authenticator itself.

In addition, there are ‘Legacy factors’: e.g. if Kerberos is used to authenticate the account, the ‘factor’ is set to the Kerberos realm used.

(More information about all of this can be found in the “Cosign Multi-Factor Specification, 20 March 2006, Draft 6”.)

On the client Cosign website, authorization by factor is enforced by the Cosign filter directive CosignRequireFactor.

Authorization by factor can be arranged via ‘AND‘ and ‘OR‘ combinations: a CosignRequireFactor directive which includes multiple factors implies that those factors are AND‘ed together; multiple CosignRequireFactor directives are OR‘ed.

Edit: in fact, testing subsequent to this blog post shows it is not the case that “multiple CosignRequireFactor directives are OR‘ed”! It turns out that, in the case of multiple CosignRequireFactor directives, the most ‘recently defined’ CosignRequireFactor directive wins. See blog post Cosign ‘factors’ – a correction.

On Informatics sites, up until fairly recently CosignRequireFactor has typically been null – which means ‘accept any request which has been authenticated against any available factor.’

Nowadays, we generally declare

CosignRequireFactor INF.ED.AC.UK  

in order to allow Informatics users, but to exclude iFriend users.

Just to repeat: a null CosignRequireFactor means that authentication against any available factor is deemed sufficient. Be careful!

Cosign ‘multi-factor’ authentication

Filed under: Pilot service for Yubikey two-factor authentication — idurkacz @ 12:03 pm
Tags:

I mentioned above that conventional Cosign authentication is based on Kerberos: i.e. usernames, and passwords.

However, it also turns out that, since v2, Cosign has had (some) support for multi-factor authentication. The relevant document to read is linked to from Cosign’s home page, and is “Cosign Multi-Factor Specification, 20 March 2006, Draft 6”.

That’s good news: it means that the necessary infrastructural support for ‘two-factor’ authentication is already present in Cosign.

Some background: what’s Cosign, and how does it work?

Filed under: Pilot service for Yubikey two-factor authentication — idurkacz @ 11:36 am
Tags:

Cosign – see http://weblogin.org – is “an open source project originally designed to provide the University of Michigan with a secure single sign-on web authentication system.”

From the point of view of a user, a first visit to a Cosign-protected website results in redirection to an institutional authentication server which requests username and password via an HTTPS web form. Once authenticated, the user is then redirected back to the Cosign-protected website where – internal website authorization permitting – they can access content and resources, all mediated by the corresponding Cosign filter. Visits to further Cosign-protected websites then proceed transparently, using authentication cookies delivered via the initial visit to the institutional authentication server: that’s the ‘single sign-on’ in action.

In fact, the ‘single sign-on’ can work even better than that. Since the underlying authentication protocol is assumed to be Kerberos, a web browser which is capable of using SPNEGO (also known as ‘HTTP Negotiate Auth’ – see for example both RFC4559, and Microsoft’s HTTP-Based Cross-Platform Authentication by Using the Negotiate Protocol documentation) is able to use a user’s existing Kerberos tickets for the initial authentication sequence. The result in that case is that, provided the user has already authenticated via Kerberos, his/her subsequent access to institutional Cosign-protected websites is completely transparent.

Official Cosign documentation is unfortunately rather scattered. For a pictorial view of the authentication process, see the overview diagram at Cosign’s home website.

I might also mention that documentation pertaining to Informatics-specific local Cosign modifications is also rather scattered … but more on that later!

November 9, 2015

Back to work …

Filed under: Pilot service for Yubikey two-factor authentication — idurkacz @ 10:32 pm
Tags: ,

Quite some time ago now (!), I wrote ‘In the New Year, I’ll post more information about the new project and, in particular, progress with integrating Yubikey use into Cosign.’

Practical work on this project stalled since I wrote that sentence – in part, owing to the lack of a ‘real’ test case which we could use for serious testing. However we’ve now restarted the effort, and I’ll document the successful integration into Cosign of Yubikey two-factor authentication in some forthcoming posts.

December 13, 2014

A new project

Filed under: Pilot service for Yubikey two-factor authentication — idurkacz @ 11:33 am
Tags: ,

The test OpenSSH service described in previous posts which uses Yubikey two-factor authentication seems to work fine, has been running in a very small-scale way since about August 2014, and was in fact developed as part of the more general investigative precursor project Project 279 – Options for two-factor authentication.

However, as mentioned in an earlier post, in order to make our overall site configuration both sensible and consistent, we’d definitely want to integrate the use of Yubikeys into our Cosign-protected websites too. So, having satisfied ourselves that the use of Yubikeys seemed to be viable, we created the project which is the subject of this blog – namely Project 313: Pilot service for Yubikey two-factor authentication – in order to develop a more fully-fledged ‘test’ service.

The previous posts bring this blog more or less up-to-date with the state of the test two-factor OpenSSH service, but by now there has also now been progress with Cosign integration.

In the New Year, I’ll post more information about the new project and, in particular, progress with integrating Yubikey use into Cosign.

December 12, 2014

Towards two-factor Yubikey authentication with OpenSSH

Filed under: Pilot service for Yubikey two-factor authentication — idurkacz @ 5:21 pm
Tags: , ,

Our overall strategy for a test OpenSSH service using two-factor authentication via Yubikey is now clear:

  1. Integrate Yubico’s PAM module into the PAM stack used for our ssh service.
  2. Configure that PAM module to authenticate against the Yubicloud service.
  3. Organize our configuration so that only those users who are registered (somehow …) for Yubikey use are required to submit a Yubikey OTP.

Since we definitely don’t want to mandate Yubikey use for every user, how can we arrange this final (very necessary) requirement? It turns out that the (previously unknown to me) pam_succeed_if module can help. That allows an ‘if test’ which tests for group and/or netgroup membership to be arranged in the PAM stack. So, what we need to do is to instantiate a suitable group (or netgroup) which contains the UUNs of all those users registered for Yubikey use.

To keep things as simple as possible for testing, we’ve chosen to set that up for now as a group, called yubikeyusers. (We’ll almost certainly use a netgroup in any final live implementation.) The relevant lines of the resulting PAM configuration are as follows:

 
auth	[success=ignore ignore=ignore default=1]	/lib64/security/pam_succeed_if.so	debug user ingroup yubikeyusers 
auth	required	/lib64/security/pam_yubico.so	id=<secret> key=<secret> authfile=/etc/yubikey_mappings debug 

Some notes about the parameters to the Yubico PAM module pam_yubico.so:

  1. We’ve got debugging turned on for this module so that we can get detailed output from the authentication process. For that to work as expected, it’s necessary to ‘touch’ the nominated log file in advance:
    touch /var/run/pam-debug.log
    chmod go+w /var/run/pam-debug.log
    
  2. The <secret> strings are our private keys for use with the Yubicloud service. Such keys are freely available from Yubico.
  3. The file /etc/yubikey_mappings contains the mappings of Yubikey public ids to local UUNs. That is: it formally associates actual Yubikeys with actual users. (An individual user can be associated with more than one Yubikey, by the way.) In a final live system, we’d expect to integrate that same information into our LDAP directory: Yubico’s PAM module can read from that.

Yubikey authentication

Filed under: Pilot service for Yubikey two-factor authentication — idurkacz @ 5:04 pm
Tags: ,

The Yubikey authentication standard is proprietary – but it is completely open. So it would be perfectly possible for anybody to implement their own authenticator from the ground up.

However: why bother? Yubico makes a lot of source code available at its github site including:

  1. Source code for an authentication server.
  2. Source code for a PAM module which interfaces with the authentication server.

In addition, Yubico provides a free ‘cloud-based’ authentication service, ‘Yubicloud’.

So in fact experimenting with Yubikey authentication is easy: for a start, anyway, we can just use the ‘Yubicloud’ service.

What is a Yubikey, and how does it work?

Filed under: Pilot service for Yubikey two-factor authentication — idurkacz @ 3:56 pm
Tags:

A Yubikey is a small (about 3cm x 1cm x 2mm) passive USB device. When plugged into the USB port of any PC, it presents itself as a standard USB HID keyboard and, when the capacitive ‘button’ on the Yubikey is pressed, the device emits a character string which implements a one-time password (OTP).

Ignoring, for now, the details of the contents of the string, the point is that, if the string can be correctly handled as a OTP by the receiving server, the entire system is platform independent (more-or-less every PC or laptop has a USB port), and very easy to use.

Ok – so what does the ‘string’ look like? In fact, the Yubikey can operate in two different modes: either the standard proprietary ‘Yubico OTP’ mode, or ‘OATH-HOTP’ mode. (Aside: note, not ‘OATH-TOTP’: the Yubikey is unpowered, and so doesn’t have a on-board clock.) We’re currently using and testing the standard mode, though it might be that later on we move to OATH-HOTP for reasons of server-side compatability with software OTP producers.

In standard mode, then, and using its default settings, the Yubikey produces a 44 character text string in which the first 12 characters are a public id string, and the final 32 characters are an AES-encrypted OTP. Here (taken from the Yubikey manual) is an example of the output when a Yubikey is pressed three times in succession:

fifjgjgkhchbirdrfdnlnghhfgrtnnlgedjlftrbdeut
fifjgjgkhchbgefdkbbditfjrlniggevfhenublfnrev
fifjgjgkhchblechfkfhiiuunbtnvgihdfiktncvlhck
<-12 chars-><---------- 32 chars ---------->

You can see that the public id of the Yubikey here is fifjgjgkhchb.

What’s the content of the encrypted OTP? In essence, it’s nothing more than a monotonically-increasing integer. Authentication works as follows:

  1. Each Yubikey has a unique (symmetric) AES key.
  2. All such keys are shared between the Yubikeys, and the authentication server.
  3. On the authentication server, the AES keys are mapped to the public ids of the Yubikeys.
  4. On receipt of an OTP, the authentication server selects the appropriate AES key, decrypts the payload and, if it finds that the integer contained in the payload is larger than any previously presented by the Yubikey, authentication succeeds.
« Previous PageNext Page »

Theme: Rubric.