App::OATH - Simple OATH authenticator


Simple command line OATH authenticator written in Perl.


Implements the Open Authentication (OATH) time-based one time password (TOTP) two factor authentication standard as a simple command line programme.

Allows storage of multiple tokens, which are kept encrypted on disk.

Google Authenticator is a popular example of this standard, and this project can be used with the same tokens.


usage: oath --add string --file filename --help --init --list --newpass --search string


--add string

add a new password to the database, the format can be one of the following

    text: identifier:secret
    url:  otpauth://totp/

--file filename

filename for database, default ~/.oath.json


show this help


initialise the database, file must not exist


list keys in database


resave database with a new password

--search string

search database for keys matching string


Tokens are encrypted on disk, the identifiers are not encrypted and can be read in plaintext from the file.

This is intended to secure against casual reading of the file, but as always, if you have specific security requirements you should do your own research with regard to relevant attack vectors and use an appropriate solution.


You most likely won't ever want to call these directly, you should use the included command line programme instead.

  • new()

    Instantiate a new object

  • usage()

    Display usage and exit

  • set_raw()

    Show the raw OATH code rather than decoding

  • set_rawqr()

    Show the raw OATH code as a QR code rather than decoding

  • set_search()

    Set the search parameter

  • get_search()

    Get the search parameter

  • init()

    Initialise a new file

  • add_entry()

    Add an entry to the file

  • list_keys()

    Display a list of keys in the current file

  • get_counter()

    Get the current time based counter

  • display_codes()

    Display a list of codes

  • make_qr( $srting )

    Format the given string as a QR code

  • oath_auth()

    Perform the authentication calculations

  • set_filename()

    Set the filename

  • get_filename()

    Get the filename

  • load_data()

    Load in data from file

  • save_data()

    Save data to file

  • encrypt_data()

    Encrypt the data

  • decrypt_data()

    Decrypt the data

  • get_plaintext()

    Get the plaintext version of the data

  • get_encrypted()

    Get the encrypted version of the data

  • set_newpass()

    Signal that we would like to set a new password

  • drop_password()

    Drop the password

  • get_password()

    Get the current password (from user or cache)

  • get_lockfilename()

    Return a filename for the lock file, typically this is filename appended with .lock

  • drop_lock()

    Drop the lock (unlock)

  • get_lock()

    Get a lock, return 1 on success or 0 on failure




Marc Bradshaw


Copyright 2015

This library is free software; you may redistribute it and/or modify it under the same terms as Perl itself.