Privy

Privy is a small and fast utility for password-protecting secret data such as
API keys, cryptocurrency wallets, or seeds for digital signatures.
Table of Contents

.. contents::
    :backlinks: top
    :local:

Usage
-----

Say for example you are using GnuPG. You are about to sign a message but it first
requires your password. Does your password become the input to unlock your stored
private key? No, it is first hashed by a secure `key derivation function`_. That
hash then becomes the input to a symmetric cipher such as AES which then decrypts
your stored private key. That is what Privy does.

Fear not! With Privy, this become trivially easy:

.. code-block:: python

    >>> import privy
    >>>
    >>> # After creating secret, immediately encrypt it using Privy.
    >>> data = b'secret'
    >>>
    >>> hidden = privy.hide(data, ask_for_password())
    >>> hidden
    '1$2$fL7xRh8WKe...'

Now you can safely store or transmit the hidden secret. Whenever your user needs
to use their secret again, ask for their password to take a peek.

.. code-block:: python

    >>> privy.peek(hidden, password)
    b'secret'

Installation
------------

Privy is available on Linux/macOS and Windows and supports Python 2.7, 3.3+, PyPy, and PyPy3.3-5.5+.

.. code-block:: bash

    $ pip install privy

Encryption scheme
-----------------

Secrets are encrypted using the `Fernet`_ protocol. Specifically, it uses AES for
encryption and has built-in authentication using HMAC. The private key used for
encryption is derived from the password using a `key derivation function`_. The
key derivation function used is `Argon2`_, the winner of the `Password Hashing
Competition`_. Both Argon2i and Argon2d variants are supported.

Encrypted format
----------------

``ascii(Argon2 algorithm, security level, base64(salt), base64(Fernet token))``

API
---

There are 2 functions: ``hide`` and ``peek``.

hide
^^^^

``hide(secret, password, security=2, salt=None, server=True)``

Encrypts ``secret`` using ``password``. Returns the hidden secret as unicode.

* Parameters

  - **secret** (``bytes``) - The secret to encrypt.
  - **password** (``bytes`` or ``unicode``) - The password used to access the secret.
  - **security** (``int``) - A number 0-20 inclusive. Higher values are more secure at
    the cost of slower computation and greater use of memory. See `security levels`_.
  - **salt** (``bytes``) - The salt used for the password hash. Defaults to ``os.urandom(32)``.
  - **server** (``bool``) - If ``True``, it is assumed side-channel attack protection is
    needed and therefore the Argon2i algorithm will be used. Otherwise, the password will
    be hashed using the Argon2d algorithm.

peek
^^^^

``peek(hidden, password, expires=None)``

Decrypts ``hidden`` using ``password``. Returns the secret as ``bytes``.

* Parameters

  - **hidden** (``bytes`` or ``unicode``) - The hidden secret to decrypt.
  - **password** (``bytes`` or ``unicode``) - The password used to access the secret.
  - **expires** (``int``) - The maximum number of seconds since encryption that
    is allowed. The default is no expiration.

A ``ValueError`` will be raised if the password is wrong, the password was attempted on a
different hidden secret, or the number of seconds since encryption is > ``expires`` argument.

Security levels
---------------

All expected times were taken from tests on an Intel Core i7-2670QM @ 2.2 GHz when decrypting
a 256 KiB secret.

This is the command, where ``SL`` is the desired security level:

.. code-block:: bash

    $ python -m timeit -s "import privy, os; pw = 'password'; s = os.urandom(1024 * 256); h = privy.hide(s, pw, SL)" "privy.peek(h, pw)"

