README.rst

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

• Usage
• Installation
• Encryption scheme
• Encrypted format
• API
  • hide
  • peek
• Security levels
• License
• Changelog
  • 6.0.0
  • 5.0.0
  • 4.0.0
  • 3.0.0
  • 2.0.1
  • 1.0.0

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:

>>> 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.

>>> 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+.

$ 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:

$ 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
0	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
• Apache License, Version 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