view release on metacpan or  search on metacpan

lib/App/locket.pm  view on Meta::CPAN

=head1 VERSION

version 0.0022

=head1 SYNOPSIS

    # Setup the configuration file for the cipherstore:
    # (How to read the cipherstore, how to edit the cipherstore, etc.)
    $ locket setup

    # Add or change data in the cipherstore:
    $ locket edit

    # List all the entries in the cipherstore:
    $ locket /

    # Show a secret from the cipherstore:
    $ locket /alice@gmail

=head1 DESCRIPTION

App::locket is a tool for querying a simple YAML/JSON-based cipherstore 

It has a simple commandline-based querying method and supports copying into the clipboard 

Currently, encryption and decryption is performed via external tools (e.g. GnuPG, OpenSSL, etc.)

App::locket is best used with:

* gnupg.vim L<http://www.vim.org/scripts/script.php?script_id=661>

* openssl.vim L<http://www.vim.org/scripts/script.php?script_id=2012>

* EasyPG L<http://www.emacswiki.org/emacs/AutoEncryption>

=head1 SECURITY

=head2 Encryption/decryption

App::locket defers actual encryption/decryption to external tools. The choice of the actual
cipher/encryption method is left up to you

If you're using GnuPG, then you could use C<gpg-agent> for passphrase prompting and limited retention

=head2 In-memory encryption

App::locket does not perform any in-memory encryption; once the cipherstore is loaded it is exposed in memory

In addition, if the process is swapped out while running then the plaintextstore could be written to disk

Encrypting swap is one way of mitigating this problem

=head2 Clipboard access

App::locket uses third-party tools for read/write access to the clipboard. It tries to detect if
C<pbcopy>, C<xsel>, or C<xclip> are available. It does this by looking in C</bin> and C</usr/bin>

=head2 Purging the clipboard

By default, App::locket will purge the clipboard of a secret it put there after a set delay. It will try to verify that it is
wiping what it put there in the first place (so it doesn't accidentally erase something else you copied)

If for some reason App::locket cannot read from the clipboard, it will purge it just in case

If you prematurely cancel a secret copying operation via CTRL-C, App::locket will catch the signal and purge the clipboard first

=head2 Attack via configuration

Currently, App::locket does not encrypt/protect the configuration file. This means an attacker can potentially (unknown to you) modify
the reading/editing commands to divert the plaintext elsewhere

There is an option to lock the configuration file, but given the ease of code injection you're probably better off installing and using App::locket in a dedicated VM

=head2 Resetting $PATH

C<$PATH> is reset to C</bin:/usr/bin>

=head1 INSTALL

    $ cpanm -i App::locket

=head1 INSTALL cpanm

L<http://search.cpan.org/perldoc?App::cpanminus#INSTALLATION> 

=head1 USAGE

    locket [options] setup|edit|<query>

        --delay <delay>     Keep value in clipboard for <delay> seconds
                            If value is still in the clipboard at the end of
                            <delay> then it will be automatically wiped from
                            the clipboard

        --unsafe            Turn the safety off. This will disable prompting
                            before emitting any sensitive information in
                            plaintext. There will be no opportunity to
                            abort (via CTRL-C)

        setup               Setup a new or edit an existing user configuration
                            file (~/.locket/cfg)

        edit                Edit the cipherstore
                            The configuration must have an "edit" value, e.g.:

                                /usr/bin/vim -n ~/.locket.gpg


        /<query>            Search the cipherstore for <query> and emit the
                            resulting secret
                            
                            The configuration must have a "read" value to
                            tell it how to read the cipherstore. Only piped
                            commands are supported today, and they should
                            be something like:

                                </usr/local/bin/gpg -q --no-tty -d ~/.locket.gpg'

                            If the found key in the cipherstore is of the format
                            "<username>@<site>" then the username will be emitted