+--------+-----------------+---------------+-----------------+, Levels, Argon2 settings, Expected time, Notes, +========+=================+===============+=================+, m=8 KiB, t=1, 7 msec, Lowest possible, +--------+-----------------+---------------+-----------------+, 1, m=4 MiB, t=10, 54 msec, +--------+-----------------+---------------+-----------------+, 2, m=8 MiB, t=10, 99 msec, Default, +--------+-----------------+---------------+-----------------+, 3, m=32 MiB, t=10, 367 msec, +--------+-----------------+---------------+-----------------+, 4, m=48 MiB, t=10, 540 msec, +--------+-----------------+---------------+-----------------+, 5, m=96 MiB, t=10, 1.1 sec, Good choice, +--------+-----------------+---------------+-----------------+, 6, m=256 MiB, t=10, 3 sec, +--------+-----------------+---------------+-----------------+, 7, m=512 MiB, t=10, 6 sec, +--------+-----------------+---------------+-----------------+, 8, m=768 MiB, t=10, 9 sec, +--------+-----------------+---------------+-----------------+, 9, m=1 GiB, t=10, 12.2 sec, +--------+-----------------+---------------+-----------------+, 10, m=2 GiB, t=20, 48 sec, For use on, +--------+-----------------+---------------+ users' machines, 11, m=3 GiB, t=30, 107, +--------+-----------------+---------------+, 12, m=4 GiB, t=40, ?, +--------+-----------------+---------------+, 13, m=5 GiB, t=50, ?, +--------+-----------------+---------------+, 14, m=6 GiB, t=60, ?, +--------+-----------------+---------------+, 15, m=7 GiB, t=70, ?, +--------+-----------------+---------------+, 16, m=8 GiB, t=80, ?, +--------+-----------------+---------------+, 17, m=9 GiB, t=90, ?, +--------+-----------------+---------------+, 18, m=10 GiB, t=100, ?, +--------+-----------------+---------------+, 19, m=11 GiB, t=110, ?, +--------+-----------------+---------------+, 20, m=12 GiB, t=120, ?, +--------+-----------------+---------------+-----------------+

License
-------

Privy is distributed under the terms of either

- `MIT License <https://choosealicense.com/licenses/mit>`_
- `Apache License, Version 2.0 <https://choosealicense.com/licenses/apache-2.0>`_

at your option.

Changelog
---------

Important changes are emphasized.

6.0.0
^^^^^

* **Breaking:** Support for Python 3.3 has been dropped.

5.0.0
^^^^^

* **Breaking:** Privy is now dual-licensed under the terms of MIT and Apache v2.0.
* Only documented methods ``hide`` and ``peek`` are now exposed in the root namespace.
* Travis now runs tests with the latest versions of PyPy and PyPy3.
* Improvements to documentation.

4.0.0
^^^^^

* **Breaking:** For saner conformity, security level 7 now utilizes 512 MiB of RAM instead of 448.
* Major improvements to documentation.

3.0.0
^^^^^

* Added security levels 11-20. These are quite resource intensive and are therefore
  only acceptable for individual use.

2.0.1
^^^^^

* **Breaking:** Due to requests, the encrypted format now uses url-safe base64 instead of hex.

1.0.0
^^^^^

* Initial release

.. _Fernet: https://github.com/fernet/spec/blob/master/Spec.md
.. _key derivation function: https://en.wikipedia.org/wiki/Key_derivation_function
.. _Argon2: https://github.com/p-h-c/phc-winner-argon2
.. _Password Hashing Competition: https://en.wikipedia.org/wiki/Password_Hashing_Competition
.. _security levels: https://github.com/ofek/privy#security-levels
Name With Owner	ofek/privy
Primary Language	Python
Program language	Python (Language Count: 1)
Platform
License:	Apache License 2.0
Created At	2017-02-13 20:51:52
Pushed At	2018-11-06 19:13:42
Last Commit At	2018-01-22 17:39:40
Release Count	0
Stargazers Count	255
Watchers Count	16
Fork Count	14
Commits Count	67
Has Issues Enabled
Issues Count	0
Issue Open Count	0
Pull Requests Count	0
Pull Requests Open Count	1
Pull Requests Close Count	0
Has Wiki Enabled
Is Archived
Is Fork
Is Locked
Is Mirror
Is Private
privy

Github stars Tracking Chart

Privy

Main metrics
