\input texinfo   @c -*-texinfo-*-

@c %**start of header
@setfilename totp.info

@c Automake automatically updates version.texi to @set VERSION and
@c @set UPDATED to appropriate values.
@include version.texi

@settitle Java TOTP Server Library @value{VERSION}

@c @finalout

@smallbook

@paragraphindent 2
@c %**end of header

@copying
This manual is for the Java @acronym{TOTP} server library (version
@value{VERSION}, @value{UPDATED}).

Copyright @copyright{} 2013-2018 Enrico M. Crisostomo

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled `GNU
Free Documentation License'.
@end quotation
@end copying

@setchapternewpage odd

@shorttitlepage Java TOTP Server Library
@titlepage
@title Java TOTP Server Library
@subtitle Time-Based One-Time Password (@acronym{TOTP})
@subtitle Java Server Library @value{VERSION}, @value{UPDATED}

@author Enrico M. Crisostomo

@c Include the Distribution inside the titlepage so
@c that headings are turned off.

@page
@vskip 0pt plus 1filll
@insertcopying

@end titlepage

@c Output the table of contents at the beginning.
@summarycontents
@contents

@ifnottex
@node Top
@top Java TOTP Server Library
@insertcopying
@end ifnottex

@menu
* Introduction::
* Overview::
* API Description::
* API::
* GNU Free Documentation License:: Copying and sharing this manual
* Index::
@end menu

@node Introduction
@chapter Introduction
The Time-Based One-Time Password algorithm (@acronym{TOTP}) (@acronym{RFC} 6238)
is a an extension of the @acronym{HMAC}-based One-Time Password algorithm
(@acronym{HOTP}) (@acronym{RFC} 4226) which is the basis of many two-phase
authentication solutions such as Google's, Microsoft's and others.

The @emph{Google Authenticator} client application is probably the most widely
used software-based @acronym{TOTP} token generator, and is available as a free
application on all the mainstream mobile operating systems.  It is probably the
de-facto standard @acronym{TOTP} password generator and it is used to manage not
only Google's, but other accounts' passwords as well.  Google Authenticator is a
flexible, easy to use, easy to configure, free application that can be leveraged
by any system, provided it has a back-end that implements the functionality to
validate a @acronym{TOTP} password.  This Java library provides the building
blocks of such a back-end:

@itemize
@item
Credential generation.

@item
Credential verification.

@item
@acronym{QR} code generation@footnote{The @acronym{QR} code can be obtained
using a generated @acronym{URL}, which relies on the goQR @acronym{HTTP}
@acronym{API} to create a compliant @acronym{QR} code encoding the necessary
information.}  for the easy configuration@footnote{Google Authenticator can use
the built-in camera of a cellular phone to take a picture of a @acronym{QR} code
and configure a new account using the information contained therein.} of an
account in the Google Authenticator application.
@end itemize

@section Design Philosophy
This library has been designed with @emph{simplicity} in mind, trying to follow
the @acronym{KISS} principle.  This basically means that the library @emph{does
one thing}, and it strives hard @emph{to do it well}: @acronym{TOTP}
authentication.  No more, no less.

There exist more complex and comprehensive solutions, and if you need something
more than being able to perform @acronym{TOTP} authentication, chances are you
should assess whether to use this library or some other product.

On the other hand, if what you are looking @emph{is} performing @acronym{TOTP}
authentication, then this library will provide an easy to use @acronym{API} and
a @emph{very} compact library: currently, the size of the library @acronym{JAR}
archive is smaller than 20 kB.  Most importantly, this library has very
few@footnote{This library's dependencies are compact as well and do not pull-in
a chain of dependencies themselves.}  dependencies:

@itemize
@item
The @emph{Apache Commons Codec} library.

@item
The @emph{Apache @acronym{HTTP} components} library.

@end itemize

The library contains Java @acronym{SE} code and the back-end components are
implemented as @acronym{POJO}s (using current Java jargon).  Therefore, it can
be included and used in any Java application and does not have dependencies with
any framework or technology@footnote{Earlier versions of this library had a
dependency with @acronym{JAX-RS} v. 2 that was removed in v. 0.4.5.}  other than
a Java @acronym{SE} 7 runtime environment.

@node Overview
@chapter Overview
The @acronym{TOTP} algorithm (specified by @acronym{RFC} 6238) is an extension
of the @acronym{HOTP} algorithm that uses a time-based moving factor instead of
an event counter.  One of the purposes of that work is, in the words of the
authors:

@quotation
   The proposed algorithm can be used across a wide range of network
   applications, from remote Virtual Private Network (@acronym{VPN}) access and
   Wi-Fi network logon to transaction-oriented Web applications.  The authors
   believe that a common and shared algorithm will facilitate adoption of
   two-factor authentication on the Internet by enabling interoperability across
   commercial and open-source implementations.
@author @acronym{RFC} 6238
@end quotation

In fact, as expected by the authors, both two-factor authentication and
@acronym{TOTP} are being widely adopted.  Google enabled @acronym{TOTP}-based
two-factor authentication for its users and developed a software @acronym{TOTP}
token generator, @emph{Google Authenticator}, running on all the mainstream
smartphone operating systems, which is now the de-facto standard token generator
(at least for non-corporate use).

@acronym{TOTP}-based two-factor authentication schemes usually require the user
to send its @acronym{TOTP} password alongside its credentials.  The
@acronym{TOTP} password is time-based, it is calculated with a cryptographic
algorithm and its validity is very short: @acronym{RFC} 6238 recommends to used
a time-step size of 30 seconds.  The very short expiration time of each password
is a key security factor against attacks.

The security analysis (@acronym{RFC} 4226) of this algorithm concludes that the
best attack against the @acronym{HOTP} function is the @emph{brute force}
attack.  The security of the algorithm can be approximate (@acronym{RFC} 4226)
as
@tex
$$ {\rm Security} = {s \cdot v \over 10^d} $$
@end tex
@noindent
where @math{s} is the @emph{look-ahead synchronization window
size}@footnote{Referred to simply as @emph{window size} in the rest of this
manual.}, @math{v} is the number of @emph{verification attempts} and @math{d} is
the number of @emph{digits} in the @acronym{TOTP} password.  That is: if a brute
force attack with @math{v} verification attempts is used, then its probability
of success is
@tex
$$ p = {s \cdot v \over 10^d} $$
@end tex

@acronym{RFC} 4226 recommends that @math{d \geq 6}, and this library validates
6-digit @acronym{TOTP} passwords, which is the password length currently used by
Google Authenticator.  Passwords of up to 9 decimal digits could be used, which
is the maximum that can be represented by the 31-bit string returned by the
@emph{dynamic truncation} function.

Evaluating the probability @math{p} of making a successful attack with @math{s =
10} and @math{d = 6} yields
@tex
$$ p = { v \over 10^5 } $$
@end tex
that is, @math{v} successes every 10.000 attempts.  By limiting the number of
unsuccessful authentication attempts a user can perform, a superior bound on
@math{p} can be established that satisfies the security requirements.

@node API Description
@chapter @acronym{API} Description
The @acronym{TOTP} algorithm is used to determine whether the password provided
by the @emph{prover}@footnote{The user providing the password generated by his
token.}  is proved as authentic by the @emph{verifier}, given the prover's
@emph{shared secret} and current Unix time.

The two basic operations that this library implements are:

@itemize
@item
Credential @emph{creation}.

@item
Credential @emph{authentication}.

@end itemize

Credential creation is the process in which the server generates the
@emph{shared secret} and shares it with the client.  The shared secret is
generated using a cryptographically strong pseudorandom generator and has to be
communicated to the client, so that he can store it and configure its token.  A
common way to communicate this information is sending it to the client encoded
into a @acronym{QR} code.  The user only needs to scan the @acronym{QR} code
with the Google Authenticator application and then discard it immediately.  For
the sake of security, @acronym{TOTP} token generators do not generally let users
retrieve the shared secrets after an account has been configured.  This way,
only individuals in physical possession of a token can use the shared secret to
generate @acronym{TOTP} passwords.

Credential authentication is the process in which the server applies the
@acronym{TOTP} algorithm to the shared secret and the token-generated password
of the prover to determine its authenticity.

All the @acronym{API} members are published by the following interfaces and
classes:

@table @command
@item IGoogleAuthenticator
This is the main @acronym{API} interface and it publishes the library entry
points.

@item GoogleAuthenticatorKey
This class is the credentials container, mainly used when returning
newly-created credentials.

@item GoogleAuthenticatorQRGenerator
This helper class provides @acronym{QR} code generation using the goQR
@acronym{HTTP} @acronym{API}.

@item ICredentialRepository
This interface can optionally be implemented by callers to provide callback
functions to the library used to interact with a `credential repository', where
newly-generated credentials are @emph{stored} and keys are @emph{retrieved} when
a password must be validated.

