• Stars
    star
    238
  • Rank 169,306 (Top 4 %)
  • Language
    Python
  • License
    Apache License 2.0
  • Created over 7 years ago
  • Updated about 6 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

An easy, fast lib to correctly password-protect your data

Privy

https://img.shields.io/pypi/v/privy.svg?style=flat-square https://img.shields.io/travis/ofek/privy/master.svg?style=flat-square https://img.shields.io/codecov/c/github/ofek/privy/master.svg?style=flat-square https://img.shields.io/pypi/pyversions/privy.svg?style=flat-square https://img.shields.io/pypi/l/privy.svg?style=flat-square

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

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

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

More Repositories

1

bit

Bitcoin made easy.
Python
1,240
star
2

pyapp

Runtime installer for Python applications
Rust
1,198
star
3

pypinfo

Easily view PyPI download statistics via Google's BigQuery.
Python
364
star
4

csi-gcs

Kubernetes CSI driver for Google Cloud Storage
Go
152
star
5

userpath

Cross-platform tool for adding locations to the user PATH, no elevated privileges required!
Python
129
star
6

coincurve

Cross-platform Python bindings for libsecp256k1
Python
128
star
7

hatch-vcs

Hatch plugin for versioning with your preferred VCS
Python
102
star
8

hatch-mypyc

Hatch build hook plugin for Mypyc
Python
36
star
9

venum

Verifiably better, validated Enum for Python
Python
31
star
10

hatch-showcase

A project showcasing features and plugins for Hatch
Python
26
star
11

extensionlib

The toolkit for building extension modules
Python
25
star
12

hatch-containers

Hatch plugin for Docker containers
Python
22
star
13

pybin

Cross-platform tool to put Python's user bin in PATH, no sudo/runas required!
Python
21
star
14

rusty

Rusty example CLI
Rust
14
star
15

binary

Easily convert between binary and SI units (kibibyte, kilobyte, etc.).
Python
9
star
16

terminal-demo

Produce GIFs from shell commands
Python
9
star
17

dep-sync

Synchronize Python environments with dependencies
Python
9
star
18

hatch-autorun

Hatch build hook plugin to inject code that will automatically run
Python
7
star
19

msgspec-click

Generate Click options from msgspec types
Python
7
star
20

pyproject-validate

Validate and format pyproject.toml files
Python
4
star
21

depq

CPython double-ended priority queue (DEPQ)
Python
3
star
22

mkpatcher

Python-Markdown extension allowing arbitrary scripts to modify MkDocs input files
Python
2
star
23

katutil

utilities for automating tasks on KickassTorrents
Python
2
star
24

ofek

Python
2
star
25

find-exe

Find matching executables
Python
2
star
26

spry

Modern file transfer utility supporting HTTPS & SFTP.
Python
2
star
27

talks

Collection of potential talks and associated materials
2
star
28

ink

Digital signatures made easy.
Python
1
star
29

pyoxidizer-build-example

Repo showing how to build PyOxidizer executables for every platform
Starlark
1
star
30

perplex

Perpetual Plex in the Cloud
Python
1
star
31

everlib

Everlasting media library backed by cloud storage
Python
1
star