authglue.h File Reference

Performs DAF calls required for authentication sequences. More...

#include "../daf/DigitalAuthenticationFramework.h"
#include "daf_auth_state.h"

Go to the source code of this file.

Classes
class	DAAuthProtocol
	Co-ordinates calls required for enrollment, authentication and passphrase change. More...
Functions
DAAuthProtocol *	DAAuthEnroll (DADevice &device, DASession &sess, DAAuthState &state)
	Begins a DAF authentication enrollment process.
DAAuthProtocol *	DAAuthAuthenticate (DADevice &device, DASession &sess, DAAuthState &state)
	Begins a DAF re-authentication process.
DAAuthProtocol *	DAAuthChangePassphrase (DADevice &device, DASession &sess, DAAuthState &state)
	Begins a DAF authentication roll-over process.

---

Detailed Description

Performs DAF calls required for authentication sequences.

The 'authglue' library provides implementations of class DAAuthProtocol, and required support functions. A DAAuthProtocol object is created during the initial enrolment, authentication, and password-change (or key rollover) sequences, and is responsible for determining the class of the attached DAF device and making the appropriate sequence of calls to the DAF implementation. Where a user password is required, the DAAuthProtocol is also responsible for accepting the password and performing the required hashing to combine it with device secrets.

Call flow:

• The user interface code calls DAAuthEnroll, DAAuthAuthenticate or DAAuthChangePassphrase and receives ownership of a DAAuthProtocol object.
• The caller checks DAAuthProtocol::getLastError, DAAuthProtocol::requiresExistingPassphrase and DAAuthProtocol::requiresNewPassphrase flag functions, dealing with errors and passphrase acquisition as necessary. Note: authentication protocols do not do passphrase length, repetition or construction checking. That needs to happen higher up.
• The caller checks that DAAuthProtocol::finished() returns true.
• The caller passes the results of DAAuthProtocol::getSecret and/or DAAuthProtocol::getNewSecret to appropriate GD functions (unlockWithPassword, changePassword, setAuthProviderData, etc.)
• The caller deletes the DAAuthProtocol object.

For each protocol, the results available via getSecret/getNewSecret are:

• Enrollment: DAAuthProtocol::getNewSecret
• Authentication: DAAuthProtocol::getSecret
• Change passphrase: DAAuthProtocol::getSecret, and DAAuthProtocol::getNewSecret

The DAAuthState object passed in to DAAuthEnroll and DAAuthChangePassphrase will be modified, and should be saved in non-volatile storage.

---

Function Documentation

DAAuthProtocol* DAAuthAuthenticate	(	DADevice &	device,
		DASession &	sess,
		DAAuthState &	state
	)

Begins a DAF re-authentication process.

The caller will have called DAAuthEnroll successfully sometime in the past with device and sess, and saved the resulting state, passed back in here as state.

Errors are reported either by returning NULL or returning a protocol object already in the error state.

The returned object belongs to the caller and must be deleted.

DAAuthProtocol* DAAuthChangePassphrase	(	DADevice &	device,
		DASession &	sess,
		DAAuthState &	state
	)

Begins a DAF authentication roll-over process.

The caller will have called DAAuthEnroll successfully sometime in the past with device and sess, and saved the resulting state, passed back in here as state.

Errors are reported either by returning NULL or returning a protocol object already in the error state.

The returned object belongs to the caller and must be deleted.

DAAuthProtocol* DAAuthEnroll	(	DADevice &	device,
		DASession &	sess,
		DAAuthState &	state
	)

Begins a DAF authentication enrollment process.

sess must be a working session associated with device. Errors are reported either by this function returning NULL (if the device or session are broken or unidentifiable as offering authentication capabilities), or returning a DAAuthProtocol already in the error state (if the protocol went wrong, but didn't require any extra user input).

The returned object belongs to the caller and must be deleted.