@end table

@section Random Number Generator Algorithm and Provider
The creation of a shared secret is an important process because the ability of
taking over or guessing somebody else's secret could result in account
hijacking.  For this reason, and since it is not always practicable or desirable
to devise such a creation strategy, this library offers the possibility of
creating shared secrets using data coming from a cryptographically strong
pseudorandom generator (@acronym{PRNG}).  The default provider (@command{SUN})
and the default algorithm (@command{SHA1PRNG}) used by this library are
available on Oracle Java runtime environments and they were not tested on other
implementations where they are likely to be missing.

Users can configure the library to use an alternate provider and algorithm by
providing their names as values of the following system properties or they can
specify this in the @code{GoogleAuthenticator} constructor:

@table @command
@item com.warrenstrange.googleauth.rng.algorithm
If a property with this name is set, the specified random number generator
algorithm is used.

@item com.warrenstrange.googleauth.rng.algorithmProvider
If a property with this name is set, the specified random number generator
algorithm provider is used.  The provider can be overridden if and only if the
algorithm is overridden as well.

@end table

While explicitly specifying a provider and an algorithm may impair
interoperability, on the other hand it guarantees the expected level of
randomness and a predictable behaviour.  The performance problems often reported
when using a blocking entropy gathering device (@pxref{NativePRNG}) are an
example of why the authors chose the current defaults.

@subsection @command{NativePRNG}
@anchor{NativePRNG}
On some environments the @command{NativePRNG} algorithm may be used by default.
This algorithm uses the @file{/dev/random} device to get random data and this
device is @emph{blocking} on certain platforms (such as Linux).  If the blocking
behaviour is undesirable and @file{/dev/urandom} can be used as a valid
alternative entropy gathering device, then the @command{NativePRNG} algorithm
can be configured to get random data from @file{/dev/urandom} by setting the
system property @env{java.security.egd} to @file{/dev/urandom}, for example
passing the following argument to the Java virtual machine:

@example
-Djava.security.egd=file:/dev/urandom
@end example

@section @command{ICredentialRepository}-Related Methods
The @command{IGoogleAuthenticator} interface originally provided the following
methods:

@table @command
@item createCredentials()
Create new credentials.

@item authorize(String secret, int verificationCode)
Validate the specified @command{verificationCode} with the specified
@command{secret} using the @acronym{TOTP} algorithm.

@end table

When support for the @command{ICredentialRepository} callbacks was designed, a
new set of methods were added to allow the user to specify a
@command{@var{userName}} to be used to save or retrieve his key.  Such methods
are the following:

@table @command
@item createCredentials(String userName)
Create new credentials.

@item authorizeUser(String userName, int verificationCode)
Validate the specified @command{verificationCode} with the secret of the user
with the specified @command{userName} using the @acronym{TOTP} algorithm.
@end table

@noindent
Their functionality is identical to that of the aforementioned methods, but in
this case no @command{@var{secret}} is returned or passed as a parameter, but is
saved or retrieved from the configured @command{ICredentialRepository} instance
instead.

In the following sections the first generation methods will be used for tutorial
purposes, but any of those @acronym{API} calls could be substituted by the
corresponding @command{ICredentialRepository}-enabled call.

@section Credential Creation
A new set of credentials can be created using the @command{createCredentials}
method:

@example
GoogleAuthenticatorKey createCredentials();
@end example

@noindent
This method computes a new random shared secret wrapped into a
@command{GoogleAuthenticatorKey} instance.

@subsection Credentials
The @command{GoogleAuthenticatorKey} class represents newly generated
credentials, as returned by @command{createCredentials}.  Instances of this
class contains the following data members:

@itemize
@item
The shared secret @command{key}.

@item
The @emph{verification code}@footnote{The verification code is the
@acronym{TOTP} password calculated at @math{t = u}, where @math{u} is the Unix
Epoch.} @command{verificationCode}.  The verification code is an optional
feature which is not used by some clients such as Google Authenticator.

@item
A list of @emph{scratch codes} @command{scratchCodes}.  Scratch codes are
randomly generated data@footnote{Generated together with the shared secret using
the same, cryptographically strong pseudorandom generator.}  that are optionally
used as `recovery passwords' in case the token generator is not available.  If
this feature is implemented, scratch codes should be usable only @emph{once}.
This library provides scratch codes as an ancillary feature, to offer the client
randomly generated data with the same guarantees the shared secret offers.  How
scratch codes are used, however, is a responsibility of the prover and this
library offers no facility to store them or validate them.
@end itemize

@section Generating a @acronym{QR} Code
@anchor{Generating a @acronym{QR} Code} The Google Authenticator application can
be quickly configured using a @acronym{QR} code: the application requests the
user to take a photograph of the code and the application uses the data encoded
therein to configure a new account.

This approach has several advantages: human errors are reduced to a minimum, or
eliminated altogether, the setup process is easy and quick, but most
importantly, the shared secret is @emph{never} shown in plain text.  Unless a
malicious user succeeds in stealing a usable picture of the @acronym{QR} code to
configure another Google Authenticator instance with the stolen credentials, the
shared secret cannot be read, not even by the legitimate owner himself.
Therefore, @acronym{QR} code greatly reduce the risk of credentials being
intercepted during the delicate phase of the initial interchange.

This library supports this use case providing a ready-to-use goQR
@acronym{HTTP} @acronym{API} call to display a @acronym{QR} code encoding all
the data of the newly generated credentials:

@itemize
@item The @emph{issuer}.
@item The @emph{account name}.
@item The @emph{label}.
@item The @emph{shared secret}.
@end itemize

The @acronym{QR} code encoding the aforementioned data can be created invoking
the @command{GoogleAuthenticatorQRGenerator.getOtpAuthURL()} method:

@example
public static String getOtpAuthURL(
  String issuer,
  String accountName,
  GoogleAuthenticatorKey credentials);
@end example

@noindent
as in the following example, where @command{Test Org.} is the @emph{issuer} and
@command{test@@test.org} is the account name@footnote{Account names often are
email addresses, but they need @emph{not} be.}:

@example
final GoogleAuthenticatorKey key =
  googleAuthenticator.createCredentials();
final String otpAuthURL =
  GoogleAuthenticatorQRGenerator.getOtpAuthURL(
    "Test Org.",
    "test@@test.org",
    key);
@end example

@noindent
The @command{GoogleAuthenticatorQRGenerator.getOtpAuthURL} method will return a
goQR @acronym{API} @acronym{URL} which can then be used to generate the
@acronym{QR} code image.

@subsection The @command{otpauth} Scheme
Google Authenticator expects an @acronym{URI} conforming to the
@acronym{otpauth} scheme to configure a new account.

@example
otpauth://@var{type}/@var{label}?@var{parameters}
@end example

@noindent
This @acronym{URI} is generated by the library using the information passed to
the @acronym{API} methods.  The most important pieces of information are:

@itemize
@item
The @command{@var{type}}, which is @emph{always} @command{totp}.

@item
The @command{@var{label}}, conforming to the following @acronym{ABNF} grammar:

@smallexample
label = accountname / issuer (":" / "%3A") *"%20" accountname
@end smallexample

@item
The @command{@var{parameters}}.  The library automatically adds the two required
parameters @command{issuer} and @command{secret}.  The secret is the shared
secret, encoded in Base32 (@acronym{RFC} 5348).
@end itemize

@subsubsection The Issuer
The issuer identifies the service provider associated with the account being
created, and it must be @acronym{URL}-encoded.  The issuer information is
@emph{optional} and is present in both the label and the query parameters of an
@command{optauth} @acronym{URI}.  Although optional, it is @emph{strongly
recommended} to include it.

@subsection The @acronym{QR} Code
The goQR @acronym{API} currently generates the @acronym{QR} code as an
image in @acronym{PNG} format (@pxref{qr}).

@float Figure, qr
@image{qr, 100pt}
@caption{A @acronym{QR} code generated by goQR.}
@end float

Since one of the reasons why @acronym{QR} codes are used in the first place is
making it more difficult to a man in the middle to steal a newly-generated
identity, and since it encodes the shared secret, implementors should make sure
the @acronym{QR} code is treated as securely as any other kind of credential.

@section Generating a Password
A @acronym{TOTP} password can be created using one of the
@command{getTotpPassword*} methods, specifying:

@itemize
@item
The secret or the username.

@item
The time for which the password should be generated.
@end itemize


@section Validating a Password
A @acronym{TOTP} password is validated using one of the different
@command{authorize*} methods provided by the library.  To validate a password,
the @acronym{TOTP} algorithm requires:

@itemize
@item
The password to validate.

@item
The shared secret@footnote{The library @acronym{API} treats one-time passwords
as integers.}.

@item
The time-based moving factor.

@end itemize

The client and the server should agree on how to calculate the time-based moving
factor.  @acronym{RFC 6238} @emph{recommends} using a default time-step size of
30 seconds and this library adheres to that recommendation.  The library
@acronym{API} allows callers to specify the number of time-step windows that
should be checked during the validation process, but does not currently allows
the time-step size to be overridden.

When the number @math{x} of time-step windows to use is specified, the
implementation will check all the integral time-step in an interval @math{I}
(roughly) centered in the current instant of time:
@math{I = [\lfloor -(x-1)/2 \rfloor, \lfloor x/2 \rfloor]}.

@node API
@chapter @acronym{API}
The @acronym{API} is currently published by the following classes and interfaces:

@table @command
@item GoogleAuthenticator
The @command{IGoogleAuthenticator} implementation.

@item GoogleAuthenticatorConfig
The configuration parameters used during the TOTP password validation, including
time step size, window size, number of digits and key representations.

@item GoogleAuthenticatorConfig.GoogleAuthenticatorConfigBuilder
The factory for @code{GoogleAuthenticatorConfig} instances.

@item GoogleAuthenticatorException
The root exception used by the library.

@item GoogleAuthenticatorKey
This class is the credentials container, mainly used when returning
newly-created credentials.

@item GoogleAuthenticatorQRGenerator
Helper class providing @acronym{QR} code generation using the goQR
@acronym{HTTP API}.

@item ICredentialRepository
This interface can optionally be implemented by callers to provide callback
functions to the library used to interact with a `credential repository', where
newly-generated credentials are @emph{stored} and keys are @emph{retrieved} when
a password must be validated.

@item IGoogleAuthenticator
This is the main @acronym{API} interface and it publishes the library entry points.

@item KeyRepresentation
An enumeration of all the available secret key representations, currently:

@itemize
@item @code{BASE32}
@item @code{BASE64}
@end itemize

@item ReseedingSecureRandom
A wrapper class around @command{SecureRandom} that takes care of reseeding the
wrapper instance every certain number of operations.  Currently, this parameter
is not overridable.

@end table

@section @command{GoogleAuthenticator}
The @command{GoogleAuthenticator} class is the provided implementation of the
@command{IGoogleAuthenticator} interface.  This class adds no public methods to
those defined in its primary interface.

This implementation conforms to the recommendations and the default parameter
values specified in @acronym{RFC 6238}.  Specifically, this class uses:

@itemize
@item
The @acronym{HMAC-SHA-1} algorithm is used, as specified by @acronym{RFC} 4226.
@acronym{RFC} 6238 specifies that implementors @emph{may} also use
@acronym{HMAC-SHA-256} and @acronym{HMAC-SHA-512} and can be used by specifying them
in the constructor of @code{GoogleAuthenticator}.

@item
A time-step size of 30 seconds is used, as recommended in by @acronym{RFC} 6238.

@end itemize

@noindent
The parameters used during the TOTP password validation are:

@itemize
@item Time step size.
@item Windows size.
@item Number of digits (key modulus).
@end itemize

@noindent
Furthermore, the secret key can be provided in one of the supported
representations:

@itemize
@item @code{BASE32}.
@item @code{BASE64}.
@end itemize

Base32 is the representation used by default by Google Authenticator, and Base64
is offered since it is the default representation used by @acronym{RFC} 6030,
@emph{Portable Symmetric Key Container (PSKC)}, since it is commonly used by
software platforms and hardware TOTP token providers.

All these parameters can be configured by passing an instance of the
@code{GoogleAuthenticatorConfig} class to the constructor of the
@code{GoogleAuthenticator} class.

@subsection @code{GoogleAuthenticatorConfigBuilder}
@code{GoogleAuthenticatorConfig} instances can only be built using
@code{GoogleAuthenticatorConfigBuilder} instances.
The following fragment, for example, builds a @code{GoogleAuthenticator}
instance with the following characteristics:

@itemize
@item
It uses a time step size of one minute.

@item
It validate TOTP password checking an interval of 5 time steps centered at the
current time.

@item
It validates and creates TOTP passwords of 8 digits.

@item
It requests 10 scratch codes.

@end itemize

@example
GoogleAuthenticatorConfigBuilder gacb =
  new GoogleAuthenticatorConfigBuilder()
    .setTimeStepSizeInMillis(TimeUnit.SECONDS.toMillis(60))
    .setWindowSize(5)
    .setCodeDigits(8)
    .setNumberOfScratchCodes(10);
GoogleAuthenticator ga =
  new GoogleAuthenticator(gacb.build());
@end example

@section @command{GoogleAuthenticatorException}
This class is the root exception used by library methods.  The exception is a
subtype of @command{RuntimeException} so that library method callers need
neither catch nor declare this exception in their calling methods.

@section @command{GoogleAuthenticatorKey}
This inmutable class is a JavaBean used by the GoogleAuthenticator library to
represent a newly-created set of credentials.  Currently, this class publishes
the following read-only properties:

@table @command
@item GoogleAuthenticatorCofig config
The @acronym{TOTP} configuration of this key.

@item String key
The shared secret.

@item List<Integer> scratchCodes
A list of scratch codes.  By default, 5 scratch codes are provided.
There currently is no way to generate scratch codes without creating a
new credential.

@item int verificationCode
The verification code, that is, the @acronym{TOTP} password when at time-step 0
(the Unix Epoch).

@end table

@subsection @command{GoogleAuthenticatorKey.Builder}
Instances of @command{GoogleAuthenticatorKey} can only be built using
@command{GoogleAuthenticatorKey.Builder} instances.  The builder
publishes all the properties of the @command{GoogleAuthenticatorKey}
class.  The following fragment, for example, builds an instance with the
following characteristics:

@itemize
@item
It has a default @command{GoogleAuthenticatorConfig}.

@item
It has the following secret key: @command{secretKey}.

@item
It has the following verification code: @command{123456}.

@item
It has an empty list of scratch codes.
@end itemize

@example
GoogleAuthenticatorConfig config =
  new GoogleAuthenticatorConfig
    .GoogleAuthenticatorConfigBuilder()
    .build();

GoogleAuthenticatorKey credentials =
  new GoogleAuthenticatorKey
    .Builder("secretKey")
    .setConfig(config)
    .setVerificationCode(123456)
    .setScratchCodes(new ArrayList<Integer>())
    .build();
@end example

Manually building instances of this class is generally useful to
re-create @acronym{QR} codes for an existing key.

@section @command{GoogleAuthenticatorQRGenerator}
This class is a helper class which provides a way to generate
@acronym{QR} codes using the goQR @acronym{API}.  Please note
that the usage of this method is subject to the license and usage
restrictions of the goQR @acronym{API}.

This class publishes the following method:

@table @command
@item static String getOtpAuthURL(String issuer, String accountName, GoogleAuthenticatorKey credentials)
Returns the @acronym{URL} of a goQR @acronym{API} call to
generate a @acronym{QR} barcode to be loaded into the Google
Authenticator application.  The user scans this bar code with the
application on their smart phones or enters the secret manually.

@item static String getOtpAuthTotpURL(String issuer, String accountName, GoogleAuthenticatorKey credentials)
Returns the key @acronym{URI}, that is a @command{otpauth://}
@acronym{URL} as specified by the key @acronym{URI} format, to be loaded
in compliant applications.
@end table

@noindent
@ref{Generating a @acronym{QR} Code}, provides a detailed description of this
method's functionality.

@section @command{ICredentialRepository}
The @command{ICredentialRepository} is a service interface which can be
implemented by a library user to provide a callback that establishes a relation
between a user name and its shared secret.  The methods of the @acronym{API}
that accept a user name instead of the shared secret will use this callback to
retrieve that user's shared key.  This interface is optional and needs not be
implemented, unless you want the library code to perform basic user management
tasks.  Methods accepting user names are used when no
@code{ICredentialRepository} service is available will fail.

This interface defines the following methods:

@table @command
@item String getSecretKey(String userName);
This method returns the shared secret of the specified user.  If the specified
user does not exist, the method shall @emph{fail} throwing a
@command{GoogleAuthenticatorException}.

@item void saveUserCredentials(String userName, String secretKey, int validationCode, List<Integer> scratchCodes);
This method saves the credentials of the specified user.
@end table

The service lookup mechanism used by the library is the @code{ServiceLoader}
facility provided by Java @acronym{SE}.  Implementors needs creating a file
named after the service interface, that is
@example
com.warrenstrange.googleauth.ICredentialRepository
@end example
@noindent
and one line with the name of each implementing class.  The library will use the
@command{ServiceLoader} class to discover the available implementations and will
use the @emph{first} available.

@subsection Setting a credential repository on a per-instance basis

Since 1.0.0, the @code{ServiceLoader} @acronym{API} is not the only
way to set the credential repository: the
@code{setCredentialRepository(ICredentialRepository)} method can be
used to explicitly set the credential repository used by an
@code{IGoogleAuthenticator} instance, effectively disabling the
autmatic service discovery described in the previous section.

@subsection Disabling the credential repository feature

Sometimes it may be desirable to disable this feature on specific
instances.  This can be achieved by passing @code{null} to the
@code{setCredentialRepository} method.

@section @command{IGoogleAuthenticator}
This interfaces publishes the main library @acronym{API}:

@table @command
@item GoogleAuthenticatorKey createCredentials();
This method generates a new set of credentials including:

@itemize
@item Secret key.
@item Validation code.
@item A list of scratch codes.
@end itemize

The user must register this secret on their device.

@item GoogleAuthenticatorKey createCredentials(String userName);
This method generates a new set of credentials invoking the
@code{createCredentials} method with no arguments.  The generated credentials
are then saved using the configured @code{ICredentialRepository} service.

The user must register this secret on their device.

@item boolean authorize(String secret, int verificationCode);
Checks a verification code against a secret key using the current
time.  The algorithm also checks in a time window whose size
determined by the @code{windowSize} property of this class.  The
default value of 30 seconds recommended by @acronym{RFC} 6238 is used
for the interval size.

@item boolean authorize(String secret, int verificationCode, long time);
Checks a verification code against a secret key the specified time.
The algorithm also checks in a time window whose size determined by
the @code{windowSize} property of this class.  The default value of 30
seconds recommended by @acronym{RFC} 6238 is used for the interval
size.

@item boolean authorizeUser(String userName, int verificationCode);
This method validates a verification code of the specified user whose
private key is retrieved from the configured credential repository.
This method delegates the validation to the @code{authorize(String,
int)} method.

@item boolean authorizeUser(String userName, int verificationCode, long time);
This method validates a verification code of the specified user whose
private key is retrieved from the configured credential repository.
This method delegates the validation to the @code{authorize(String,
int, long)} method.

@item ICredentialRepository getCredentialRepository();
This method returns the credential repository used by this instance,
or @code{null} if none is set or none can be found using the
@emph{ServiceLoader} @acronym{API}.

@item void setCredentialRepository(ICredentialRepository repository);
This method sets the credential repository used by this instance.  If
@code{null} is passed to this method, no credential repository will be
used, nor discovered using the @emph{ServiceLoader} @acronym{API}.

@item getTotpPassword(String secret);
This method generates the current @acronym{TOTP} password using the
specified secret.

@item getTotpPassword(String secret, long time);
This method generates the @acronym{TOTP} password at the specified
time using the specified secret.

@item getTotpPasswordOfUser(String userName);
This method generates the current @acronym{TOTP} password using key of
the specified user.

@item getTotpPasswordOfUser(String userName, long time);
This method generates the @acronym{TOTP} password at the specified
time using key of the specified user.

@end table

@node GNU Free Documentation License
@appendix GNU Free Documentation License

@include fdl.texi

@c Print option index

@node Index
@unnumbered Index
@printindex cp

@bye