Upgrade cryptography from 2.5 to 3.3
Source code is from https://github.com/pyca/cryptography/tree/3.3.x
Run setup.py locally and rename _openssl.so/_padding.so
Bug: 205265538
Test: None
Change-Id: If031739ef5830ba2fb177add74515e4660e2906e
diff --git a/docs/api-stability.rst b/docs/api-stability.rst
index 205b184..fd34ced 100644
--- a/docs/api-stability.rst
+++ b/docs/api-stability.rst
@@ -1,7 +1,7 @@
API stability
=============
-From its first release, ``cryptography`` will have a strong API stability
+From its first release, ``cryptography`` has had a strong API stability
policy.
What does this policy cover?
diff --git a/docs/conf.py b/docs/conf.py
index 4349b05..fb67ada 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -35,7 +35,7 @@
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath("."))
# -- General configuration ----------------------------------------------------
@@ -45,33 +45,33 @@
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
- 'sphinx.ext.autodoc',
- 'sphinx.ext.doctest',
- 'sphinx.ext.intersphinx',
- 'sphinx.ext.viewcode',
- 'cryptography-docs',
+ "sphinx.ext.autodoc",
+ "sphinx.ext.doctest",
+ "sphinx.ext.intersphinx",
+ "sphinx.ext.viewcode",
+ "cryptography-docs",
]
if spelling is not None:
- extensions.append('sphinxcontrib.spelling')
+ extensions.append("sphinxcontrib.spelling")
# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
nitpicky = True
# The suffix of source filenames.
-source_suffix = '.rst'
+source_suffix = ".rst"
# The encoding of source files.
# source_encoding = 'utf-8-sig'
# The master toctree document.
-master_doc = 'index'
+master_doc = "index"
# General information about the project.
-project = 'Cryptography'
-copyright = '2013-2017, Individual Contributors'
+project = "Cryptography"
+copyright = "2013-2021, Individual Contributors"
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
@@ -81,7 +81,7 @@
base_dir = os.path.join(os.path.dirname(__file__), os.pardir)
about = {}
with open(os.path.join(base_dir, "src", "cryptography", "__about__.py")) as f:
- exec(f.read(), about)
+ exec (f.read(), about)
version = release = about["__version__"]
@@ -97,7 +97,7 @@
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
-exclude_patterns = ['_build']
+exclude_patterns = ["_build"]
# The reST default role (used for this markup: `text`) to use for all documents
# default_role = None
@@ -114,7 +114,7 @@
# show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = "sphinx"
# -- Options for HTML output --------------------------------------------------
@@ -130,22 +130,26 @@
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ["_static"]
# Output file base name for HTML help builder.
-htmlhelp_basename = 'Cryptographydoc'
+htmlhelp_basename = "Cryptographydoc"
# -- Options for LaTeX output -------------------------------------------------
-latex_elements = {
-}
+latex_elements = {}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual])
latex_documents = [
- ('index', 'Cryptography.tex', 'Cryptography Documentation',
- 'Individual Contributors', 'manual'),
+ (
+ "index",
+ "Cryptography.tex",
+ "Cryptography Documentation",
+ "Individual Contributors",
+ "manual",
+ ),
]
# -- Options for manual page output -------------------------------------------
@@ -153,8 +157,13 @@
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
- ('index', 'cryptography', 'Cryptography Documentation',
- ['Individual Contributors'], 1)
+ (
+ "index",
+ "cryptography",
+ "Cryptography Documentation",
+ ["Individual Contributors"],
+ 1,
+ )
]
# -- Options for Texinfo output -----------------------------------------------
@@ -163,22 +172,31 @@
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
- ('index', 'Cryptography', 'Cryptography Documentation',
- 'Individual Contributors', 'Cryptography',
- 'One line description of project.',
- 'Miscellaneous'),
+ (
+ "index",
+ "Cryptography",
+ "Cryptography Documentation",
+ "Individual Contributors",
+ "Cryptography",
+ "One line description of project.",
+ "Miscellaneous",
+ ),
]
# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/3': None}
+intersphinx_mapping = {"https://docs.python.org/3": None}
-epub_theme = 'epub'
+epub_theme = "epub"
# Retry requests in the linkcheck builder so that we're resillient against
# transient network errors.
linkcheck_retries = 10
+linkcheck_timeout = 5
+
linkcheck_ignore = [
# Small DH key results in a TLS failure on modern OpenSSL
- "https://info.isl.ntt.co.jp/crypt/eng/camellia/",
+ r"https://info.isl.ntt.co.jp/crypt/eng/camellia/",
+ # Inconsistent small DH params they seem incapable of fixing
+ r"https://www.secg.org/sec1-v2.pdf",
]
diff --git a/docs/development/c-bindings.rst b/docs/development/c-bindings.rst
index 1b58dab..e53e0ba 100644
--- a/docs/development/c-bindings.rst
+++ b/docs/development/c-bindings.rst
@@ -5,7 +5,7 @@
.. _cffi: https://cffi.readthedocs.io
-Bindings live in :py:mod:`cryptography.hazmat.bindings`.
+Bindings live in ``cryptography.hazmat.bindings``.
When modifying the bindings you will need to recompile the C extensions to
test the changes. This can be accomplished with ``pip install -e .`` in the
@@ -189,9 +189,9 @@
Sometimes, a set of loosely related features are added in the same
version, and it's impractical to create ``#ifdef`` statements for each
one. In that case, it may make sense to either check for a particular
-version. For example, to check for OpenSSL 1.1.0 or newer::
+version. For example, to check for OpenSSL 1.1.1 or newer::
- #if CRYPTOGRAPHY_OPENSSL_110_OR_GREATER
+ #if CRYPTOGRAPHY_OPENSSL_111_OR_GREATER
Sometimes, the version of a library on a particular platform will have
features that you thought it wouldn't, based on its version.
diff --git a/docs/development/custom-vectors/arc4/generate_arc4.py b/docs/development/custom-vectors/arc4/generate_arc4.py
index 3dee44a..2ca85c9 100644
--- a/docs/development/custom-vectors/arc4/generate_arc4.py
+++ b/docs/development/custom-vectors/arc4/generate_arc4.py
@@ -12,10 +12,14 @@
_RFC6229_KEY_MATERIALS = [
- (True,
- 8 * '0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20'),
- (False,
- 8 * '1ada31d5cf688221c109163908ebe51debb46227c6cc8b37641910833222772a')
+ (
+ True,
+ 8 * "0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20",
+ ),
+ (
+ False,
+ 8 * "1ada31d5cf688221c109163908ebe51debb46227c6cc8b37641910833222772a",
+ ),
]
@@ -37,42 +41,43 @@
3056,
3072,
4080,
- 4096
+ 4096,
]
-_SIZES_TO_GENERATE = [
- 160
-]
+_SIZES_TO_GENERATE = [160]
def _key_for_size(size, keyinfo):
msb, key = keyinfo
if msb:
- return key[:size // 4]
+ return key[: size // 4]
else:
- return key[-size // 4:]
+ return key[-size // 4 :]
def _build_vectors():
count = 0
output = []
key = None
- plaintext = binascii.unhexlify(32 * '0')
+ plaintext = binascii.unhexlify(32 * "0")
for size in _SIZES_TO_GENERATE:
for keyinfo in _RFC6229_KEY_MATERIALS:
key = _key_for_size(size, keyinfo)
cipher = ciphers.Cipher(
algorithms.ARC4(binascii.unhexlify(key)),
None,
- default_backend())
+ default_backend(),
+ )
encryptor = cipher.encryptor()
current_offset = 0
for offset in _RFC6229_OFFSETS:
if offset % 16 != 0:
raise ValueError(
- "Offset {} is not evenly divisible by 16"
- .format(offset))
+ "Offset {} is not evenly divisible by 16".format(
+ offset
+ )
+ )
while current_offset < offset:
encryptor.update(plaintext)
current_offset += len(plaintext)
@@ -80,19 +85,23 @@
count += 1
output.append("KEY = {}".format(key))
output.append("OFFSET = {}".format(offset))
- output.append("PLAINTEXT = {}".format(
- binascii.hexlify(plaintext)))
- output.append("CIPHERTEXT = {}".format(
- binascii.hexlify(encryptor.update(plaintext))))
+ output.append(
+ "PLAINTEXT = {}".format(binascii.hexlify(plaintext))
+ )
+ output.append(
+ "CIPHERTEXT = {}".format(
+ binascii.hexlify(encryptor.update(plaintext))
+ )
+ )
current_offset += len(plaintext)
assert not encryptor.finalize()
return "\n".join(output)
def _write_file(data, filename):
- with open(filename, 'w') as f:
+ with open(filename, "w") as f:
f.write(data)
-if __name__ == '__main__':
- _write_file(_build_vectors(), 'arc4.txt')
+if __name__ == "__main__":
+ _write_file(_build_vectors(), "arc4.txt")
diff --git a/docs/development/custom-vectors/cast5/generate_cast5.py b/docs/development/custom-vectors/cast5/generate_cast5.py
index a0e28e3..5208b90 100644
--- a/docs/development/custom-vectors/cast5/generate_cast5.py
+++ b/docs/development/custom-vectors/cast5/generate_cast5.py
@@ -14,7 +14,7 @@
cipher = base.Cipher(
algorithms.CAST5(binascii.unhexlify(key)),
mode(binascii.unhexlify(iv)),
- default_backend()
+ default_backend(),
)
encryptor = cipher.encryptor()
ct = encryptor.update(binascii.unhexlify(plaintext))
@@ -23,33 +23,36 @@
def build_vectors(mode, filename):
- vector_file = open(filename, "r")
-
count = 0
output = []
key = None
iv = None
plaintext = None
- for line in vector_file:
- line = line.strip()
- if line.startswith("KEY"):
- if count != 0:
- output.append("CIPHERTEXT = {}".format(
- encrypt(mode, key, iv, plaintext))
- )
- output.append("\nCOUNT = {}".format(count))
- count += 1
- name, key = line.split(" = ")
- output.append("KEY = {}".format(key))
- elif line.startswith("IV"):
- name, iv = line.split(" = ")
- iv = iv[0:16]
- output.append("IV = {}".format(iv))
- elif line.startswith("PLAINTEXT"):
- name, plaintext = line.split(" = ")
- output.append("PLAINTEXT = {}".format(plaintext))
- output.append("CIPHERTEXT = {}".format(encrypt(mode, key, iv, plaintext)))
+ with open(filename, "r") as vector_file:
+ for line in vector_file:
+ line = line.strip()
+ if line.startswith("KEY"):
+ if count != 0:
+ output.append(
+ "CIPHERTEXT = {}".format(
+ encrypt(mode, key, iv, plaintext)
+ )
+ )
+ output.append("\nCOUNT = {}".format(count))
+ count += 1
+ name, key = line.split(" = ")
+ output.append("KEY = {}".format(key))
+ elif line.startswith("IV"):
+ name, iv = line.split(" = ")
+ iv = iv[0:16]
+ output.append("IV = {}".format(iv))
+ elif line.startswith("PLAINTEXT"):
+ name, plaintext = line.split(" = ")
+ output.append("PLAINTEXT = {}".format(plaintext))
+ output.append(
+ "CIPHERTEXT = {}".format(encrypt(mode, key, iv, plaintext))
+ )
return "\n".join(output)
diff --git a/docs/development/custom-vectors/hkdf/generate_hkdf.py b/docs/development/custom-vectors/hkdf/generate_hkdf.py
index 767aedd..aa2fc27 100644
--- a/docs/development/custom-vectors/hkdf/generate_hkdf.py
+++ b/docs/development/custom-vectors/hkdf/generate_hkdf.py
@@ -13,27 +13,31 @@
IKM = binascii.unhexlify(b"0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b")
L = 1200
OKM = HKDF(
- algorithm=hashes.SHA256(), length=L, salt=None, info=None,
- backend=default_backend()
+ algorithm=hashes.SHA256(),
+ length=L,
+ salt=None,
+ info=None,
+ backend=default_backend(),
).derive(IKM)
def _build_vectors():
- output = []
- output.append("COUNT = 0")
- output.append("Hash = SHA-256")
- output.append("IKM = " + binascii.hexlify(IKM).decode("ascii"))
- output.append("salt = ")
- output.append("info = ")
- output.append("L = {}".format(L))
- output.append("OKM = " + binascii.hexlify(OKM).decode("ascii"))
+ output = [
+ "COUNT = 0",
+ "Hash = SHA-256",
+ "IKM = " + binascii.hexlify(IKM).decode("ascii"),
+ "salt = ",
+ "info = ",
+ "L = {}".format(L),
+ "OKM = " + binascii.hexlify(OKM).decode("ascii"),
+ ]
return "\n".join(output)
def _write_file(data, filename):
- with open(filename, 'w') as f:
+ with open(filename, "w") as f:
f.write(data)
-if __name__ == '__main__':
- _write_file(_build_vectors(), 'hkdf.txt')
+if __name__ == "__main__":
+ _write_file(_build_vectors(), "hkdf.txt")
diff --git a/docs/development/custom-vectors/idea/generate_idea.py b/docs/development/custom-vectors/idea/generate_idea.py
index 2eb6996..0030956 100644
--- a/docs/development/custom-vectors/idea/generate_idea.py
+++ b/docs/development/custom-vectors/idea/generate_idea.py
@@ -8,7 +8,7 @@
cipher = base.Cipher(
algorithms.IDEA(binascii.unhexlify(key)),
mode(binascii.unhexlify(iv)),
- backend
+ backend,
)
encryptor = cipher.encryptor()
ct = encryptor.update(binascii.unhexlify(plaintext))
@@ -29,8 +29,10 @@
line = line.strip()
if line.startswith("KEY"):
if count != 0:
- output.append("CIPHERTEXT = {0}".format(
- encrypt(mode, key, iv, plaintext))
+ output.append(
+ "CIPHERTEXT = {0}".format(
+ encrypt(mode, key, iv, plaintext)
+ )
)
output.append("\nCOUNT = {0}".format(count))
count += 1
diff --git a/docs/development/custom-vectors/idea/verify_idea.py b/docs/development/custom-vectors/idea/verify_idea.py
index 89713c8..d356de0 100644
--- a/docs/development/custom-vectors/idea/verify_idea.py
+++ b/docs/development/custom-vectors/idea/verify_idea.py
@@ -8,11 +8,13 @@
def encrypt(mode, key, iv, plaintext):
- encryptor = botan.Cipher("IDEA/{0}/NoPadding".format(mode), "encrypt",
- binascii.unhexlify(key))
+ encryptor = botan.Cipher(
+ "IDEA/{0}/NoPadding".format(mode), "encrypt", binascii.unhexlify(key)
+ )
- cipher_text = encryptor.cipher(binascii.unhexlify(plaintext),
- binascii.unhexlify(iv))
+ cipher_text = encryptor.cipher(
+ binascii.unhexlify(plaintext), binascii.unhexlify(iv)
+ )
return binascii.hexlify(cipher_text)
@@ -22,12 +24,7 @@
vectors = load_nist_vectors(vector_file)
for vector in vectors:
- ct = encrypt(
- mode,
- vector["key"],
- vector["iv"],
- vector["plaintext"]
- )
+ ct = encrypt(mode, vector["key"], vector["iv"], vector["plaintext"])
assert ct == vector["ciphertext"]
diff --git a/docs/development/custom-vectors/rsa-oaep-sha2/generate_rsa_oaep_sha2.py b/docs/development/custom-vectors/rsa-oaep-sha2/generate_rsa_oaep_sha2.py
index bd5148f..a43e150 100644
--- a/docs/development/custom-vectors/rsa-oaep-sha2/generate_rsa_oaep_sha2.py
+++ b/docs/development/custom-vectors/rsa-oaep-sha2/generate_rsa_oaep_sha2.py
@@ -62,9 +62,8 @@
dmq1=private["dmq1"],
iqmp=private["iqmp"],
public_numbers=rsa.RSAPublicNumbers(
- e=private["public_exponent"],
- n=private["modulus"]
- )
+ e=private["public_exponent"], n=private["modulus"]
+ ),
).private_key(backend)
count = 1
@@ -74,8 +73,8 @@
padding.OAEP(
mgf=padding.MGF1(algorithm=hashes.SHA1()),
algorithm=hashes.SHA1(),
- label=None
- )
+ label=None,
+ ),
)
assert message == binascii.unhexlify(example["message"])
ct = pkey.encrypt(
@@ -83,8 +82,8 @@
padding.OAEP(
mgf=padding.MGF1(algorithm=mgf1alg),
algorithm=hashalg,
- label=None
- )
+ label=None,
+ ),
)
output.append(
b"# OAEP Example {0} alg={1} mgf1={2}".format(
@@ -116,13 +115,12 @@
hashes.SHA512(),
]
for hashtuple in itertools.product(hashalgs, hashalgs):
- if (
- isinstance(hashtuple[0], hashes.SHA1) and
- isinstance(hashtuple[1], hashes.SHA1)
+ if isinstance(hashtuple[0], hashes.SHA1) and isinstance(
+ hashtuple[1], hashes.SHA1
):
continue
write_file(
build_vectors(hashtuple[0], hashtuple[1], oaep_path),
- "oaep-{0}-{1}.txt".format(hashtuple[0].name, hashtuple[1].name)
+ "oaep-{0}-{1}.txt".format(hashtuple[0].name, hashtuple[1].name),
)
diff --git a/docs/development/custom-vectors/secp256k1/generate_secp256k1.py b/docs/development/custom-vectors/secp256k1/generate_secp256k1.py
index d6a2071..bfb150b 100644
--- a/docs/development/custom-vectors/secp256k1/generate_secp256k1.py
+++ b/docs/development/custom-vectors/secp256k1/generate_secp256k1.py
@@ -10,9 +10,7 @@
from cryptography_vectors import open_vector_file
-from tests.utils import (
- load_fips_ecdsa_signing_vectors, load_vectors_from_file
-)
+from tests.utils import load_fips_ecdsa_signing_vectors, load_vectors_from_file
HASHLIB_HASH_TYPES = {
"SHA-1": hashlib.sha1,
@@ -32,13 +30,13 @@
return self
def digest(self):
- return self.hasher.digest()[:256 // 8]
+ return self.hasher.digest()[: 256 // 8]
def build_vectors(fips_vectors):
vectors = defaultdict(list)
for vector in fips_vectors:
- vectors[vector['digest_algorithm']].append(vector['message'])
+ vectors[vector["digest_algorithm"]].append(vector["message"])
for digest_algorithm, messages in vectors.items():
if digest_algorithm not in HASHLIB_HASH_TYPES:
@@ -55,8 +53,9 @@
# Sign the message using warner/ecdsa
secret_key = SigningKey.generate(curve=SECP256k1)
public_key = secret_key.get_verifying_key()
- signature = secret_key.sign(message, hashfunc=hash_func,
- sigencode=sigencode_der)
+ signature = secret_key.sign(
+ message, hashfunc=hash_func, sigencode=sigencode_der
+ )
r, s = sigdecode_der(signature, None)
@@ -79,12 +78,8 @@
dest_path = os.path.join("asymmetric", "ECDSA", "SECP256K1", "SigGen.txt")
fips_vectors = load_vectors_from_file(
- source_path,
- load_fips_ecdsa_signing_vectors
+ source_path, load_fips_ecdsa_signing_vectors
)
with open_vector_file(dest_path, "w") as dest_file:
- write_file(
- build_vectors(fips_vectors),
- dest_file
- )
+ write_file(build_vectors(fips_vectors), dest_file)
diff --git a/docs/development/custom-vectors/secp256k1/verify_secp256k1.py b/docs/development/custom-vectors/secp256k1/verify_secp256k1.py
index b236d77..f721b00 100644
--- a/docs/development/custom-vectors/secp256k1/verify_secp256k1.py
+++ b/docs/development/custom-vectors/secp256k1/verify_secp256k1.py
@@ -6,12 +6,10 @@
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import ec
from cryptography.hazmat.primitives.asymmetric.utils import (
- encode_dss_signature
+ encode_dss_signature,
)
-from tests.utils import (
- load_fips_ecdsa_signing_vectors, load_vectors_from_file
-)
+from tests.utils import load_fips_ecdsa_signing_vectors, load_vectors_from_file
CRYPTOGRAPHY_HASH_TYPES = {
"SHA-1": hashes.SHA1,
@@ -23,37 +21,32 @@
def verify_one_vector(vector):
- digest_algorithm = vector['digest_algorithm']
- message = vector['message']
- x = vector['x']
- y = vector['y']
- signature = encode_dss_signature(vector['r'], vector['s'])
+ digest_algorithm = vector["digest_algorithm"]
+ message = vector["message"]
+ x = vector["x"]
+ y = vector["y"]
+ signature = encode_dss_signature(vector["r"], vector["s"])
- numbers = ec.EllipticCurvePublicNumbers(
- x, y,
- ec.SECP256K1()
- )
+ numbers = ec.EllipticCurvePublicNumbers(x, y, ec.SECP256K1())
key = numbers.public_key(default_backend())
verifier = key.verifier(
- signature,
- ec.ECDSA(CRYPTOGRAPHY_HASH_TYPES[digest_algorithm]())
+ signature, ec.ECDSA(CRYPTOGRAPHY_HASH_TYPES[digest_algorithm]())
)
verifier.update(message)
- return verifier.verify()
+ verifier.verify()
def verify_vectors(vectors):
for vector in vectors:
- assert verify_one_vector(vector)
+ verify_one_vector(vector)
vector_path = os.path.join("asymmetric", "ECDSA", "SECP256K1", "SigGen.txt")
secp256k1_vectors = load_vectors_from_file(
- vector_path,
- load_fips_ecdsa_signing_vectors
+ vector_path, load_fips_ecdsa_signing_vectors
)
verify_vectors(secp256k1_vectors)
diff --git a/docs/development/custom-vectors/seed/generate_seed.py b/docs/development/custom-vectors/seed/generate_seed.py
index 5c62d67..046fcfb 100644
--- a/docs/development/custom-vectors/seed/generate_seed.py
+++ b/docs/development/custom-vectors/seed/generate_seed.py
@@ -8,7 +8,7 @@
cipher = base.Cipher(
algorithms.SEED(binascii.unhexlify(key)),
mode(binascii.unhexlify(iv)),
- backend
+ backend,
)
encryptor = cipher.encryptor()
ct = encryptor.update(binascii.unhexlify(plaintext))
@@ -29,8 +29,10 @@
line = line.strip()
if line.startswith("KEY"):
if count != 0:
- output.append("CIPHERTEXT = {0}".format(
- encrypt(mode, key, iv, plaintext))
+ output.append(
+ "CIPHERTEXT = {0}".format(
+ encrypt(mode, key, iv, plaintext)
+ )
)
output.append("\nCOUNT = {0}".format(count))
count += 1
diff --git a/docs/development/custom-vectors/seed/verify_seed.py b/docs/development/custom-vectors/seed/verify_seed.py
index e626428..252088d 100644
--- a/docs/development/custom-vectors/seed/verify_seed.py
+++ b/docs/development/custom-vectors/seed/verify_seed.py
@@ -6,11 +6,13 @@
def encrypt(mode, key, iv, plaintext):
- encryptor = botan.Cipher("SEED/{0}/NoPadding".format(mode), "encrypt",
- binascii.unhexlify(key))
+ encryptor = botan.Cipher(
+ "SEED/{0}/NoPadding".format(mode), "encrypt", binascii.unhexlify(key)
+ )
- cipher_text = encryptor.cipher(binascii.unhexlify(plaintext),
- binascii.unhexlify(iv))
+ cipher_text = encryptor.cipher(
+ binascii.unhexlify(plaintext), binascii.unhexlify(iv)
+ )
return binascii.hexlify(cipher_text)
@@ -20,12 +22,7 @@
vectors = load_nist_vectors(vector_file)
for vector in vectors:
- ct = encrypt(
- mode,
- vector["key"],
- vector["iv"],
- vector["plaintext"]
- )
+ ct = encrypt(mode, vector["key"], vector["iv"], vector["plaintext"])
assert ct == vector["ciphertext"]
diff --git a/docs/development/getting-started.rst b/docs/development/getting-started.rst
index cc333e4..1d939a9 100644
--- a/docs/development/getting-started.rst
+++ b/docs/development/getting-started.rst
@@ -81,7 +81,7 @@
...
py27: commands succeeded
ERROR: pypy: InterpreterNotFound: pypy
- py34: commands succeeded
+ py38: commands succeeded
docs: commands succeeded
pep8: commands succeeded
diff --git a/docs/development/reviewing-patches.rst b/docs/development/reviewing-patches.rst
index bd3ee96..0844618 100644
--- a/docs/development/reviewing-patches.rst
+++ b/docs/development/reviewing-patches.rst
@@ -7,18 +7,18 @@
When reviewing a patch try to keep each of these concepts in mind:
-Architecture
-------------
-
-* Is the proposed change being made in the correct place? Is it a fix in a
- backend when it should be in the primitives?
-
Intent
------
* What is the change being proposed?
* Do we want this feature or is the bug they're fixing really a bug?
+Architecture
+------------
+
+* Is the proposed change being made in the correct place? Is it a fix in a
+ backend when it should be in the primitives?
+
Implementation
--------------
diff --git a/docs/development/submitting-patches.rst b/docs/development/submitting-patches.rst
index ec00aa5..b4ed175 100644
--- a/docs/development/submitting-patches.rst
+++ b/docs/development/submitting-patches.rst
@@ -19,9 +19,10 @@
----
When in doubt, refer to :pep:`8` for Python code. You can check if your code
-meets our automated requirements by running ``flake8`` against it. If you've
-installed the development requirements this will automatically use our
-configuration. You can also run the ``tox`` job with ``tox -e pep8``.
+meets our automated requirements by formatting it with ``black`` and running
+``flake8`` against it. If you've installed the development requirements this
+will automatically use our configuration. You can also run the ``tox`` job with
+``tox -e pep8``.
`Write comments as complete sentences.`_
@@ -80,10 +81,9 @@
output in order to allow transparent upgrading of the algorithms in use, as
the algorithms or parameters needed to achieve a given security margin evolve.
-APIs at the :doc:`/hazmat/primitives/index` layer should always take an
-explicit backend, APIs at the recipes layer should automatically use the
-:func:`~cryptography.hazmat.backends.default_backend`, but optionally allow
-specifying a different backend.
+APIs at the :doc:`/hazmat/primitives/index` and recipes layer should
+automatically use the :func:`~cryptography.hazmat.backends.default_backend`,
+but optionally allow specifying a different backend.
C bindings
~~~~~~~~~~
@@ -156,6 +156,6 @@
.. _`Write comments as complete sentences.`: https://nedbatchelder.com/blog/201401/comments_should_be_sentences.html
.. _`syntax`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists
-.. _`Studies have shown`: https://smartbear.com/SmartBear/media/pdfs/11_Best_Practices_for_Peer_Code_Review.pdf
+.. _`Studies have shown`: https://smartbear.com/learn/code-review/best-practices-for-peer-code-review/
.. _`our mailing list`: https://mail.python.org/mailman/listinfo/cryptography-dev
.. _`doc8`: https://github.com/openstack/doc8
diff --git a/docs/development/test-vectors.rst b/docs/development/test-vectors.rst
index df1ecfa..f952337 100644
--- a/docs/development/test-vectors.rst
+++ b/docs/development/test-vectors.rst
@@ -23,7 +23,7 @@
continuous integration environments.
We have ensured all test vectors are used as of commit
-``c313761979d74b0417230eddd0f87d0cfab2b46b``.
+``2196000605e45d91097147c9c71f26b72af58003``.
Asymmetric ciphers
~~~~~~~~~~~~~~~~~~
@@ -78,6 +78,8 @@
* ``asymmetric/PEM_Serialization/rsa_public_key.pem`` and
``asymmetric/DER_Serialization/rsa_public_key.der``- Contains an RSA 2048
bit public generated using OpenSSL from ``rsa_private_key.pem``.
+* ``asymmetric/PEM_Serialization/dsa_4096.pem`` - Contains a 4096-bit DSA
+ private key generated using OpenSSL.
* ``asymmetric/PEM_Serialization/dsaparam.pem`` - Contains 2048-bit DSA
parameters generated using OpenSSL; contains no keys.
* ``asymmetric/PEM_Serialization/dsa_private_key.pem`` - Contains a DSA 2048
@@ -86,6 +88,11 @@
* ``asymmetric/PEM_Serialization/dsa_public_key.pem`` and
``asymmetric/DER_Serialization/dsa_public_key.der`` - Contains a DSA 2048 bit
key generated using OpenSSL from ``dsa_private_key.pem``.
+* ``asymmetric/DER_Serialization/dsa_public_key_no_params.der`` - Contains a
+ DSA public key with the optional parameters removed.
+* ``asymmetric/DER_Serialization/dsa_public_key_invalid_bit_string.der`` -
+ Contains a DSA public key with the bit string padding value set to 2 rather
+ than the required 0.
* ``asymmetric/PKCS8/unenc-dsa-pkcs8.pem`` and
``asymmetric/DER_Serialization/unenc-dsa-pkcs8.der`` - Contains a DSA 1024
bit key generated using OpenSSL.
@@ -102,6 +109,8 @@
* ``x509/custom/ca/ca_key.pem`` - An unencrypted PCKS8 ``secp256r1`` key. It is
the private key for the certificate ``x509/custom/ca/ca.pem``. This key is
encoded in several of the PKCS12 custom vectors.
+* ``x509/custom/ca/rsa_key.pem`` - An unencrypted PCKS8 4096 bit RSA key. It is
+ the private key for the certificate ``x509/custom/ca/rsa_ca.pem``.
* ``asymmetric/EC/compressed_points.txt`` - Contains compressed public points
generated using OpenSSL.
* ``asymmetric/X448/x448-pkcs8-enc.pem`` and
@@ -111,6 +120,13 @@
contain an unencrypted X448 key.
* ``asymmetric/X448/x448-pub.pem`` and ``asymmetric/X448/x448-pub.der`` contain
an X448 public key.
+* ``asymmetric/Ed25519/ed25519-pkcs8-enc.pem`` and
+ ``asymmetric/Ed25519/ed25519-pkcs8-enc.der`` contain an Ed25519 key encrypted
+ with AES 256 CBC with the password ``password``.
+* ``asymmetric/Ed25519/ed25519-pkcs8.pem`` and
+ ``asymmetric/Ed25519/ed25519-pkcs8.der`` contain an unencrypted Ed25519 key.
+* ``asymmetric/Ed25519/ed25519-pub.pem`` and
+ ``asymmetric/Ed25519/ed25519-pub.der`` contain an Ed25519 public key.
* ``asymmetric/X25519/x25519-pkcs8-enc.pem`` and
``asymmetric/X25519/x25519-pkcs8-enc.der`` contain an X25519 key encrypted
with AES 256 CBC with the password ``password``.
@@ -118,6 +134,13 @@
``asymmetric/X25519/x25519-pkcs8.der`` contain an unencrypted X25519 key.
* ``asymmetric/X25519/x25519-pub.pem`` and ``asymmetric/X25519/x25519-pub.der``
contain an X25519 public key.
+* ``asymmetric/Ed448/ed448-pkcs8-enc.pem`` and
+ ``asymmetric/Ed448/ed448-pkcs8-enc.der`` contain an Ed448 key encrypted
+ with AES 256 CBC with the password ``password``.
+* ``asymmetric/Ed448/ed448-pkcs8.pem`` and
+ ``asymmetric/Ed448/ed448-pkcs8.der`` contain an unencrypted Ed448 key.
+* ``asymmetric/Ed448/ed448-pub.pem`` and ``asymmetric/Ed448/ed448-pub.der``
+ contain an Ed448 public key.
Key exchange
@@ -161,6 +184,8 @@
``vectors/cryptography_vectors/asymmetric/DH/dhkey_rfc5114_2.der`` and
``vectors/cryptography_vectors/asymmetric/DH/dhpub_rfc5114_2.der`` contains
are the above parameters and keys in DER format.
+* ``vectors/cryptography_vectors/asymmetric/DH/dh_key_256.pem`` contains
+ a PEM PKCS8 encoded DH key with a 256-bit key size.
* ``vectors/cryptoraphy_vectors/asymmetric/ECDH/brainpool.txt`` contains
Brainpool vectors from :rfc:`7027`.
@@ -217,6 +242,17 @@
UTCTime in its validity->not_after.
* ``letsencryptx3.pem`` - A subordinate certificate used by Let's Encrypt to
issue end entity certificates.
+* ``ed25519-rfc8410.pem`` - A certificate containing an X25519 public key with
+ an ``ed25519`` signature taken from :rfc:`8410`.
+* ``root-ed25519.pem`` - An ``ed25519`` root certificate (``ed25519`` signature
+ with ``ed25519`` public key) from the OpenSSL test suite.
+ (`root-ed25519.pem`_)
+* ``server-ed25519-cert.pem`` - An ``ed25519`` server certificate (RSA
+ signature with ``ed25519`` public key) from the OpenSSL test suite.
+ (`server-ed25519-cert.pem`_)
+* ``server-ed448-cert.pem`` - An ``ed448`` server certificate (RSA
+ signature with ``ed448`` public key) from the OpenSSL test suite.
+ (`server-ed448-cert.pem`_)
Custom X.509 Vectors
~~~~~~~~~~~~~~~~~~~~
@@ -371,9 +407,19 @@
a ``policyConstraints`` extension with a ``requireExplicitPolicy`` value.
* ``freshestcrl.pem`` - A self-signed certificate containing a ``freshestCRL``
extension.
+* ``sia.pem`` - An RSA 2048 bit self-signed certificate containing a subject
+ information access extension with both a CA repository entry and a custom
+ OID entry.
* ``ca/ca.pem`` - A self-signed certificate with ``basicConstraints`` set to
true. Its private key is ``ca/ca_key.pem``. This certificate is encoded in
several of the PKCS12 custom vectors.
+* ``negative_serial.pem`` - A certificate with a serial number that is a
+ negative number.
+* ``rsa_pss.pem`` - A certificate with an RSA PSS signature.
+* ``root-ed448.pem`` - An ``ed448`` self-signed CA certificate
+ using ``ed448-pkcs8.pem`` as key.
+* ``ca/rsa_ca.pem`` - A self-signed RSA certificate with ``basicConstraints``
+ set to true. Its private key is ``ca/rsa_key.pem``.
Custom X.509 Request Vectors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -406,6 +452,14 @@
critical.
* ``invalid_signature.pem`` - A certificate signing request for an RSA
1024 bit key containing an invalid signature with correct padding.
+* ``challenge.pem`` - A certificate signing request for an RSA 2048 bit key
+ containing a challenge password.
+* ``challenge-invalid.der`` - A certificate signing request for an RSA 2048 bit
+ key containing a challenge password attribute that has been encoded as an
+ ASN.1 integer rather than a string.
+* ``challenge-unstructured.pem`` - A certificate signing request for an RSA
+ 2048 bit key containing a challenge password attribute and an unstructured
+ name attribute.
Custom X.509 Certificate Revocation List Vectors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -480,6 +534,12 @@
contains a revoked certificate and no ``nextUpdate`` value.
* ``x509/ocsp/resp-invalid-signature-oid.der`` - An OCSP response that was
modified to contain an MD2 signature algorithm object identifier.
+* ``x509/ocsp/resp-single-extension-reason.der`` - An OCSP response that
+ contains a ``CRLReason`` single extension.
+* ``x509/ocsp/resp-sct-extension.der`` - An OCSP response containing a
+ ``CT Certificate SCTs`` single extension, from the SwissSign OCSP responder.
+* ``x509/ocsp/ocsp-army.deps.mil-resp.der`` - An OCSP response containing
+ multiple ``SINGLERESP`` values.
Custom X.509 OCSP Test Vectors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -515,6 +575,49 @@
(``x509/custom/ca/ca.pem``) encrypted via AES 256 CBC with the
password ``cryptography`` and no private key.
+Custom PKCS7 Test Vectors
+~~~~~~~~~~~~~~~~~~~~~~~~~
+* ``pkcs7/isrg.pem`` - A PEM encoded PKCS7 file containing the ISRG X1 root
+ CA.
+* ``pkcs7/amazon-roots.p7b`` - A DER encoded PCKS7 file containing Amazon Root
+ CA 2 and 3.
+* ``pkcs7/enveloped.pem`` - A PEM encoded PKCS7 file with enveloped data.
+
+Custom OpenSSH Test Vectors
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Generated by
+``asymmetric/OpenSSH/gen.sh``
+using command-line tools from OpenSSH_7.6p1 package.
+
+* ``dsa-nopsw.key``, ``dsa-nopsw.key.pub``, ``dsa-nopsw.key-cert.pub`` -
+ DSA-1024 private key; and corresponding public key in plain format
+ and with self-signed certificate.
+* ``dsa-psw.key``, ``dsa-psw.key.pub`` -
+ Password-protected DSA-1024 private key and corresponding public key.
+ Password is "password".
+* ``ecdsa-nopsw.key``, ``ecdsa-nopsw.key.pub``,
+ ``ecdsa-nopsw.key-cert.pub`` -
+ SECP256R1 private key; and corresponding public key in plain format
+ and with self-signed certificate.
+* ``ecdsa-psw.key``, ``ecdsa-psw.key.pub`` -
+ Password-protected SECP384R1 private key and corresponding public key.
+ Password is "password".
+* ``ed25519-nopsw.key``, ``ed25519-nopsw.key.pub``,
+ ``ed25519-nopsw.key-cert.pub`` -
+ Ed25519 private key; and corresponding public key in plain format
+ and with self-signed certificate.
+* ``ed25519-psw.key``, ``ed25519-psw.key.pub`` -
+ Password-protected Ed25519 private key and corresponding public key.
+ Password is "password".
+* ``rsa-nopsw.key``, ``rsa-nopsw.key.pub``,
+ ``rsa-nopsw.key-cert.pub`` -
+ RSA-2048 private key; and corresponding public key in plain format
+ and with self-signed certificate.
+* ``rsa-psw.key``, ``rsa-psw.key.pub`` -
+ Password-protected RSA-2048 private key and corresponding public key.
+ Password is "password".
+
Hashes
~~~~~~
@@ -593,6 +696,11 @@
* AES-128, AES-192, AES-256, 3DES from `NIST SP-800-38B`_
+Poly1305
+~~~~~~~~
+
+* Test vectors from :rfc:`7539`.
+
Creating test vectors
---------------------
@@ -629,7 +737,7 @@
.. _`IETF`: https://www.ietf.org/
.. _`Project Wycheproof`: https://github.com/google/wycheproof
.. _`NIST CAVP`: https://csrc.nist.gov/projects/cryptographic-algorithm-validation-program
-.. _`Bruce Schneier's vectors`: https://www.schneier.com/code/vectors.txt
+.. _`Bruce Schneier's vectors`: https://www.schneier.com/wp-content/uploads/2015/12/vectors-2.txt
.. _`Camellia page`: https://info.isl.ntt.co.jp/crypt/eng/camellia/
.. _`CRYPTREC`: https://www.cryptrec.go.jp
.. _`OpenSSL's test vectors`: https://github.com/openssl/openssl/blob/97cf1f6c2854a3a955fd7dd3a1f113deba00c9ef/crypto/evp/evptests.txt#L232
@@ -654,13 +762,16 @@
.. _`NIST SP-800-38B`: https://csrc.nist.gov/publications/detail/sp/800-38b/archive/2005-05-01
.. _`NIST PKI Testing`: https://csrc.nist.gov/Projects/PKI-Testing
.. _`testx509.pem`: https://github.com/openssl/openssl/blob/master/test/testx509.pem
-.. _`DigiCert Global Root G3`: https://cacerts.digicert.com/DigiCertGlobalRootG3.crt
+.. _`DigiCert Global Root G3`: http://cacerts.digicert.com/DigiCertGlobalRootG3.crt
.. _`root data`: https://hg.mozilla.org/projects/nss/file/25b2922cc564/security/nss/lib/ckfw/builtins/certdata.txt#l2053
.. _`asymmetric/public/PKCS1/dsa.pub.pem`: https://github.com/ruby/ruby/blob/4ccb387f3bc436a08fc6d72c4931994f5de95110/test/openssl/test_pkey_dsa.rb#L53
.. _`Mozilla bug`: https://bugzilla.mozilla.org/show_bug.cgi?id=233586
-.. _`Russian CA`: https://e-trust.gosuslugi.ru/MainCA
+.. _`Russian CA`: https://e-trust.gosuslugi.ru/
.. _`test/evptests.txt`: https://github.com/openssl/openssl/blob/2d0b44126763f989a4cbffbffe9d0c7518158bb7/test/evptests.txt
.. _`unknown signature OID`: https://bugzilla.mozilla.org/show_bug.cgi?id=405966
.. _`botan`: https://github.com/randombit/botan/blob/57789bdfc55061002b2727d0b32587612829a37c/src/tests/data/pubkey/dh.vec
.. _`DHKE`: https://sandilands.info/sgordon/diffie-hellman-secret-key-exchange-with-openssl
.. _`Botan's key wrap vectors`: https://github.com/randombit/botan/blob/737f33c09a18500e044dca3e2ae13bd2c08bafdd/src/tests/data/keywrap/nist_key_wrap.vec
+.. _`root-ed25519.pem`: https://github.com/openssl/openssl/blob/2a1e2fe145c6eb8e75aa2e1b3a8c3a49384b2852/test/certs/root-ed25519.pem
+.. _`server-ed25519-cert.pem`: https://github.com/openssl/openssl/blob/2a1e2fe145c6eb8e75aa2e1b3a8c3a49384b2852/test/certs/server-ed25519-cert.pem
+.. _`server-ed448-cert.pem`: https://github.com/openssl/openssl/blob/2a1e2fe145c6eb8e75aa2e1b3a8c3a49384b2852/test/certs/server-ed448-cert.pem
diff --git a/docs/doing-a-release.rst b/docs/doing-a-release.rst
index e7ee88f..043d52d 100644
--- a/docs/doing-a-release.rst
+++ b/docs/doing-a-release.rst
@@ -21,10 +21,10 @@
-------------------------
The release process creates wheels bundling OpenSSL for Windows, macOS, and
-Linux. Check that the Windows and macOS Jenkins builders have the latest
-version of OpenSSL installed and verify that the latest version is present in
-the ``pyca/cryptography-manylinux1`` docker containers. If anything is out
-of date follow the instructions for upgrading OpenSSL.
+Linux. Check that the Windows, macOS, and Linux builders (both
+``pyca/cryptography-manylinux1`` and ``pyca/cryptography-manylinux2010``) have
+the latest OpenSSL. If anything is out of date follow the instructions for
+upgrading OpenSSL.
Upgrading OpenSSL
-----------------
diff --git a/docs/faq.rst b/docs/faq.rst
index 6d87661..d6f4ad3 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -1,6 +1,33 @@
Frequently asked questions
==========================
+.. _faq-howto-handle-deprecation-warning:
+
+I cannot suppress the deprecation warning that ``cryptography`` emits on import
+-------------------------------------------------------------------------------
+
+.. hint::
+
+ The deprecation warning emitted on import does not inherit
+ :py:exc:`DeprecationWarning` but inherits :py:exc:`UserWarning`
+ instead.
+
+If your pytest setup follows the best practices of failing on
+emitted warnings (``filterwarnings = error``), you may ignore it
+by adding the following line at the end of the list::
+
+ ignore:Python 2 is no longer supported by the Python core team. Support for it is now deprecated in cryptography, and will be removed in a future release.:UserWarning
+
+**Note:** Using ``cryptography.utils.CryptographyDeprecationWarning``
+is not possible here because specifying it triggers
+``import cryptography`` internally that emits the warning before
+the ignore rule even kicks in.
+
+Ref: https://github.com/pytest-dev/pytest/issues/7524
+
+The same applies when you use :py:func:`~warnings.filterwarnings` in
+your code or invoke CPython with :std:option:`-W` command line option.
+
``cryptography`` failed to install!
-----------------------------------
@@ -43,18 +70,17 @@
:class:`AES-GCM <cryptography.hazmat.primitives.ciphers.modes.GCM>` and
:class:`~cryptography.hazmat.primitives.kdf.hkdf.HKDF`.
-Compiling ``cryptography`` on macOS produces a ``fatal error: 'openssl/aes.h' file not found`` error
-----------------------------------------------------------------------------------------------------
+Installing ``cryptography`` produces a ``fatal error: 'openssl/opensslv.h' file not found`` error
+-------------------------------------------------------------------------------------------------
-This happens because macOS 10.11 no longer includes a copy of OpenSSL.
-``cryptography`` now provides wheels which include a statically linked copy of
-OpenSSL. You're seeing this error because your copy of pip is too old to find
-our wheel files. Upgrade your copy of pip with ``pip install -U pip`` and then
-try install ``cryptography`` again.
+``cryptography`` provides wheels which include a statically linked copy of
+OpenSSL. If you see this error it is likely because your copy of ``pip`` is too
+old to find our wheel files. Upgrade your ``pip`` with ``pip install -U pip``
+and then try to install ``cryptography`` again.
-If you are using PyPy, we do not currently ship ``cryptography`` wheels for
-PyPy. You will need to install your own copy of OpenSSL -- we recommend using
-Homebrew.
+Users on PyPy, unusual CPU architectures, or distributions of Linux using
+``musl`` (like Alpine) will need to compile ``cryptography`` themselves. Please
+view our :doc:`/installation` documentation.
``cryptography`` raised an ``InternalError`` and I'm not sure what to do?
-------------------------------------------------------------------------
@@ -82,34 +108,22 @@
versions with ``pip install -U pip setuptools`` (or on Windows
``python -m pip install -U pip setuptools``).
-Installing cryptography with OpenSSL 0.9.8 or 1.0.0 fails
----------------------------------------------------------
+Installing cryptography with OpenSSL 0.9.8, 1.0.0, 1.0.1, 1.0.2 fails
+---------------------------------------------------------------------
-The OpenSSL project has dropped support for the 0.9.8 and 1.0.0 release series.
-Since they are no longer receiving security patches from upstream,
-``cryptography`` is also dropping support for them. To fix this issue you
-should upgrade to a newer version of OpenSSL (1.0.2 or later). This may require
-you to upgrade to a newer operating system.
+The OpenSSL project has dropped support for the 0.9.8, 1.0.0, 1.0.1, and 1.0.2
+release series. Since they are no longer receiving security patches from
+upstream, ``cryptography`` is also dropping support for them. To fix this issue
+you should upgrade to a newer version of OpenSSL (1.1.0 or later). This may
+require you to upgrade to a newer operating system.
-Why are there no wheels for Python 3.5+ on Linux or macOS?
-----------------------------------------------------------
+Why are there no wheels for my Python3.x version?
+-------------------------------------------------
-Our Python3 wheels, for macOS and Linux, are ``abi3`` wheels. This means they
-support multiple versions of Python. The Python 3.4 ``abi3`` wheel can be used
-with any version of Python greater than or equal to 3.4. Recent versions of
-``pip`` will automatically install ``abi3`` wheels.
-
-``ImportError``: ``idna`` is not installed
-------------------------------------------
-
-``cryptography`` deprecated passing :term:`U-label` strings to various X.509
-constructors in version 2.1 and in version 2.5 moved the ``idna`` dependency
-to a ``setuptools`` extra. If you see this exception you should upgrade your
-software so that it no longer depends on this deprecated feature. If that is
-not yet possible you can also install ``cryptography`` with
-``pip install cryptography[idna]`` to automatically install the missing
-dependency. This workaround will be available until the feature is fully
-removed.
+Our Python3 wheels are ``abi3`` wheels. This means they support multiple
+versions of Python. The ``abi3`` wheel can be used with any version of Python
+greater than or equal to the version it specifies. Recent versions of ``pip``
+will automatically install ``abi3`` wheels.
Why can't I import my PEM file?
-------------------------------
diff --git a/docs/fernet.rst b/docs/fernet.rst
index 9b95621..5e2655d 100644
--- a/docs/fernet.rst
+++ b/docs/fernet.rst
@@ -23,9 +23,10 @@
>>> f.decrypt(token)
b'my deep dark secret'
- :param bytes key: A URL-safe base64-encoded 32-byte key. This **must** be
- kept secret. Anyone with this key is able to create and
- read messages.
+ :param key: A URL-safe base64-encoded 32-byte key. This **must** be
+ kept secret. Anyone with this key is able to create and
+ read messages.
+ :type key: bytes or str
.. classmethod:: generate_key()
@@ -53,6 +54,28 @@
generated in *plaintext*, the time a message was created will
therefore be visible to a possible attacker.
+ .. method:: encrypt_at_time(data, current_time)
+
+ .. versionadded:: 3.0
+
+ Encrypts data passed using explicitly passed current time. See
+ :meth:`encrypt` for the documentation of the ``data`` parameter, the
+ return type and the exceptions raised.
+
+ The motivation behind this method is for the client code to be able to
+ test token expiration. Since this method can be used in an insecure
+ manner one should make sure the correct time (``int(time.time())``)
+ is passed as ``current_time`` outside testing.
+
+ :param int current_time: The current time.
+
+ .. note::
+
+ Similarly to :meth:`encrypt` the encrypted message contains the
+ timestamp in *plaintext*, in this case the timestamp is the value
+ of the ``current_time`` parameter.
+
+
.. method:: decrypt(token, ttl=None)
Decrypts a Fernet token. If successfully decrypted you will receive the
@@ -80,6 +103,23 @@
:raises TypeError: This exception is raised if ``token`` is not
``bytes``.
+ .. method:: decrypt_at_time(token, ttl, current_time)
+
+ .. versionadded:: 3.0
+
+ Decrypts a token using explicitly passed current time. See
+ :meth:`decrypt` for the documentation of the ``token`` and ``ttl``
+ parameters (``ttl`` is required here), the return type and the exceptions
+ raised.
+
+ The motivation behind this method is for the client code to be able to
+ test token expiration. Since this method can be used in an insecure
+ manner one should make sure the correct time (``int(time.time())``)
+ is passed as ``current_time`` outside testing.
+
+ :param int current_time: The current time.
+
+
.. method:: extract_timestamp(token)
.. versionadded:: 2.3
@@ -189,7 +229,6 @@
>>> import base64
>>> import os
>>> from cryptography.fernet import Fernet
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives import hashes
>>> from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
>>> password = b"password"
@@ -199,7 +238,6 @@
... length=32,
... salt=salt,
... iterations=100000,
- ... backend=default_backend()
... )
>>> key = base64.urlsafe_b64encode(kdf.derive(password))
>>> f = Fernet(key)
@@ -236,8 +274,9 @@
-----------
Fernet is ideal for encrypting data that easily fits in memory. As a design
-feature it does not expose unauthenticated bytes. Unfortunately, this makes it
-generally unsuitable for very large files at this time.
+feature it does not expose unauthenticated bytes. This means that the complete
+message contents must be available in memory, making Fernet generally
+unsuitable for very large files at this time.
.. _`Fernet`: https://github.com/fernet/spec/
diff --git a/docs/hazmat/backends/index.rst b/docs/hazmat/backends/index.rst
index a8a1ff3..97dbc86 100644
--- a/docs/hazmat/backends/index.rst
+++ b/docs/hazmat/backends/index.rst
@@ -8,10 +8,13 @@
.. currentmodule:: cryptography.hazmat.backends
-``cryptography`` was originally designed to support multiple backends, but
-this design has been deprecated.
+``cryptography`` was designed to support multiple cryptographic backends, but
+consumers rarely need this flexibility. Starting with version 3.1 ``backend``
+arguments are optional and the default backend will automatically be selected
+if none is specified.
-You can get the default backend by calling :func:`~default_backend`.
+On older versions you can get the default backend by calling
+:func:`~default_backend`.
.. function:: default_backend()
diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst
index 2c2d70e..36dd3a7 100644
--- a/docs/hazmat/backends/interfaces.rst
+++ b/docs/hazmat/backends/interfaces.rst
@@ -159,14 +159,13 @@
.. method:: create_cmac_ctx(algorithm)
Create a
- :class:`~cryptography.hazmat.primitives.mac.MACContext` that
+ context that
uses the specified ``algorithm`` to calculate a message authentication code.
:param algorithm: An instance of
:class:`~cryptography.hazmat.primitives.ciphers.BlockCipherAlgorithm`.
- :returns:
- :class:`~cryptography.hazmat.primitives.mac.MACContext`
+ :returns: CMAC object.
.. class:: PBKDF2HMACBackend
diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst
index 07ae74a..dd85d86 100644
--- a/docs/hazmat/backends/openssl.rst
+++ b/docs/hazmat/backends/openssl.rst
@@ -3,7 +3,7 @@
OpenSSL backend
===============
-The `OpenSSL`_ C library. Cryptography supports OpenSSL version 1.0.1 and
+The `OpenSSL`_ C library. Cryptography supports OpenSSL version 1.1.0 and
greater.
.. data:: cryptography.hazmat.backends.openssl.backend
@@ -68,6 +68,12 @@
OS random engine
----------------
+.. note::
+
+ As of OpenSSL 1.1.1d its CSPRNG is fork-safe by default.
+ ``cryptography`` does not compile or load the custom engine on
+ these versions.
+
By default OpenSSL uses a user-space CSPRNG that is seeded from system random (
``/dev/urandom`` or ``CryptGenRandom``). This CSPRNG is not reseeded
automatically when a process calls ``fork()``. This can result in situations
@@ -106,7 +112,7 @@
+------------------------------------------+------------------------------+
| Windows | ``CryptGenRandom()`` |
+------------------------------------------+------------------------------+
-| Linux >= 3.17 with working | ``getrandom(GRND_NONBLOCK)`` |
+| Linux >= 3.17 with working | ``getrandom()`` |
| ``SYS_getrandom`` syscall | |
+------------------------------------------+------------------------------+
| OpenBSD >= 5.6 | ``getentropy()`` |
diff --git a/docs/hazmat/bindings/index.rst b/docs/hazmat/bindings/index.rst
deleted file mode 100644
index 655f462..0000000
--- a/docs/hazmat/bindings/index.rst
+++ /dev/null
@@ -1,22 +0,0 @@
-.. hazmat::
-
-Bindings
-========
-
-.. module:: cryptography.hazmat.bindings
-
-``cryptography`` aims to provide low-level CFFI based bindings to multiple
-native C libraries. These provide no automatic initialization of the library
-and may not provide complete wrappers for its API.
-
-Using these functions directly is likely to require you to be careful in
-managing memory allocation, locking and other resources.
-
-
-Individual bindings
--------------------
-
-.. toctree::
- :maxdepth: 1
-
- openssl
diff --git a/docs/hazmat/bindings/openssl.rst b/docs/hazmat/bindings/openssl.rst
deleted file mode 100644
index ac65aa9..0000000
--- a/docs/hazmat/bindings/openssl.rst
+++ /dev/null
@@ -1,48 +0,0 @@
-.. hazmat::
-
-OpenSSL binding
-===============
-
-.. currentmodule:: cryptography.hazmat.bindings.openssl.binding
-
-These are `CFFI`_ bindings to the `OpenSSL`_ C library. Cryptography supports
-OpenSSL version 1.0.1 and greater.
-
-.. class:: cryptography.hazmat.bindings.openssl.binding.Binding()
-
- This is the exposed API for the OpenSSL bindings. It has two public
- attributes:
-
- .. attribute:: ffi
-
- This is a ``cffi.FFI`` instance. It can be used to allocate and
- otherwise manipulate OpenSSL structures.
-
- .. attribute:: lib
-
- This is a ``cffi`` library. It can be used to call OpenSSL functions,
- and access constants.
-
- .. classmethod:: init_static_locks
-
- Enables the best available locking callback for OpenSSL.
- See :ref:`openssl-threading`.
-
-.. _openssl-threading:
-
-Threading
----------
-
-``cryptography`` enables OpenSSLs `thread safety facilities`_ in two different
-ways depending on the configuration of your system. Normally the locking
-callbacks provided by your Python implementation specifically for OpenSSL will
-be used. However, if you have linked ``cryptography`` to a different version of
-OpenSSL than that used by your Python implementation we enable an alternative
-locking callback. This version is implemented in Python and so may result in
-lower performance in some situations. In particular parallelism is reduced
-because it has to acquire the GIL whenever any lock operations occur within
-OpenSSL.
-
-.. _`CFFI`: https://cffi.readthedocs.io
-.. _`OpenSSL`: https://www.openssl.org/
-.. _`thread safety facilities`: https://www.openssl.org/docs/man1.0.2/crypto/threads.html
diff --git a/docs/hazmat/primitives/asymmetric/dh.rst b/docs/hazmat/primitives/asymmetric/dh.rst
index edfe614..6b47da0 100644
--- a/docs/hazmat/primitives/asymmetric/dh.rst
+++ b/docs/hazmat/primitives/asymmetric/dh.rst
@@ -31,13 +31,11 @@
.. code-block:: pycon
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives import hashes
>>> from cryptography.hazmat.primitives.asymmetric import dh
>>> from cryptography.hazmat.primitives.kdf.hkdf import HKDF
>>> # Generate some parameters. These can be reused.
- >>> parameters = dh.generate_parameters(generator=2, key_size=2048,
- ... backend=default_backend())
+ >>> parameters = dh.generate_parameters(generator=2, key_size=2048)
>>> # Generate a private key for use in the exchange.
>>> server_private_key = parameters.generate_private_key()
>>> # In a real handshake the peer is a remote client. For this
@@ -51,7 +49,6 @@
... length=32,
... salt=None,
... info=b'handshake data',
- ... backend=default_backend()
... ).derive(shared_key)
>>> # And now we can demonstrate that the handshake performed in the
>>> # opposite direction gives the same final value
@@ -63,7 +60,6 @@
... length=32,
... salt=None,
... info=b'handshake data',
- ... backend=default_backend()
... ).derive(same_shared_key)
>>> derived_key == same_derived_key
@@ -75,13 +71,11 @@
.. code-block:: pycon
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives import hashes
>>> from cryptography.hazmat.primitives.asymmetric import dh
>>> from cryptography.hazmat.primitives.kdf.hkdf import HKDF
>>> # Generate some parameters. These can be reused.
- >>> parameters = dh.generate_parameters(generator=2, key_size=2048,
- ... backend=default_backend())
+ >>> parameters = dh.generate_parameters(generator=2, key_size=2048)
>>> # Generate a private key for use in the exchange.
>>> private_key = parameters.generate_private_key()
>>> # In a real handshake the peer_public_key will be received from the
@@ -96,7 +90,6 @@
... length=32,
... salt=None,
... info=b'handshake data',
- ... backend=default_backend()
... ).derive(shared_key)
>>> # For the next handshake we MUST generate another private key, but
>>> # we can reuse the parameters.
@@ -108,7 +101,6 @@
... length=32,
... salt=None,
... info=b'handshake data',
- ... backend=default_backend()
... ).derive(shared_key_2)
To assemble a :class:`~DHParameters` and a :class:`~DHPublicKey` from
@@ -118,9 +110,9 @@
peer::
pn = dh.DHParameterNumbers(p, g)
- parameters = pn.parameters(default_backend())
+ parameters = pn.parameters()
peer_public_numbers = dh.DHPublicNumbers(y, pn)
- peer_public_key = peer_public_numbers.public_key(default_backend())
+ peer_public_key = peer_public_numbers.public_key()
See also the :class:`~cryptography.hazmat.backends.interfaces.DHBackend`
@@ -129,7 +121,7 @@
Group parameters
~~~~~~~~~~~~~~~~
-.. function:: generate_parameters(generator, key_size, backend)
+.. function:: generate_parameters(generator, key_size, backend=None)
.. versionadded:: 1.7
@@ -140,7 +132,7 @@
:param key_size: The bit length of the prime modulus to generate.
- :param backend: A
+ :param backend: An optional
:class:`~cryptography.hazmat.backends.interfaces.DHBackend`
instance.
@@ -349,11 +341,11 @@
p subgroup order value.
- .. method:: parameters(backend)
+ .. method:: parameters(backend=None)
.. versionadded:: 1.7
- :param backend: An instance of
+ :param backend: An optional instance of
:class:`~cryptography.hazmat.backends.interfaces.DHBackend`.
:returns: A new instance of :class:`DHParameters`.
@@ -377,11 +369,11 @@
The private value.
- .. method:: private_key(backend)
+ .. method:: private_key(backend=None)
.. versionadded:: 1.7
- :param backend: An instance of
+ :param backend: An optional instance of
:class:`~cryptography.hazmat.backends.interfaces.DHBackend`.
:returns: A new instance of :class:`DHPrivateKey`.
@@ -405,11 +397,11 @@
The public value.
- .. method:: public_key(backend)
+ .. method:: public_key(backend=None)
.. versionadded:: 1.7
- :param backend: An instance of
+ :param backend: An optional instance of
:class:`~cryptography.hazmat.backends.interfaces.DHBackend`.
:returns: A new instance of :class:`DHPublicKey`.
diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst
index 7b05986..788e427 100644
--- a/docs/hazmat/primitives/asymmetric/dsa.rst
+++ b/docs/hazmat/primitives/asymmetric/dsa.rst
@@ -5,26 +5,36 @@
.. module:: cryptography.hazmat.primitives.asymmetric.dsa
+.. note::
+
+ DSA is a **legacy algorithm** and should generally be avoided in favor of
+ choices like
+ :doc:`EdDSA using curve25519</hazmat/primitives/asymmetric/ed25519>` or
+ :doc:`ECDSA</hazmat/primitives/asymmetric/ec>`.
+
`DSA`_ is a `public-key`_ algorithm for signing messages.
Generation
~~~~~~~~~~
-.. function:: generate_private_key(key_size, backend)
+.. function:: generate_private_key(key_size, backend=None)
.. versionadded:: 0.5
+ .. versionchanged:: 3.0
+
+ Added support for 4096-bit keys for some legacy applications that
+ continue to use DSA despite the wider cryptographic community's
+ `ongoing protestations`_.
+
Generate a DSA private key from the given key size. This function will
generate a new set of parameters and key in one step.
:param int key_size: The length of the modulus in :term:`bits`. It should
- be either 1024, 2048 or 3072. For keys generated in 2015 this should
- be `at least 2048`_ (See page 41). Note that some applications
- (such as SSH) have not yet gained support for larger key sizes
- specified in FIPS 186-3 and are still restricted to only the
- 1024-bit keys specified in FIPS 186-2.
+ be either 1024, 2048, 3072, or 4096. For keys generated in 2015 this
+ should be `at least 2048`_ (See page 41).
- :param backend: An instance of
+ :param backend: An optional instance of
:class:`~cryptography.hazmat.backends.interfaces.DSABackend`.
:return: An instance of
@@ -34,20 +44,23 @@
the provided ``backend`` does not implement
:class:`~cryptography.hazmat.backends.interfaces.DSABackend`
-.. function:: generate_parameters(key_size, backend)
+.. function:: generate_parameters(key_size, backend=None)
.. versionadded:: 0.5
+ .. versionchanged:: 3.0
+
+ Added support for 4096-bit keys for some legacy applications that
+ continue to use DSA despite the wider cryptographic community's
+ `ongoing protestations`_.
+
Generate DSA parameters using the provided ``backend``.
:param int key_size: The length of :attr:`~DSAParameterNumbers.q`. It
- should be either 1024, 2048 or 3072. For keys generated in 2015 this
- should be `at least 2048`_ (See page 41). Note that some applications
- (such as SSH) have not yet gained support for larger key sizes
- specified in FIPS 186-3 and are still restricted to only the
- 1024-bit keys specified in FIPS 186-2.
+ should be either 1024, 2048, 3072, or 4096. For keys generated in 2015
+ this should be `at least 2048`_ (See page 41).
- :param backend: An instance of
+ :param backend: An optional instance of
:class:`~cryptography.hazmat.backends.interfaces.DSABackend`.
:return: An instance of
@@ -65,12 +78,10 @@
.. doctest::
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives import hashes
>>> from cryptography.hazmat.primitives.asymmetric import dsa
>>> private_key = dsa.generate_private_key(
... key_size=1024,
- ... backend=default_backend()
... )
>>> data = b"this is some data I'd like to sign"
>>> signature = private_key.sign(
@@ -90,7 +101,7 @@
>>> from cryptography.hazmat.primitives.asymmetric import utils
>>> chosen_hash = hashes.SHA256()
- >>> hasher = hashes.Hash(chosen_hash, default_backend())
+ >>> hasher = hashes.Hash(chosen_hash)
>>> hasher.update(b"data & ")
>>> hasher.update(b"more data")
>>> digest = hasher.finalize()
@@ -133,7 +144,7 @@
.. doctest::
>>> chosen_hash = hashes.SHA256()
- >>> hasher = hashes.Hash(chosen_hash, default_backend())
+ >>> hasher = hashes.Hash(chosen_hash)
>>> hasher.update(b"data & ")
>>> hasher.update(b"more data")
>>> digest = hasher.finalize()
@@ -170,9 +181,9 @@
The generator.
- .. method:: parameters(backend)
+ .. method:: parameters(backend=None)
- :param backend: An instance of
+ :param backend: An optional instance of
:class:`~cryptography.hazmat.backends.interfaces.DSABackend`.
:returns: A new instance of
@@ -197,9 +208,9 @@
The :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAParameterNumbers`
associated with the public key.
- .. method:: public_key(backend)
+ .. method:: public_key(backend=None)
- :param backend: An instance of
+ :param backend: An optional instance of
:class:`~cryptography.hazmat.backends.interfaces.DSABackend`.
:returns: A new instance of
@@ -229,9 +240,9 @@
The :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicNumbers`
associated with the private key.
- .. method:: private_key(backend)
+ .. method:: private_key(backend=None)
- :param backend: An instance of
+ :param backend: An optional instance of
:class:`~cryptography.hazmat.backends.interfaces.DSABackend`.
:returns: A new instance of
@@ -344,7 +355,8 @@
:attr:`~cryptography.hazmat.primitives.serialization.Encoding.PEM` or
:attr:`~cryptography.hazmat.primitives.serialization.Encoding.DER`),
format (
- :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.TraditionalOpenSSL`
+ :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.TraditionalOpenSSL`,
+ :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.OpenSSH`
or
:attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.PKCS8`)
and encryption algorithm (such as
@@ -445,3 +457,4 @@
.. _`public-key`: https://en.wikipedia.org/wiki/Public-key_cryptography
.. _`FIPS 186-4`: https://csrc.nist.gov/publications/detail/fips/186/4/final
.. _`at least 2048`: https://www.cosic.esat.kuleuven.be/ecrypt/ecrypt2/documents/D.SPA.20.pdf
+.. _`ongoing protestations`: https://buttondown.email/cryptography-dispatches/archive/cryptography-dispatches-dsa-is-past-its-prime/
diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst
index d89fde3..5691560 100644
--- a/docs/hazmat/primitives/asymmetric/ec.rst
+++ b/docs/hazmat/primitives/asymmetric/ec.rst
@@ -6,7 +6,7 @@
.. module:: cryptography.hazmat.primitives.asymmetric.ec
-.. function:: generate_private_key(curve, backend)
+.. function:: generate_private_key(curve, backend=None)
.. versionadded:: 0.5
@@ -14,13 +14,13 @@
:param curve: An instance of :class:`EllipticCurve`.
- :param backend: An instance of
+ :param backend: An optional instance of
:class:`~cryptography.hazmat.backends.interfaces.EllipticCurveBackend`.
:returns: A new instance of :class:`EllipticCurvePrivateKey`.
-.. function:: derive_private_key(private_value, curve, backend)
+.. function:: derive_private_key(private_value, curve, backend=None)
.. versionadded:: 1.6
@@ -31,7 +31,7 @@
:param curve: An instance of :class:`EllipticCurve`.
- :param backend: An instance of
+ :param backend: An optional instance of
:class:`~cryptography.hazmat.backends.interfaces.EllipticCurveBackend`.
:returns: A new instance of :class:`EllipticCurvePrivateKey`.
@@ -47,16 +47,19 @@
The ECDSA signature algorithm first standardized in NIST publication
`FIPS 186-3`_, and later in `FIPS 186-4`_.
+ Note that while elliptic curve keys can be used for both signing and key
+ exchange, this is `bad cryptographic practice`_. Instead, users should
+ generate separate signing and ECDH keys.
+
:param algorithm: An instance of
:class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`.
.. doctest::
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives import hashes
>>> from cryptography.hazmat.primitives.asymmetric import ec
>>> private_key = ec.generate_private_key(
- ... ec.SECP384R1(), default_backend()
+ ... ec.SECP384R1()
... )
>>> data = b"this is some data I'd like to sign"
>>> signature = private_key.sign(
@@ -64,7 +67,7 @@
... ec.ECDSA(hashes.SHA256())
... )
- The ``signature`` is a ``bytes`` object, whose contents is DER encoded as
+ The ``signature`` is a ``bytes`` object, whose contents are DER encoded as
described in :rfc:`3279`. This can be decoded using
:func:`~cryptography.hazmat.primitives.asymmetric.utils.decode_dss_signature`.
@@ -76,7 +79,7 @@
>>> from cryptography.hazmat.primitives.asymmetric import utils
>>> chosen_hash = hashes.SHA256()
- >>> hasher = hashes.Hash(chosen_hash, default_backend())
+ >>> hasher = hashes.Hash(chosen_hash)
>>> hasher.update(b"data & ")
>>> hasher.update(b"more data")
>>> digest = hasher.finalize()
@@ -86,13 +89,18 @@
... )
- Verification requires the public key, the signature itself, the signed
- data, and knowledge of the hashing algorithm that was used when producing
- the signature:
+ Verification requires the public key, the DER-encoded signature itself, the
+ signed data, and knowledge of the hashing algorithm that was used when
+ producing the signature:
>>> public_key = private_key.public_key()
>>> public_key.verify(signature, data, ec.ECDSA(hashes.SHA256()))
+ As above, the ``signature`` is a ``bytes`` object whose contents are DER
+ encoded as described in :rfc:`3279`. It can be created from a raw ``(r,s)``
+ pair by using
+ :func:`~cryptography.hazmat.primitives.asymmetric.utils.encode_dss_signature`.
+
If the signature is not valid, an
:class:`~cryptography.exceptions.InvalidSignature` exception will be raised.
@@ -103,7 +111,7 @@
.. doctest::
>>> chosen_hash = hashes.SHA256()
- >>> hasher = hashes.Hash(chosen_hash, default_backend())
+ >>> hasher = hashes.Hash(chosen_hash)
>>> hasher.update(b"data & ")
>>> hasher.update(b"more data")
>>> digest = hasher.finalize()
@@ -139,12 +147,12 @@
The private value.
- .. method:: private_key(backend)
+ .. method:: private_key(backend=None)
Convert a collection of numbers into a private key suitable for doing
actual cryptographic operations.
- :param backend: An instance of
+ :param backend: An optional instance of
:class:`~cryptography.hazmat.backends.interfaces.EllipticCurveBackend`.
:returns: A new instance of :class:`EllipticCurvePrivateKey`.
@@ -181,12 +189,12 @@
The affine y component of the public point used for verifying.
- .. method:: public_key(backend)
+ .. method:: public_key(backend=None)
Convert a collection of numbers into a public key suitable for doing
actual cryptographic operations.
- :param backend: An instance of
+ :param backend: An optional instance of
:class:`~cryptography.hazmat.backends.interfaces.EllipticCurveBackend`.
:raises ValueError: Raised if the point is invalid for the curve.
@@ -249,6 +257,10 @@
key, derivation of multiple keys, and destroys any structure that may be
present.
+ Note that while elliptic curve keys can be used for both signing and key
+ exchange, this is `bad cryptographic practice`_. Instead, users should
+ generate separate signing and ECDH keys.
+
.. warning::
This example does not give `forward secrecy`_ and is only provided as a
@@ -257,18 +269,17 @@
.. doctest::
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives import hashes
>>> from cryptography.hazmat.primitives.asymmetric import ec
>>> from cryptography.hazmat.primitives.kdf.hkdf import HKDF
>>> # Generate a private key for use in the exchange.
>>> server_private_key = ec.generate_private_key(
- ... ec.SECP384R1(), default_backend()
+ ... ec.SECP384R1()
... )
>>> # In a real handshake the peer is a remote client. For this
>>> # example we'll generate another local private key though.
>>> peer_private_key = ec.generate_private_key(
- ... ec.SECP384R1(), default_backend()
+ ... ec.SECP384R1()
... )
>>> shared_key = server_private_key.exchange(
... ec.ECDH(), peer_private_key.public_key())
@@ -278,7 +289,6 @@
... length=32,
... salt=None,
... info=b'handshake data',
- ... backend=default_backend()
... ).derive(shared_key)
>>> # And now we can demonstrate that the handshake performed in the
>>> # opposite direction gives the same final value
@@ -290,7 +300,6 @@
... length=32,
... salt=None,
... info=b'handshake data',
- ... backend=default_backend()
... ).derive(same_shared_key)
>>> derived_key == same_derived_key
True
@@ -303,19 +312,18 @@
.. doctest::
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives import hashes
>>> from cryptography.hazmat.primitives.asymmetric import ec
>>> from cryptography.hazmat.primitives.kdf.hkdf import HKDF
>>> # Generate a private key for use in the exchange.
>>> private_key = ec.generate_private_key(
- ... ec.SECP384R1(), default_backend()
+ ... ec.SECP384R1()
... )
>>> # In a real handshake the peer_public_key will be received from the
>>> # other party. For this example we'll generate another private key
>>> # and get a public key from that.
>>> peer_public_key = ec.generate_private_key(
- ... ec.SECP384R1(), default_backend()
+ ... ec.SECP384R1()
... ).public_key()
>>> shared_key = private_key.exchange(ec.ECDH(), peer_public_key)
>>> # Perform key derivation.
@@ -324,14 +332,13 @@
... length=32,
... salt=None,
... info=b'handshake data',
- ... backend=default_backend()
... ).derive(shared_key)
>>> # For the next handshake we MUST generate another private key.
>>> private_key_2 = ec.generate_private_key(
- ... ec.SECP384R1(), default_backend()
+ ... ec.SECP384R1()
... )
>>> peer_public_key_2 = ec.generate_private_key(
- ... ec.SECP384R1(), default_backend()
+ ... ec.SECP384R1()
... ).public_key()
>>> shared_key_2 = private_key_2.exchange(ec.ECDH(), peer_public_key_2)
>>> derived_key_2 = HKDF(
@@ -339,7 +346,6 @@
... length=32,
... salt=None,
... info=b'handshake data',
- ... backend=default_backend()
... ).derive(shared_key_2)
Elliptic Curves
@@ -601,7 +607,16 @@
:param signature_algorithm: An instance of
:class:`EllipticCurveSignatureAlgorithm`, such as :class:`ECDSA`.
- :return bytes: Signature.
+ :return bytes: The signature as a ``bytes`` object, whose contents are
+ DER encoded as described in :rfc:`3279`. This can be decoded using
+ :func:`~cryptography.hazmat.primitives.asymmetric.utils.decode_dss_signature`,
+ which returns the decoded tuple ``(r, s)``.
+
+ .. attribute:: curve
+
+ :type: :class:`EllipticCurve`
+
+ The EllipticCurve that this key is on.
.. attribute:: key_size
@@ -633,7 +648,8 @@
:attr:`~cryptography.hazmat.primitives.serialization.Encoding.PEM` or
:attr:`~cryptography.hazmat.primitives.serialization.Encoding.DER`),
format (
- :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.TraditionalOpenSSL`
+ :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.TraditionalOpenSSL`,
+ :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.OpenSSH`
or
:attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.PKCS8`)
and encryption algorithm (such as
@@ -704,7 +720,10 @@
Verify one block of data was signed by the private key associated
with this public key.
- :param bytes signature: The signature to verify.
+ :param bytes signature: The DER-encoded signature to verify.
+ A raw signature may be DER-encoded by splitting it into the ``r``
+ and ``s`` components and passing them into
+ :func:`~cryptography.hazmat.primitives.asymmetric.utils.encode_dss_signature`.
:param bytes data: The message string that was signed.
@@ -761,12 +780,10 @@
.. doctest::
- >>> from cryptography.hazmat.backends import default_backend
- >>> from cryptography.hazmat.primitives import hashes
- >>> from cryptography.hazmat.primitives.asymmetric import ec
>>> from cryptography.hazmat.primitives import serialization
+ >>> from cryptography.hazmat.primitives.asymmetric import ec
- >>> private_key = ec.generate_private_key(ec.SECP384R1(), default_backend())
+ >>> private_key = ec.generate_private_key(ec.SECP384R1())
>>> serialized_private = private_key.private_bytes(
... encoding=serialization.Encoding.PEM,
@@ -806,14 +823,12 @@
>>> loaded_public_key = serialization.load_pem_public_key(
... serialized_public,
- ... backend=default_backend()
... )
>>> loaded_private_key = serialization.load_pem_private_key(
... serialized_private,
... # or password=None, if in plain text
... password=b'testpassword',
- ... backend=default_backend()
... )
@@ -926,6 +941,21 @@
Corresponds to the dotted string ``"1.3.132.0.39"``.
+.. function:: get_curve_for_oid(oid)
+
+ .. versionadded:: 2.6
+
+ A function that takes an :class:`~cryptography.x509.ObjectIdentifier`
+ and returns the associated elliptic curve class.
+
+ :param oid: An instance of
+ :class:`~cryptography.x509.ObjectIdentifier`.
+
+ :returns: The matching elliptic curve class. The returned class conforms
+ to the :class:`EllipticCurve` interface.
+
+ :raises LookupError: Raised if no elliptic curve is found that matches
+ the provided object identifier.
.. _`FIPS 186-3`: https://csrc.nist.gov/csrc/media/publications/fips/186/3/archive/2009-06-25/documents/fips_186-3.pdf
.. _`FIPS 186-4`: https://csrc.nist.gov/publications/detail/fips/186/4/final
@@ -939,4 +969,5 @@
.. _`ECDSA`: https://en.wikipedia.org/wiki/ECDSA
.. _`EdDSA`: https://en.wikipedia.org/wiki/EdDSA
.. _`forward secrecy`: https://en.wikipedia.org/wiki/Forward_secrecy
-.. _`SEC 1 v2.0`: http://www.secg.org/sec1-v2.pdf
+.. _`SEC 1 v2.0`: https://www.secg.org/sec1-v2.pdf
+.. _`bad cryptographic practice`: https://crypto.stackexchange.com/a/3313
diff --git a/docs/hazmat/primitives/asymmetric/ed25519.rst b/docs/hazmat/primitives/asymmetric/ed25519.rst
new file mode 100644
index 0000000..47d95ec
--- /dev/null
+++ b/docs/hazmat/primitives/asymmetric/ed25519.rst
@@ -0,0 +1,168 @@
+.. hazmat::
+
+Ed25519 signing
+===============
+
+.. currentmodule:: cryptography.hazmat.primitives.asymmetric.ed25519
+
+
+Ed25519 is an elliptic curve signing algorithm using `EdDSA`_ and
+`Curve25519`_. If you do not have legacy interoperability concerns then you
+should strongly consider using this signature algorithm.
+
+
+Signing & Verification
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. doctest::
+
+ >>> from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+ >>> private_key = Ed25519PrivateKey.generate()
+ >>> signature = private_key.sign(b"my authenticated message")
+ >>> public_key = private_key.public_key()
+ >>> # Raises InvalidSignature if verification fails
+ >>> public_key.verify(signature, b"my authenticated message")
+
+Key interfaces
+~~~~~~~~~~~~~~
+
+.. class:: Ed25519PrivateKey
+
+ .. versionadded:: 2.6
+
+ .. classmethod:: generate()
+
+ Generate an Ed25519 private key.
+
+ :returns: :class:`Ed25519PrivateKey`
+
+ .. classmethod:: from_private_bytes(data)
+
+ :param data: 32 byte private key.
+ :type data: :term:`bytes-like`
+
+ :returns: :class:`Ed25519PrivateKey`
+
+ .. doctest::
+
+ >>> from cryptography.hazmat.primitives import serialization
+ >>> from cryptography.hazmat.primitives.asymmetric import ed25519
+ >>> private_key = ed25519.Ed25519PrivateKey.generate()
+ >>> private_bytes = private_key.private_bytes(
+ ... encoding=serialization.Encoding.Raw,
+ ... format=serialization.PrivateFormat.Raw,
+ ... encryption_algorithm=serialization.NoEncryption()
+ ... )
+ >>> loaded_private_key = ed25519.Ed25519PrivateKey.from_private_bytes(private_bytes)
+
+
+ .. method:: public_key()
+
+ :returns: :class:`Ed25519PublicKey`
+
+ .. method:: sign(data)
+
+ :param bytes data: The data to sign.
+
+ :returns bytes: The 64 byte signature.
+
+ .. method:: private_bytes(encoding, format, encryption_algorithm)
+
+ Allows serialization of the key to bytes. Encoding (
+ :attr:`~cryptography.hazmat.primitives.serialization.Encoding.PEM`,
+ :attr:`~cryptography.hazmat.primitives.serialization.Encoding.DER`, or
+ :attr:`~cryptography.hazmat.primitives.serialization.Encoding.Raw`) and
+ format (
+ :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.PKCS8`,
+ :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.OpenSSH`
+ or
+ :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.Raw`
+ ) are chosen to define the exact serialization.
+
+ :param encoding: A value from the
+ :class:`~cryptography.hazmat.primitives.serialization.Encoding` enum.
+
+ :param format: A value from the
+ :class:`~cryptography.hazmat.primitives.serialization.PrivateFormat`
+ enum. If the ``encoding`` is
+ :attr:`~cryptography.hazmat.primitives.serialization.Encoding.Raw`
+ then ``format`` must be
+ :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.Raw`
+ , otherwise it must be
+ :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.PKCS8` or
+ :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.OpenSSH`.
+
+ :param encryption_algorithm: An instance of an object conforming to the
+ :class:`~cryptography.hazmat.primitives.serialization.KeySerializationEncryption`
+ interface.
+
+ :return bytes: Serialized key.
+
+.. class:: Ed25519PublicKey
+
+ .. versionadded:: 2.6
+
+ .. classmethod:: from_public_bytes(data)
+
+ :param bytes data: 32 byte public key.
+
+ :returns: :class:`Ed25519PublicKey`
+
+ .. doctest::
+
+ >>> from cryptography.hazmat.primitives import serialization
+ >>> from cryptography.hazmat.primitives.asymmetric import ed25519
+ >>> private_key = ed25519.Ed25519PrivateKey.generate()
+ >>> public_key = private_key.public_key()
+ >>> public_bytes = public_key.public_bytes(
+ ... encoding=serialization.Encoding.Raw,
+ ... format=serialization.PublicFormat.Raw
+ ... )
+ >>> loaded_public_key = ed25519.Ed25519PublicKey.from_public_bytes(public_bytes)
+
+ .. method:: public_bytes(encoding, format)
+
+ Allows serialization of the key to bytes. Encoding (
+ :attr:`~cryptography.hazmat.primitives.serialization.Encoding.PEM`,
+ :attr:`~cryptography.hazmat.primitives.serialization.Encoding.DER`,
+ :attr:`~cryptography.hazmat.primitives.serialization.Encoding.OpenSSH`,
+ or
+ :attr:`~cryptography.hazmat.primitives.serialization.Encoding.Raw`) and
+ format (
+ :attr:`~cryptography.hazmat.primitives.serialization.PublicFormat.SubjectPublicKeyInfo`,
+ :attr:`~cryptography.hazmat.primitives.serialization.PublicFormat.OpenSSH`
+ , or
+ :attr:`~cryptography.hazmat.primitives.serialization.PublicFormat.Raw`
+ ) are chosen to define the exact serialization.
+
+ :param encoding: A value from the
+ :class:`~cryptography.hazmat.primitives.serialization.Encoding` enum.
+
+ :param format: A value from the
+ :class:`~cryptography.hazmat.primitives.serialization.PublicFormat`
+ enum. If the ``encoding`` is
+ :attr:`~cryptography.hazmat.primitives.serialization.Encoding.Raw`
+ then ``format`` must be
+ :attr:`~cryptography.hazmat.primitives.serialization.PublicFormat.Raw`.
+ If ``encoding`` is
+ :attr:`~cryptography.hazmat.primitives.serialization.Encoding.OpenSSH`
+ then ``format`` must be
+ :attr:`~cryptography.hazmat.primitives.serialization.PublicFormat.OpenSSH`.
+ In all other cases ``format`` must be
+ :attr:`~cryptography.hazmat.primitives.serialization.PublicFormat.SubjectPublicKeyInfo`.
+
+ :returns bytes: The public key bytes.
+
+ .. method:: verify(signature, data)
+
+ :param bytes signature: The signature to verify.
+
+ :param bytes data: The data to verify.
+
+ :raises cryptography.exceptions.InvalidSignature: Raised when the
+ signature cannot be verified.
+
+
+
+.. _`EdDSA`: https://en.wikipedia.org/wiki/EdDSA
+.. _`Curve25519`: https://en.wikipedia.org/wiki/Curve25519
diff --git a/docs/hazmat/primitives/asymmetric/ed448.rst b/docs/hazmat/primitives/asymmetric/ed448.rst
new file mode 100644
index 0000000..fb79dcb
--- /dev/null
+++ b/docs/hazmat/primitives/asymmetric/ed448.rst
@@ -0,0 +1,131 @@
+.. hazmat::
+
+Ed448 signing
+=============
+
+.. currentmodule:: cryptography.hazmat.primitives.asymmetric.ed448
+
+
+Ed448 is an elliptic curve signing algorithm using `EdDSA`_.
+
+
+Signing & Verification
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. doctest::
+
+ >>> from cryptography.hazmat.primitives.asymmetric.ed448 import Ed448PrivateKey
+ >>> private_key = Ed448PrivateKey.generate()
+ >>> signature = private_key.sign(b"my authenticated message")
+ >>> public_key = private_key.public_key()
+ >>> # Raises InvalidSignature if verification fails
+ >>> public_key.verify(signature, b"my authenticated message")
+
+Key interfaces
+~~~~~~~~~~~~~~
+
+.. class:: Ed448PrivateKey
+
+ .. versionadded:: 2.6
+
+ .. classmethod:: generate()
+
+ Generate an Ed448 private key.
+
+ :returns: :class:`Ed448PrivateKey`
+
+ .. classmethod:: from_private_bytes(data)
+
+ :param data: 57 byte private key.
+ :type data: :term:`bytes-like`
+
+ :returns: :class:`Ed448PrivateKey`
+
+ .. method:: public_key()
+
+ :returns: :class:`Ed448PublicKey`
+
+ .. method:: sign(data)
+
+ :param bytes data: The data to sign.
+
+ :returns bytes: The 114 byte signature.
+
+ .. method:: private_bytes(encoding, format, encryption_algorithm)
+
+ Allows serialization of the key to bytes. Encoding (
+ :attr:`~cryptography.hazmat.primitives.serialization.Encoding.PEM`,
+ :attr:`~cryptography.hazmat.primitives.serialization.Encoding.DER`, or
+ :attr:`~cryptography.hazmat.primitives.serialization.Encoding.Raw`) and
+ format (
+ :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.PKCS8`
+ or
+ :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.Raw`
+ ) are chosen to define the exact serialization.
+
+ :param encoding: A value from the
+ :class:`~cryptography.hazmat.primitives.serialization.Encoding` enum.
+
+ :param format: A value from the
+ :class:`~cryptography.hazmat.primitives.serialization.PrivateFormat`
+ enum. If the ``encoding`` is
+ :attr:`~cryptography.hazmat.primitives.serialization.Encoding.Raw`
+ then ``format`` must be
+ :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.Raw`
+ , otherwise it must be
+ :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.PKCS8`.
+
+ :param encryption_algorithm: An instance of an object conforming to the
+ :class:`~cryptography.hazmat.primitives.serialization.KeySerializationEncryption`
+ interface.
+
+ :return bytes: Serialized key.
+
+.. class:: Ed448PublicKey
+
+ .. versionadded:: 2.6
+
+ .. classmethod:: from_public_bytes(data)
+
+ :param bytes data: 57 byte public key.
+
+ :returns: :class:`Ed448PublicKey`
+
+ .. method:: public_bytes(encoding, format)
+
+ Allows serialization of the key to bytes. Encoding (
+ :attr:`~cryptography.hazmat.primitives.serialization.Encoding.PEM`,
+ :attr:`~cryptography.hazmat.primitives.serialization.Encoding.DER`, or
+ :attr:`~cryptography.hazmat.primitives.serialization.Encoding.Raw`) and
+ format (
+ :attr:`~cryptography.hazmat.primitives.serialization.PublicFormat.SubjectPublicKeyInfo`
+ or
+ :attr:`~cryptography.hazmat.primitives.serialization.PublicFormat.Raw`
+ ) are chosen to define the exact serialization.
+
+ :param encoding: A value from the
+ :class:`~cryptography.hazmat.primitives.serialization.Encoding` enum.
+
+ :param format: A value from the
+ :class:`~cryptography.hazmat.primitives.serialization.PublicFormat`
+ enum. If the ``encoding`` is
+ :attr:`~cryptography.hazmat.primitives.serialization.Encoding.Raw`
+ then ``format`` must be
+ :attr:`~cryptography.hazmat.primitives.serialization.PublicFormat.Raw`
+ , otherwise it must be
+ :attr:`~cryptography.hazmat.primitives.serialization.PublicFormat.SubjectPublicKeyInfo`.
+
+ :returns bytes: The public key bytes.
+
+ .. method:: verify(signature, data)
+
+ :param bytes signature: The signature to verify.
+
+ :param bytes data: The data to verify.
+
+ :raises cryptography.exceptions.InvalidSignature: Raised when the
+ signature cannot be verified.
+
+
+
+.. _`EdDSA`: https://en.wikipedia.org/wiki/EdDSA
diff --git a/docs/hazmat/primitives/asymmetric/index.rst b/docs/hazmat/primitives/asymmetric/index.rst
index 1561c59..c27e178 100644
--- a/docs/hazmat/primitives/asymmetric/index.rst
+++ b/docs/hazmat/primitives/asymmetric/index.rst
@@ -23,7 +23,9 @@
.. toctree::
:maxdepth: 1
+ ed25519
x25519
+ ed448
x448
ec
rsa
diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst
index dab9096..33f402b 100644
--- a/docs/hazmat/primitives/asymmetric/rsa.rst
+++ b/docs/hazmat/primitives/asymmetric/rsa.rst
@@ -14,10 +14,14 @@
of bytes, RSA keys have a complex internal structure with `specific
mathematical properties`_.
-.. function:: generate_private_key(public_exponent, key_size, backend)
+.. function:: generate_private_key(public_exponent, key_size, backend=None)
.. versionadded:: 0.5
+ .. versionchanged:: 3.0
+
+ Tightened restrictions on ``public_exponent``.
+
Generates a new RSA private key using the provided ``backend``.
``key_size`` describes how many :term:`bits` long the key should be. Larger
keys provide more security; currently ``1024`` and below are considered
@@ -28,24 +32,22 @@
.. doctest::
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives.asymmetric import rsa
>>> private_key = rsa.generate_private_key(
... public_exponent=65537,
... key_size=2048,
- ... backend=default_backend()
... )
:param int public_exponent: The public exponent of the new key.
- Usually one of the small Fermat primes 3, 5, 17, 257, 65537. If in
- doubt you should `use 65537`_.
+ Either 65537 or 3 (for legacy purposes). Almost everyone should
+ `use 65537`_.
:param int key_size: The length of the modulus in :term:`bits`. For keys
generated in 2015 it is strongly recommended to be
`at least 2048`_ (See page 41). It must not be less than 512.
Some backends may have additional limitations.
- :param backend: A backend which implements
+ :param backend: An optional backend which implements
:class:`~cryptography.hazmat.backends.interfaces.RSABackend`.
:return: An instance of
@@ -64,14 +66,12 @@
.. code-block:: pycon
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives import serialization
>>> with open("path/to/key.pem", "rb") as key_file:
... private_key = serialization.load_pem_private_key(
... key_file.read(),
... password=None,
- ... backend=default_backend()
... )
Serialized keys may optionally be encrypted on disk using a password. In this
@@ -167,7 +167,7 @@
>>> from cryptography.hazmat.primitives.asymmetric import utils
>>> chosen_hash = hashes.SHA256()
- >>> hasher = hashes.Hash(chosen_hash, default_backend())
+ >>> hasher = hashes.Hash(chosen_hash)
>>> hasher.update(b"data & ")
>>> hasher.update(b"more data")
>>> digest = hasher.finalize()
@@ -217,7 +217,7 @@
.. doctest::
>>> chosen_hash = hashes.SHA256()
- >>> hasher = hashes.Hash(chosen_hash, default_backend())
+ >>> hasher = hashes.Hash(chosen_hash)
>>> hasher.update(b"data & ")
>>> hasher.update(b"more data")
>>> digest = hasher.finalize()
@@ -342,6 +342,11 @@
:class:`OAEP` should be preferred for encryption and :class:`PSS` should be
preferred for signatures.
+ .. warning::
+
+ Our implementation of PKCS1 v1.5 decryption is not constant time. See
+ :doc:`/limitations` for details.
+
.. function:: calculate_max_pss_salt_length(key, hash_algorithm)
@@ -399,9 +404,9 @@
The public exponent.
- .. method:: public_key(backend)
+ .. method:: public_key(backend=None)
- :param backend: An instance of
+ :param backend: An optional instance of
:class:`~cryptography.hazmat.backends.interfaces.RSABackend`.
:returns: A new instance of
@@ -466,9 +471,9 @@
A `Chinese remainder theorem`_ coefficient used to speed up RSA
operations. Calculated as: q\ :sup:`-1` mod p
- .. method:: private_key(backend)
+ .. method:: private_key(backend=None)
- :param backend: A new instance of
+ :param backend: An optional instance of
:class:`~cryptography.hazmat.backends.interfaces.RSABackend`.
:returns: An instance of
@@ -607,7 +612,8 @@
:attr:`~cryptography.hazmat.primitives.serialization.Encoding.PEM` or
:attr:`~cryptography.hazmat.primitives.serialization.Encoding.DER`),
format (
- :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.TraditionalOpenSSL`
+ :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.TraditionalOpenSSL`,
+ :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.OpenSSH`
or
:attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.PKCS8`)
and encryption algorithm (such as
@@ -708,6 +714,55 @@
:raises cryptography.exceptions.InvalidSignature: If the signature does
not validate.
+ .. method:: recover_data_from_signature(signature, padding, algorithm)
+
+ .. versionadded:: 3.3
+
+ Recovers the signed data from the signature. The data contains the
+ digest of the original message string. The ``padding`` and
+ ``algorithm`` parameters must match the ones used when the signature
+ was created for the recovery to succeed.
+
+ The ``algorithm`` parameter can also be set to ``None`` to recover all
+ the data present in the signature, without regard to its format or the
+ hash algorithm used for its creation.
+
+ For
+ :class:`~cryptography.hazmat.primitives.asymmetric.padding.PKCS1v15`
+ padding, this returns the data after removing the padding layer. For
+ standard signatures the data contains the full ``DigestInfo`` structure.
+ For non-standard signatures, any data can be returned, including zero-
+ length data.
+
+ Normally you should use the
+ :meth:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey.verify`
+ function to validate the signature. But for some non-standard signature
+ formats you may need to explicitly recover and validate the signed
+ data. Following are some examples:
+
+ - Some old Thawte and Verisign timestamp certificates without ``DigestInfo``.
+ - Signed MD5/SHA1 hashes in TLS 1.1 or earlier (RFC 4346, section 4.7).
+ - IKE version 1 signatures without ``DigestInfo`` (RFC 2409, section 5.1).
+
+ :param bytes signature: The signature.
+
+ :param padding: An instance of
+ :class:`~cryptography.hazmat.primitives.asymmetric.padding.AsymmetricPadding`.
+ Recovery is only supported with some of the padding types. (Currently
+ only with
+ :class:`~cryptography.hazmat.primitives.asymmetric.padding.PKCS1v15`).
+
+ :param algorithm: An instance of
+ :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`.
+ Can be ``None`` to return the all the data present in the signature.
+
+ :return bytes: The signed data.
+
+ :raises cryptography.exceptions.InvalidSignature: If the signature is
+ invalid.
+
+ :raises cryptography.exceptions.UnsupportedAlgorithm: If signature
+ data recovery is not supported with the provided ``padding`` type.
.. class:: RSAPublicKeyWithSerialization
diff --git a/docs/hazmat/primitives/asymmetric/serialization.rst b/docs/hazmat/primitives/asymmetric/serialization.rst
index dbb2bb6..2324340 100644
--- a/docs/hazmat/primitives/asymmetric/serialization.rst
+++ b/docs/hazmat/primitives/asymmetric/serialization.rst
@@ -88,10 +88,9 @@
.. doctest::
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives.asymmetric import dsa, rsa
>>> from cryptography.hazmat.primitives.serialization import load_pem_private_key
- >>> key = load_pem_private_key(pem_data, password=None, backend=default_backend())
+ >>> key = load_pem_private_key(pem_data, password=None)
>>> if isinstance(key, rsa.RSAPrivateKey):
... signature = sign_with_rsa_key(key, message)
... elif isinstance(key, dsa.DSAPrivateKey):
@@ -126,7 +125,7 @@
extract the public key with
:meth:`Certificate.public_key <cryptography.x509.Certificate.public_key>`.
-.. function:: load_pem_private_key(data, password, backend)
+.. function:: load_pem_private_key(data, password, backend=None)
.. versionadded:: 0.6
@@ -140,7 +139,7 @@
be ``None`` if the private key is not encrypted.
:type data: :term:`bytes-like`
- :param backend: An instance of
+ :param backend: An optional instance of
:class:`~cryptography.hazmat.backends.interfaces.PEMSerializationBackend`.
:returns: One of
@@ -159,10 +158,9 @@
password was supplied.
:raises cryptography.exceptions.UnsupportedAlgorithm: If the serialized key
- is of a type that is not supported by the backend or if the key is
- encrypted with a symmetric cipher that is not supported by the backend.
+ is of a type that is not supported by the backend.
-.. function:: load_pem_public_key(data, backend)
+.. function:: load_pem_public_key(data, backend=None)
.. versionadded:: 0.6
@@ -173,13 +171,13 @@
.. doctest::
>>> from cryptography.hazmat.primitives.serialization import load_pem_public_key
- >>> key = load_pem_public_key(public_pem_data, backend=default_backend())
+ >>> key = load_pem_public_key(public_pem_data)
>>> isinstance(key, rsa.RSAPublicKey)
True
:param bytes data: The PEM encoded key data.
- :param backend: An instance of
+ :param backend: An optional instance of
:class:`~cryptography.hazmat.backends.interfaces.PEMSerializationBackend`.
@@ -197,7 +195,7 @@
:raises cryptography.exceptions.UnsupportedAlgorithm: If the serialized key
is of a type that is not supported by the backend.
-.. function:: load_pem_parameters(data, backend)
+.. function:: load_pem_parameters(data, backend=None)
.. versionadded:: 2.0
@@ -208,13 +206,13 @@
>>> from cryptography.hazmat.primitives.serialization import load_pem_parameters
>>> from cryptography.hazmat.primitives.asymmetric import dh
- >>> parameters = load_pem_parameters(parameters_pem_data, backend=default_backend())
+ >>> parameters = load_pem_parameters(parameters_pem_data)
>>> isinstance(parameters, dh.DHParameters)
True
:param bytes data: The PEM encoded parameters data.
- :param backend: An instance of
+ :param backend: An optional instance of
:class:`~cryptography.hazmat.backends.interfaces.PEMSerializationBackend`.
@@ -236,7 +234,7 @@
know whether it is a public or private key the loading functions will handle
the rest.
-.. function:: load_der_private_key(data, password, backend)
+.. function:: load_der_private_key(data, password, backend=None)
.. versionadded:: 0.8
@@ -250,7 +248,7 @@
be ``None`` if the private key is not encrypted.
:type password: :term:`bytes-like`
- :param backend: An instance of
+ :param backend: An optional instance of
:class:`~cryptography.hazmat.backends.interfaces.DERSerializationBackend`.
:returns: One of
@@ -268,20 +266,18 @@
not encrypted. Or if the key was encrypted but no
password was supplied.
- :raises cryptography.exceptions.UnsupportedAlgorithm: If the serialized key is of a type that
- is not supported by the backend or if the key is encrypted with a
- symmetric cipher that is not supported by the backend.
+ :raises cryptography.exceptions.UnsupportedAlgorithm: If the serialized key
+ is of a type that is not supported by the backend.
.. doctest::
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives.asymmetric import rsa
>>> from cryptography.hazmat.primitives.serialization import load_der_private_key
- >>> key = load_der_private_key(der_data, password=None, backend=default_backend())
+ >>> key = load_der_private_key(der_data, password=None)
>>> isinstance(key, rsa.RSAPrivateKey)
True
-.. function:: load_der_public_key(data, backend)
+.. function:: load_der_public_key(data, backend=None)
.. versionadded:: 0.8
@@ -291,7 +287,7 @@
:param bytes data: The DER encoded key data.
- :param backend: An instance of
+ :param backend: An optional instance of
:class:`~cryptography.hazmat.backends.interfaces.DERSerializationBackend`.
:returns: One of
@@ -310,14 +306,13 @@
.. doctest::
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives.asymmetric import rsa
>>> from cryptography.hazmat.primitives.serialization import load_der_public_key
- >>> key = load_der_public_key(public_der_data, backend=default_backend())
+ >>> key = load_der_public_key(public_der_data)
>>> isinstance(key, rsa.RSAPublicKey)
True
-.. function:: load_der_parameters(data, backend)
+.. function:: load_der_parameters(data, backend=None)
.. versionadded:: 2.0
@@ -326,7 +321,7 @@
:param bytes data: The DER encoded parameters data.
- :param backend: An instance of
+ :param backend: An optional instance of
:class:`~cryptography.hazmat.backends.interfaces.DERSerializationBackend`.
:returns: Currently only
@@ -341,10 +336,9 @@
.. doctest::
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives.asymmetric import dh
>>> from cryptography.hazmat.primitives.serialization import load_der_parameters
- >>> parameters = load_der_parameters(parameters_der_data, backend=default_backend())
+ >>> parameters = load_der_parameters(parameters_der_data)
>>> isinstance(parameters, dh.DHParameters)
True
@@ -369,20 +363,18 @@
``ssh-rsa``. ECDSA keys have a slightly different format, they begin with
``ecdsa-sha2-{curve}``.
-.. function:: load_ssh_public_key(data, backend)
+.. function:: load_ssh_public_key(data, backend=None)
.. versionadded:: 0.7
- Deserialize a public key from OpenSSH (:rfc:`4253`) encoded data to an
+ Deserialize a public key from OpenSSH (:rfc:`4253` and
+ `PROTOCOL.certkeys`_) encoded data to an
instance of the public key type for the specified backend.
- .. note::
+ :param data: The OpenSSH encoded key data.
+ :type data: :term:`bytes-like`
- Currently Ed25519 keys are not supported.
-
- :param bytes data: The OpenSSH encoded key data.
-
- :param backend: A backend which implements
+ :param backend: An optional backend which implements
:class:`~cryptography.hazmat.backends.interfaces.RSABackend`,
:class:`~cryptography.hazmat.backends.interfaces.DSABackend`, or
:class:`~cryptography.hazmat.backends.interfaces.EllipticCurveBackend`
@@ -391,8 +383,9 @@
:returns: One of
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`,
:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey`,
- or
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`
+ , or
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PublicKey`,
depending on the contents of ``data``.
:raises ValueError: If the OpenSSH data could not be properly decoded or
@@ -401,6 +394,58 @@
:raises cryptography.exceptions.UnsupportedAlgorithm: If the serialized
key is of a type that is not supported.
+OpenSSH Private Key
+~~~~~~~~~~~~~~~~~~~
+
+The format used by OpenSSH to store private keys, as approximately specified
+in `PROTOCOL.key`_.
+
+An example ECDSA key in OpenSSH format::
+
+ -----BEGIN OPENSSH PRIVATE KEY-----
+ b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAaAAAABNlY2RzYS
+ 1zaGEyLW5pc3RwMjU2AAAACG5pc3RwMjU2AAAAQQRI0fWnI1CxX7qYqp0ih6bxjhGmUrZK
+ /Axf8vhM8Db3oH7CFR+JdL715lUdu4XCWvQZKVf60/h3kBFhuxQC23XjAAAAqKPzVaOj81
+ WjAAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEjR9acjULFfupiq
+ nSKHpvGOEaZStkr8DF/y+EzwNvegfsIVH4l0vvXmVR27hcJa9BkpV/rT+HeQEWG7FALbde
+ MAAAAga/VGV2asRlL3kXXao0aochQ59nXHA2xEGeAoQd952r0AAAAJbWFya29AdmZmAQID
+ BAUGBw==
+ -----END OPENSSH PRIVATE KEY-----
+
+.. function:: load_ssh_private_key(data, password, backend=None)
+
+ .. versionadded:: 3.0
+
+ Deserialize a private key from OpenSSH encoded data to an
+ instance of the private key type for the specified backend.
+
+ :param data: The PEM encoded OpenSSH private key data.
+ :type data: :term:`bytes-like`
+
+ :param bytes password: Password bytes to use to decrypt
+ password-protected key. Or ``None`` if not needed.
+
+ :param backend: An optional backend which implements
+ :class:`~cryptography.hazmat.backends.interfaces.RSABackend`,
+ :class:`~cryptography.hazmat.backends.interfaces.DSABackend`, or
+ :class:`~cryptography.hazmat.backends.interfaces.EllipticCurveBackend`
+ depending on the key's type.
+
+ :returns: One of
+ :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`,
+ :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey`,
+ :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`
+ or
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PublicKey`,
+ depending on the contents of ``data``.
+
+ :raises ValueError: If the OpenSSH data could not be properly decoded,
+ if the key is not in the proper format or the incorrect password
+ was provided.
+
+ :raises cryptography.exceptions.UnsupportedAlgorithm: If the serialized
+ key is of a type that is not supported.
+
PKCS12
~~~~~~
@@ -415,7 +460,7 @@
``cryptography`` only supports a single private key and associated
certificates when parsing PKCS12 files at this time.
-.. function:: load_key_and_certificates(data, password, backend)
+.. function:: load_key_and_certificates(data, password, backend=None)
.. versionadded:: 2.5
@@ -428,7 +473,7 @@
if the PKCS12 is not encrypted.
:type password: :term:`bytes-like`
- :param backend: A backend instance.
+ :param backend: An optional backend instance.
:returns: A tuple of
``(private_key, certificate, additional_certificates)``.
@@ -438,6 +483,240 @@
``additional_certificates`` is a list of all other
:class:`~cryptography.x509.Certificate` instances in the PKCS12 object.
+.. function:: serialize_key_and_certificates(name, key, cert, cas, encryption_algorithm)
+
+ .. versionadded:: 3.0
+
+ .. warning::
+
+ PKCS12 encryption is not secure and should not be used as a security
+ mechanism. Wrap a PKCS12 blob in a more secure envelope if you need
+ to store or send it safely. Encryption is provided for compatibility
+ reasons only.
+
+ Serialize a PKCS12 blob.
+
+ .. note::
+
+ Due to `a bug in Firefox`_ it's not possible to load unencrypted PKCS12
+ blobs in Firefox.
+
+ :param name: The friendly name to use for the supplied certificate and key.
+ :type name: bytes
+
+ :param key: The private key to include in the structure.
+ :type key: An
+ :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKeyWithSerialization`
+ ,
+ :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKeyWithSerialization`
+ , or
+ :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKeyWithSerialization`
+ object.
+
+ :param cert: The certificate associated with the private key.
+ :type cert: :class:`~cryptography.x509.Certificate` or ``None``
+
+ :param cas: An optional set of certificates to also include in the structure.
+ :type cas: list of :class:`~cryptography.x509.Certificate` or ``None``
+
+ :param encryption_algorithm: The encryption algorithm that should be used
+ for the key and certificate. An instance of an object conforming to the
+ :class:`~cryptography.hazmat.primitives.serialization.KeySerializationEncryption`
+ interface. PKCS12 encryption is **very weak** and should not be used
+ as a security boundary.
+
+ :return bytes: Serialized PKCS12.
+
+PKCS7
+~~~~~
+
+.. currentmodule:: cryptography.hazmat.primitives.serialization.pkcs7
+
+PKCS7 is a format described in :rfc:`2315`, among other specifications. It can
+contain certificates, CRLs, and much more. PKCS7 files commonly have a ``p7b``,
+``p7m``, or ``p7s`` file suffix but other suffixes are also seen in the wild.
+
+.. note::
+
+ ``cryptography`` only supports parsing certificates from PKCS7 files at
+ this time.
+
+.. function:: load_pem_pkcs7_certificates(data)
+
+ .. versionadded:: 3.1
+
+ Deserialize a PEM encoded PKCS7 blob to a list of certificates. PKCS7 can
+ contain many other types of data, including CRLs, but this function will
+ ignore everything except certificates.
+
+ :param data: The data.
+ :type data: bytes
+
+ :returns: A list of :class:`~cryptography.x509.Certificate`.
+
+ :raises ValueError: If the PKCS7 data could not be loaded.
+
+ :raises cryptography.exceptions.UnsupportedAlgorithm: If the PKCS7 data
+ is of a type that is not supported.
+
+.. function:: load_der_pkcs7_certificates(data)
+
+ .. versionadded:: 3.1
+
+ Deserialize a DER encoded PKCS7 blob to a list of certificates. PKCS7 can
+ contain many other types of data, including CRLs, but this function will
+ ignore everything except certificates.
+
+ :param data: The data.
+ :type data: bytes
+
+ :returns: A list of :class:`~cryptography.x509.Certificate`.
+
+ :raises ValueError: If the PKCS7 data could not be loaded.
+
+ :raises cryptography.exceptions.UnsupportedAlgorithm: If the PKCS7 data
+ is of a type that is not supported.
+
+.. testsetup::
+
+ ca_key = b"""
+ -----BEGIN PRIVATE KEY-----
+ MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgA8Zqz5vLeR0ePZUe
+ jBfdyMmnnI4U5uAJApWTsMn/RuWhRANCAAQY/8+7+Tm49d3D7sBAiwZ1BqtPzdgs
+ UiROH+AQRme1XxW5Yr07zwxvvhr3tKEPtLnLboazUPlsUb/Bgte+xfkF
+ -----END PRIVATE KEY-----
+ """.strip()
+
+ ca_cert = b"""
+ -----BEGIN CERTIFICATE-----
+ MIIBUTCB96ADAgECAgIDCTAKBggqhkjOPQQDAjAnMQswCQYDVQQGEwJVUzEYMBYG
+ A1UEAwwPY3J5cHRvZ3JhcGh5IENBMB4XDTE3MDEwMTEyMDEwMFoXDTM4MTIzMTA4
+ MzAwMFowJzELMAkGA1UEBhMCVVMxGDAWBgNVBAMMD2NyeXB0b2dyYXBoeSBDQTBZ
+ MBMGByqGSM49AgEGCCqGSM49AwEHA0IABBj/z7v5Obj13cPuwECLBnUGq0/N2CxS
+ JE4f4BBGZ7VfFblivTvPDG++Gve0oQ+0uctuhrNQ+WxRv8GC177F+QWjEzARMA8G
+ A1UdEwEB/wQFMAMBAf8wCgYIKoZIzj0EAwIDSQAwRgIhANES742XWm64tkGnz8Dn
+ pG6u2lHkZFQr3oaVvPcemvlbAiEA0WGGzmYx5C9UvfXIK7NEziT4pQtyESE0uRVK
+ Xw4nMqk=
+ -----END CERTIFICATE-----
+ """.strip()
+
+
+.. class:: PKCS7SignatureBuilder
+
+ The PKCS7 signature builder can create both basic PKCS7 signed messages as
+ well as S/MIME messages, which are commonly used in email. S/MIME has
+ multiple versions, but this implements a subset of :rfc:`2632`, also known
+ as S/MIME Version 3.
+
+ .. versionadded:: 3.2
+
+ .. doctest::
+
+ >>> from cryptography import x509
+ >>> from cryptography.hazmat.primitives import hashes, serialization
+ >>> from cryptography.hazmat.primitives.serialization import pkcs7
+ >>> cert = x509.load_pem_x509_certificate(ca_cert)
+ >>> key = serialization.load_pem_private_key(ca_key, None)
+ >>> options = [pkcs7.PKCS7Options.DetachedSignature]
+ >>> pkcs7.PKCS7SignatureBuilder().set_data(
+ ... b"data to sign"
+ ... ).add_signer(
+ ... cert, key, hashes.SHA256()
+ ... ).sign(
+ ... serialization.Encoding.SMIME, options
+ ... )
+ b'...'
+
+ .. method:: set_data(data)
+
+ :param data: The data to be hashed and signed.
+ :type data: :term:`bytes-like`
+
+ .. method:: add_signer(certificate, private_key, hash_algorithm)
+
+ :param certificate: The :class:`~cryptography.x509.Certificate`.
+
+ :param private_key: The
+ :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey` or
+ :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey`
+ associated with the certificate provided.
+
+ :param hash_algorithm: The
+ :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` that
+ will be used to generate the signature. This must be an instance of
+ :class:`~cryptography.hazmat.primitives.hashes.SHA1`,
+ :class:`~cryptography.hazmat.primitives.hashes.SHA224`,
+ :class:`~cryptography.hazmat.primitives.hashes.SHA256`,
+ :class:`~cryptography.hazmat.primitives.hashes.SHA384`, or
+ :class:`~cryptography.hazmat.primitives.hashes.SHA512`.
+
+ .. method:: add_certificate(certificate)
+
+ Add an additional certificate (typically used to help build a
+ verification chain) to the PKCS7 structure. This method may
+ be called multiple times to add as many certificates as desired.
+
+ :param certificate: The :class:`~cryptography.x509.Certificate` to add.
+
+ .. method:: sign(encoding, options, backend=None)
+
+ :param encoding: :attr:`~cryptography.hazmat.primitives.serialization.Encoding.PEM`,
+ :attr:`~cryptography.hazmat.primitives.serialization.Encoding.DER`,
+ or :attr:`~cryptography.hazmat.primitives.serialization.Encoding.SMIME`.
+
+ :param options: A list of
+ :class:`~cryptography.hazmat.primitives.serialization.pkcs7.PKCS7Options`.
+
+ :return bytes: The signed PKCS7 message.
+
+ :param backend: An optional backend.
+
+
+.. class:: PKCS7Options
+
+ .. versionadded:: 3.2
+
+ An enumeration of options for PKCS7 signature creation.
+
+ .. attribute:: Text
+
+ The text option adds ``text/plain`` headers to an S/MIME message when
+ serializing to
+ :attr:`~cryptography.hazmat.primitives.serialization.Encoding.SMIME`.
+ This option is disallowed with ``DER`` serialization.
+
+ .. attribute:: Binary
+
+ Signing normally converts line endings (LF to CRLF). When
+ passing this option the data will not be converted.
+
+ .. attribute:: DetachedSignature
+
+ Don't embed the signed data within the ASN.1. When signing with
+ :attr:`~cryptography.hazmat.primitives.serialization.Encoding.SMIME`
+ this also results in the data being added as clear text before the
+ PEM encoded structure.
+
+ .. attribute:: NoCapabilities
+
+ PKCS7 structures contain a ``MIMECapabilities`` section inside the
+ ``authenticatedAttributes``. Passing this as an option removes
+ ``MIMECapabilities``.
+
+ .. attribute:: NoAttributes
+
+ PKCS7 structures contain an ``authenticatedAttributes`` section.
+ Passing this as an option removes that section. Note that if you
+ pass ``NoAttributes`` you can't pass ``NoCapabilities`` since
+ ``NoAttributes`` removes ``MIMECapabilities`` and more.
+
+ .. attribute:: NoCerts
+
+ Don't include the signer's certificate in the PKCS7 structure. This can
+ reduce the size of the signature but requires that the recipient can
+ obtain the signer's certificate by other means (for example from a
+ previously signed message).
+
Serialization Formats
~~~~~~~~~~~~~~~~~~~~~
@@ -486,6 +765,22 @@
A raw format used by :doc:`/hazmat/primitives/asymmetric/x448`. It is a
binary format and is invalid for other key types.
+ .. attribute:: OpenSSH
+
+ .. versionadded:: 3.0
+
+ Custom private key format for OpenSSH, internals are based on SSH protocol
+ and not ASN1. Requires
+ :attr:`~cryptography.hazmat.primitives.serialization.Encoding.PEM`
+ encoding.
+
+ A PEM encoded OpenSSH key will look like::
+
+ -----BEGIN OPENSSH PRIVATE KEY-----
+ ...
+ -----END OPENSSH PRIVATE KEY-----
+
+
.. class:: PublicFormat
.. versionadded:: 0.8
@@ -615,6 +910,12 @@
The format used by elliptic curve point encodings. This is a binary
format.
+ .. attribute:: SMIME
+
+ .. versionadded:: 3.2
+
+ An output format used for PKCS7. This is a text format.
+
Serialization Encryption Types
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -646,5 +947,8 @@
Do not encrypt.
+.. _`a bug in Firefox`: https://bugzilla.mozilla.org/show_bug.cgi?id=773111
.. _`PKCS3`: https://www.teletrust.de/fileadmin/files/oid/oid_pkcs-3v1-4.pdf
-.. _`SEC 1 v2.0`: http://www.secg.org/sec1-v2.pdf
+.. _`SEC 1 v2.0`: https://www.secg.org/sec1-v2.pdf
+.. _`PROTOCOL.key`: https://github.com/openssh/openssh-portable/blob/master/PROTOCOL.key
+.. _`PROTOCOL.certkeys`: https://github.com/openssh/openssh-portable/blob/master/PROTOCOL.certkeys
diff --git a/docs/hazmat/primitives/asymmetric/utils.rst b/docs/hazmat/primitives/asymmetric/utils.rst
index f46acb2..487926e 100644
--- a/docs/hazmat/primitives/asymmetric/utils.rst
+++ b/docs/hazmat/primitives/asymmetric/utils.rst
@@ -57,7 +57,6 @@
.. doctest::
>>> import hashlib
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives import hashes
>>> from cryptography.hazmat.primitives.asymmetric import (
... padding, rsa, utils
@@ -65,7 +64,6 @@
>>> private_key = rsa.generate_private_key(
... public_exponent=65537,
... key_size=2048,
- ... backend=default_backend()
... )
>>> prehashed_msg = hashlib.sha256(b"A message I want to sign").digest()
>>> signature = private_key.sign(
diff --git a/docs/hazmat/primitives/asymmetric/x25519.rst b/docs/hazmat/primitives/asymmetric/x25519.rst
index ea01fba..014f3d0 100644
--- a/docs/hazmat/primitives/asymmetric/x25519.rst
+++ b/docs/hazmat/primitives/asymmetric/x25519.rst
@@ -21,7 +21,6 @@
.. doctest::
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives import hashes
>>> from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey
>>> from cryptography.hazmat.primitives.kdf.hkdf import HKDF
@@ -39,7 +38,6 @@
... length=32,
... salt=None,
... info=b'handshake data',
- ... backend=default_backend()
... ).derive(shared_key)
>>> # For the next handshake we MUST generate another private key.
>>> private_key_2 = X25519PrivateKey.generate()
@@ -50,7 +48,6 @@
... length=32,
... salt=None,
... info=b'handshake data',
- ... backend=default_backend()
... ).derive(shared_key_2)
Key interfaces
diff --git a/docs/hazmat/primitives/asymmetric/x448.rst b/docs/hazmat/primitives/asymmetric/x448.rst
index 4e1f042..f166355 100644
--- a/docs/hazmat/primitives/asymmetric/x448.rst
+++ b/docs/hazmat/primitives/asymmetric/x448.rst
@@ -21,7 +21,6 @@
.. doctest::
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives import hashes
>>> from cryptography.hazmat.primitives.asymmetric.x448 import X448PrivateKey
>>> from cryptography.hazmat.primitives.kdf.hkdf import HKDF
@@ -39,7 +38,6 @@
... length=32,
... salt=None,
... info=b'handshake data',
- ... backend=default_backend()
... ).derive(shared_key)
>>> # For the next handshake we MUST generate another private key.
>>> private_key_2 = X448PrivateKey.generate()
@@ -50,7 +48,6 @@
... length=32,
... salt=None,
... info=b'handshake data',
- ... backend=default_backend()
... ).derive(shared_key_2)
Key interfaces
diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst
index 24cc70b..4cdc034 100644
--- a/docs/hazmat/primitives/cryptographic-hashes.rst
+++ b/docs/hazmat/primitives/cryptographic-hashes.rst
@@ -5,7 +5,7 @@
.. module:: cryptography.hazmat.primitives.hashes
-.. class:: Hash(algorithm, backend)
+.. class:: Hash(algorithm, backend=None)
A cryptographic hash function takes an arbitrary block of data and
calculates a fixed-size bit string (a digest), such that different data
@@ -20,9 +20,8 @@
.. doctest::
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives import hashes
- >>> digest = hashes.Hash(hashes.SHA256(), backend=default_backend())
+ >>> digest = hashes.Hash(hashes.SHA256())
>>> digest.update(b"abc")
>>> digest.update(b"123")
>>> digest.finalize()
@@ -42,7 +41,7 @@
:class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`
instance such as those described in
:ref:`below <cryptographic-hash-algorithms>`.
- :param backend: A
+ :param backend: An optional
:class:`~cryptography.hazmat.backends.interfaces.HashBackend`
instance.
diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst
index be03b19..62457b2 100644
--- a/docs/hazmat/primitives/key-derivation-functions.rst
+++ b/docs/hazmat/primitives/key-derivation-functions.rst
@@ -26,9 +26,17 @@
Ideal password storage KDFs will be demanding on both computational and
memory resources.
+
+Variable cost algorithms
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+PBKDF2
+------
+
.. currentmodule:: cryptography.hazmat.primitives.kdf.pbkdf2
-.. class:: PBKDF2HMAC(algorithm, length, salt, iterations, backend)
+.. class:: PBKDF2HMAC(algorithm, length, salt, iterations, backend=None)
.. versionadded:: 0.2
@@ -47,8 +55,6 @@
>>> import os
>>> from cryptography.hazmat.primitives import hashes
>>> from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
- >>> from cryptography.hazmat.backends import default_backend
- >>> backend = default_backend()
>>> # Salts should be randomly generated
>>> salt = os.urandom(16)
>>> # derive
@@ -57,7 +63,6 @@
... length=32,
... salt=salt,
... iterations=100000,
- ... backend=backend
... )
>>> key = kdf.derive(b"my great password")
>>> # verify
@@ -66,7 +71,6 @@
... length=32,
... salt=salt,
... iterations=100000,
- ... backend=backend
... )
>>> kdf.verify(b"my great password", key)
@@ -79,9 +83,9 @@
:param int iterations: The number of iterations to perform of the hash
function. This can be used to control the length of time the operation
takes. Higher numbers help mitigate brute force attacks against derived
- keys. See OWASP's `Password Storage Cheat Sheet`_ for more
- detailed recommendations if you intend to use this for password storage.
- :param backend: An instance of
+ keys. A `more detailed description`_ can be consulted for additional
+ information.
+ :param backend: An optional instance of
:class:`~cryptography.hazmat.backends.interfaces.PBKDF2HMACBackend`.
:raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the
@@ -130,620 +134,12 @@
key.
-.. currentmodule:: cryptography.hazmat.primitives.kdf.hkdf
-
-.. class:: HKDF(algorithm, length, salt, info, backend)
-
- .. versionadded:: 0.2
-
- `HKDF`_ (HMAC-based Extract-and-Expand Key Derivation Function) is suitable
- for deriving keys of a fixed size used for other cryptographic operations.
-
- .. warning::
-
- HKDF should not be used for password storage.
-
- .. doctest::
-
- >>> import os
- >>> from cryptography.hazmat.primitives import hashes
- >>> from cryptography.hazmat.primitives.kdf.hkdf import HKDF
- >>> from cryptography.hazmat.backends import default_backend
- >>> backend = default_backend()
- >>> salt = os.urandom(16)
- >>> info = b"hkdf-example"
- >>> hkdf = HKDF(
- ... algorithm=hashes.SHA256(),
- ... length=32,
- ... salt=salt,
- ... info=info,
- ... backend=backend
- ... )
- >>> key = hkdf.derive(b"input key")
- >>> hkdf = HKDF(
- ... algorithm=hashes.SHA256(),
- ... length=32,
- ... salt=salt,
- ... info=info,
- ... backend=backend
- ... )
- >>> hkdf.verify(b"input key", key)
-
- :param algorithm: An instance of
- :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`.
-
- :param int length: The desired length of the derived key in bytes. Maximum
- is ``255 * (algorithm.digest_size // 8)``.
-
- :param bytes salt: A salt. Randomizes the KDF's output. Optional, but
- highly recommended. Ideally as many bits of entropy as the security
- level of the hash: often that means cryptographically random and as
- long as the hash output. Worse (shorter, less entropy) salt values can
- still meaningfully contribute to security. May be reused. Does not have
- to be secret, but may cause stronger security guarantees if secret; see
- :rfc:`5869` and the `HKDF paper`_ for more details. If ``None`` is
- explicitly passed a default salt of ``algorithm.digest_size // 8`` null
- bytes will be used.
-
- :param bytes info: Application specific context information. If ``None``
- is explicitly passed an empty byte string will be used.
-
- :param backend: An instance of
- :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`.
-
- :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the
- provided ``backend`` does not implement
- :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
-
- :raises TypeError: This exception is raised if ``salt`` or ``info`` is not
- ``bytes``.
-
- .. method:: derive(key_material)
-
- :param key_material: The input key material.
- :type key_material: :term:`bytes-like`
- :return bytes: The derived key.
- :raises TypeError: This exception is raised if ``key_material`` is not
- ``bytes``.
-
- Derives a new key from the input key material by performing both the
- extract and expand operations.
-
- .. method:: verify(key_material, expected_key)
-
- :param bytes key_material: The input key material. This is the same as
- ``key_material`` in :meth:`derive`.
- :param bytes expected_key: The expected result of deriving a new key,
- this is the same as the return value of
- :meth:`derive`.
- :raises cryptography.exceptions.InvalidKey: This is raised when the
- derived key does not match
- the expected key.
- :raises cryptography.exceptions.AlreadyFinalized: This is raised when
- :meth:`derive` or
- :meth:`verify` is
- called more than
- once.
-
- This checks whether deriving a new key from the supplied
- ``key_material`` generates the same key as the ``expected_key``, and
- raises an exception if they do not match.
-
-
-.. class:: HKDFExpand(algorithm, length, info, backend)
-
- .. versionadded:: 0.5
-
- HKDF consists of two stages, extract and expand. This class exposes an
- expand only version of HKDF that is suitable when the key material is
- already cryptographically strong.
-
- .. warning::
-
- HKDFExpand should only be used if the key material is
- cryptographically strong. You should use
- :class:`~cryptography.hazmat.primitives.kdf.hkdf.HKDF` if
- you are unsure.
-
- .. doctest::
-
- >>> import os
- >>> from cryptography.hazmat.primitives import hashes
- >>> from cryptography.hazmat.primitives.kdf.hkdf import HKDFExpand
- >>> from cryptography.hazmat.backends import default_backend
- >>> backend = default_backend()
- >>> info = b"hkdf-example"
- >>> key_material = os.urandom(16)
- >>> hkdf = HKDFExpand(
- ... algorithm=hashes.SHA256(),
- ... length=32,
- ... info=info,
- ... backend=backend
- ... )
- >>> key = hkdf.derive(key_material)
- >>> hkdf = HKDFExpand(
- ... algorithm=hashes.SHA256(),
- ... length=32,
- ... info=info,
- ... backend=backend
- ... )
- >>> hkdf.verify(key_material, key)
-
- :param algorithm: An instance of
- :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`.
-
- :param int length: The desired length of the derived key in bytes. Maximum
- is ``255 * (algorithm.digest_size // 8)``.
-
- :param bytes info: Application specific context information. If ``None``
- is explicitly passed an empty byte string will be used.
-
- :param backend: An instance of
- :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`.
-
- :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the
- provided ``backend`` does not implement
- :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
- :raises TypeError: This exception is raised if ``info`` is not ``bytes``.
-
- .. method:: derive(key_material)
-
- :param bytes key_material: The input key material.
- :return bytes: The derived key.
-
- :raises TypeError: This exception is raised if ``key_material`` is not
- ``bytes``.
-
- Derives a new key from the input key material by performing both the
- extract and expand operations.
-
- .. method:: verify(key_material, expected_key)
-
- :param bytes key_material: The input key material. This is the same as
- ``key_material`` in :meth:`derive`.
- :param bytes expected_key: The expected result of deriving a new key,
- this is the same as the return value of
- :meth:`derive`.
- :raises cryptography.exceptions.InvalidKey: This is raised when the
- derived key does not match
- the expected key.
- :raises cryptography.exceptions.AlreadyFinalized: This is raised when
- :meth:`derive` or
- :meth:`verify` is
- called more than
- once.
- :raises TypeError: This is raised if the provided ``key_material`` is
- a ``unicode`` object
-
- This checks whether deriving a new key from the supplied
- ``key_material`` generates the same key as the ``expected_key``, and
- raises an exception if they do not match.
-
-.. currentmodule:: cryptography.hazmat.primitives.kdf.concatkdf
-
-.. class:: ConcatKDFHash(algorithm, length, otherinfo, backend)
-
- .. versionadded:: 1.0
-
- ConcatKDFHash (Concatenation Key Derivation Function) is defined by the
- NIST Special Publication `NIST SP 800-56Ar2`_ document, to be used to
- derive keys for use after a Key Exchange negotiation operation.
-
- .. warning::
-
- ConcatKDFHash should not be used for password storage.
-
- .. doctest::
-
- >>> import os
- >>> from cryptography.hazmat.primitives import hashes
- >>> from cryptography.hazmat.primitives.kdf.concatkdf import ConcatKDFHash
- >>> from cryptography.hazmat.backends import default_backend
- >>> backend = default_backend()
- >>> otherinfo = b"concatkdf-example"
- >>> ckdf = ConcatKDFHash(
- ... algorithm=hashes.SHA256(),
- ... length=32,
- ... otherinfo=otherinfo,
- ... backend=backend
- ... )
- >>> key = ckdf.derive(b"input key")
- >>> ckdf = ConcatKDFHash(
- ... algorithm=hashes.SHA256(),
- ... length=32,
- ... otherinfo=otherinfo,
- ... backend=backend
- ... )
- >>> ckdf.verify(b"input key", key)
-
- :param algorithm: An instance of
- :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`.
-
- :param int length: The desired length of the derived key in bytes.
- Maximum is ``hashlen * (2^32 -1)``.
-
- :param bytes otherinfo: Application specific context information.
- If ``None`` is explicitly passed an empty byte string will be used.
-
- :param backend: An instance of
- :class:`~cryptography.hazmat.backends.interfaces.HashBackend`.
-
- :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised
- if the provided ``backend`` does not implement
- :class:`~cryptography.hazmat.backends.interfaces.HashBackend`
-
- :raises TypeError: This exception is raised if ``otherinfo`` is not
- ``bytes``.
-
- .. method:: derive(key_material)
-
- :param key_material: The input key material.
- :type key_material: :term:`bytes-like`
- :return bytes: The derived key.
- :raises TypeError: This exception is raised if ``key_material`` is
- not ``bytes``.
-
- Derives a new key from the input key material.
-
- .. method:: verify(key_material, expected_key)
-
- :param bytes key_material: The input key material. This is the same as
- ``key_material`` in :meth:`derive`.
- :param bytes expected_key: The expected result of deriving a new key,
- this is the same as the return value of
- :meth:`derive`.
- :raises cryptography.exceptions.InvalidKey: This is raised when the
- derived key does not match
- the expected key.
- :raises cryptography.exceptions.AlreadyFinalized: This is raised when
- :meth:`derive` or
- :meth:`verify` is
- called more than
- once.
-
- This checks whether deriving a new key from the supplied
- ``key_material`` generates the same key as the ``expected_key``, and
- raises an exception if they do not match.
-
-
-.. class:: ConcatKDFHMAC(algorithm, length, salt, otherinfo, backend)
-
- .. versionadded:: 1.0
-
- Similar to ConcatKFDHash but uses an HMAC function instead.
-
- .. warning::
-
- ConcatKDFHMAC should not be used for password storage.
-
- .. doctest::
-
- >>> import os
- >>> from cryptography.hazmat.primitives import hashes
- >>> from cryptography.hazmat.primitives.kdf.concatkdf import ConcatKDFHMAC
- >>> from cryptography.hazmat.backends import default_backend
- >>> backend = default_backend()
- >>> salt = os.urandom(16)
- >>> otherinfo = b"concatkdf-example"
- >>> ckdf = ConcatKDFHMAC(
- ... algorithm=hashes.SHA256(),
- ... length=32,
- ... salt=salt,
- ... otherinfo=otherinfo,
- ... backend=backend
- ... )
- >>> key = ckdf.derive(b"input key")
- >>> ckdf = ConcatKDFHMAC(
- ... algorithm=hashes.SHA256(),
- ... length=32,
- ... salt=salt,
- ... otherinfo=otherinfo,
- ... backend=backend
- ... )
- >>> ckdf.verify(b"input key", key)
-
- :param algorithm: An instance of
- :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`.
-
- :param int length: The desired length of the derived key in bytes. Maximum
- is ``hashlen * (2^32 -1)``.
-
- :param bytes salt: A salt. Randomizes the KDF's output. Optional, but
- highly recommended. Ideally as many bits of entropy as the security
- level of the hash: often that means cryptographically random and as
- long as the hash output. Does not have to be secret, but may cause
- stronger security guarantees if secret; If ``None`` is explicitly
- passed a default salt of ``algorithm.block_size`` null bytes will be
- used.
-
- :param bytes otherinfo: Application specific context information.
- If ``None`` is explicitly passed an empty byte string will be used.
-
- :param backend: An instance of
- :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`.
-
- :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the
- provided ``backend`` does not implement
- :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
-
- :raises TypeError: This exception is raised if ``salt`` or ``otherinfo``
- is not ``bytes``.
-
- .. method:: derive(key_material)
-
- :param bytes key_material: The input key material.
- :return bytes: The derived key.
- :raises TypeError: This exception is raised if ``key_material`` is not
- ``bytes``.
-
- Derives a new key from the input key material.
-
- .. method:: verify(key_material, expected_key)
-
- :param bytes key_material: The input key material. This is the same as
- ``key_material`` in :meth:`derive`.
- :param bytes expected_key: The expected result of deriving a new key,
- this is the same as the return value of
- :meth:`derive`.
- :raises cryptography.exceptions.InvalidKey: This is raised when the
- derived key does not match
- the expected key.
- :raises cryptography.exceptions.AlreadyFinalized: This is raised when
- :meth:`derive` or
- :meth:`verify` is
- called more than
- once.
-
- This checks whether deriving a new key from the supplied
- ``key_material`` generates the same key as the ``expected_key``, and
- raises an exception if they do not match.
-
-.. currentmodule:: cryptography.hazmat.primitives.kdf.x963kdf
-
-.. class:: X963KDF(algorithm, length, otherinfo, backend)
-
- .. versionadded:: 1.1
-
- X963KDF (ANSI X9.63 Key Derivation Function) is defined by ANSI
- in the `ANSI X9.63:2001`_ document, to be used to derive keys for use
- after a Key Exchange negotiation operation.
-
- SECG in `SEC 1 v2.0`_ recommends that
- :class:`~cryptography.hazmat.primitives.kdf.concatkdf.ConcatKDFHash` be
- used for new projects. This KDF should only be used for backwards
- compatibility with pre-existing protocols.
-
-
- .. warning::
-
- X963KDF should not be used for password storage.
-
- .. doctest::
-
- >>> import os
- >>> from cryptography.hazmat.primitives import hashes
- >>> from cryptography.hazmat.primitives.kdf.x963kdf import X963KDF
- >>> from cryptography.hazmat.backends import default_backend
- >>> backend = default_backend()
- >>> sharedinfo = b"ANSI X9.63 Example"
- >>> xkdf = X963KDF(
- ... algorithm=hashes.SHA256(),
- ... length=32,
- ... sharedinfo=sharedinfo,
- ... backend=backend
- ... )
- >>> key = xkdf.derive(b"input key")
- >>> xkdf = X963KDF(
- ... algorithm=hashes.SHA256(),
- ... length=32,
- ... sharedinfo=sharedinfo,
- ... backend=backend
- ... )
- >>> xkdf.verify(b"input key", key)
-
- :param algorithm: An instance of
- :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`.
-
- :param int length: The desired length of the derived key in bytes.
- Maximum is ``hashlen * (2^32 -1)``.
-
- :param bytes sharedinfo: Application specific context information.
- If ``None`` is explicitly passed an empty byte string will be used.
-
- :param backend: A cryptography backend
- :class:`~cryptography.hazmat.backends.interfaces.HashBackend`
- instance.
-
- :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised
- if the provided ``backend`` does not implement
- :class:`~cryptography.hazmat.backends.interfaces.HashBackend`
-
- :raises TypeError: This exception is raised if ``sharedinfo`` is not
- ``bytes``.
-
- .. method:: derive(key_material)
-
- :param key_material: The input key material.
- :type key_material: :term:`bytes-like`
- :return bytes: The derived key.
- :raises TypeError: This exception is raised if ``key_material`` is
- not ``bytes``.
-
- Derives a new key from the input key material.
-
- .. method:: verify(key_material, expected_key)
-
- :param bytes key_material: The input key material. This is the same as
- ``key_material`` in :meth:`derive`.
- :param bytes expected_key: The expected result of deriving a new key,
- this is the same as the return value of
- :meth:`derive`.
- :raises cryptography.exceptions.InvalidKey: This is raised when the
- derived key does not match
- the expected key.
- :raises cryptography.exceptions.AlreadyFinalized: This is raised when
- :meth:`derive` or
- :meth:`verify` is
- called more than
- once.
-
- This checks whether deriving a new key from the supplied
- ``key_material`` generates the same key as the ``expected_key``, and
- raises an exception if they do not match.
-
-
-.. currentmodule:: cryptography.hazmat.primitives.kdf.kbkdf
-
-.. class:: KBKDFHMAC(algorithm, mode, length, rlen, llen, location,\
- label, context, fixed, backend)
-
- .. versionadded:: 1.4
-
- KBKDF (Key Based Key Derivation Function) is defined by the
- `NIST SP 800-108`_ document, to be used to derive additional
- keys from a key that has been established through an automated
- key-establishment scheme.
-
- .. warning::
-
- KBKDFHMAC should not be used for password storage.
-
- .. doctest::
-
- >>> import os
- >>> from cryptography.hazmat.primitives import hashes
- >>> from cryptography.hazmat.primitives.kdf.kbkdf import (
- ... CounterLocation, KBKDFHMAC, Mode
- ... )
- >>> from cryptography.hazmat.backends import default_backend
- >>> backend = default_backend()
- >>> label = b"KBKDF HMAC Label"
- >>> context = b"KBKDF HMAC Context"
- >>> kdf = KBKDFHMAC(
- ... algorithm=hashes.SHA256(),
- ... mode=Mode.CounterMode,
- ... length=32,
- ... rlen=4,
- ... llen=4,
- ... location=CounterLocation.BeforeFixed,
- ... label=label,
- ... context=context,
- ... fixed=None,
- ... backend=backend
- ... )
- >>> key = kdf.derive(b"input key")
- >>> kdf = KBKDFHMAC(
- ... algorithm=hashes.SHA256(),
- ... mode=Mode.CounterMode,
- ... length=32,
- ... rlen=4,
- ... llen=4,
- ... location=CounterLocation.BeforeFixed,
- ... label=label,
- ... context=context,
- ... fixed=None,
- ... backend=backend
- ... )
- >>> kdf.verify(b"input key", key)
-
- :param algorithm: An instance of
- :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`.
-
- :param mode: The desired mode of the PRF. A value from the
- :class:`~cryptography.hazmat.primitives.kdf.kbkdf.Mode` enum.
-
- :param int length: The desired length of the derived key in bytes.
-
- :param int rlen: An integer that indicates the length of the binary
- representation of the counter in bytes.
-
- :param int llen: An integer that indicates the binary
- representation of the ``length`` in bytes.
-
- :param location: The desired location of the counter. A value from the
- :class:`~cryptography.hazmat.primitives.kdf.kbkdf.CounterLocation` enum.
-
- :param bytes label: Application specific label information. If ``None``
- is explicitly passed an empty byte string will be used.
-
- :param bytes context: Application specific context information. If ``None``
- is explicitly passed an empty byte string will be used.
-
- :param bytes fixed: Instead of specifying ``label`` and ``context`` you
- may supply your own fixed data. If ``fixed`` is specified, ``label``
- and ``context`` is ignored.
-
- :param backend: A cryptography backend
- :class:`~cryptography.hazmat.backends.interfaces.HashBackend`
- instance.
-
- :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised
- if the provided ``backend`` does not implement
- :class:`~cryptography.hazmat.backends.interfaces.HashBackend`
-
- :raises TypeError: This exception is raised if ``label`` or ``context``
- is not ``bytes``. Also raised if ``rlen`` or ``llen`` is not ``int``.
-
- :raises ValueError: This exception is raised if ``rlen`` or ``llen``
- is greater than 4 or less than 1. This exception is also raised if
- you specify a ``label`` or ``context`` and ``fixed``.
-
- .. method:: derive(key_material)
-
- :param key_material: The input key material.
- :type key_material: :term:`bytes-like`
- :return bytes: The derived key.
- :raises TypeError: This exception is raised if ``key_material`` is
- not ``bytes``.
-
- Derives a new key from the input key material.
-
- .. method:: verify(key_material, expected_key)
-
- :param bytes key_material: The input key material. This is the same as
- ``key_material`` in :meth:`derive`.
- :param bytes expected_key: The expected result of deriving a new key,
- this is the same as the return value of
- :meth:`derive`.
- :raises cryptography.exceptions.InvalidKey: This is raised when the
- derived key does not match
- the expected key.
- :raises cryptography.exceptions.AlreadyFinalized: This is raised when
- :meth:`derive` or
- :meth:`verify` is
- called more than
- once.
-
- This checks whether deriving a new key from the supplied
- ``key_material`` generates the same key as the ``expected_key``, and
- raises an exception if they do not match.
-
-.. class:: Mode
-
- An enumeration for the key based key derivative modes.
-
- .. attribute:: CounterMode
-
- The output of the PRF is computed with a counter
- as the iteration variable.
-
-.. class:: CounterLocation
-
- An enumeration for the key based key derivative counter location.
-
- .. attribute:: BeforeFixed
-
- The counter iteration variable will be concatenated before
- the fixed input data.
-
- .. attribute:: AfterFixed
-
- The counter iteration variable will be concatenated after
- the fixed input data.
+Scrypt
+------
.. currentmodule:: cryptography.hazmat.primitives.kdf.scrypt
-.. class:: Scrypt(salt, length, n, r, p, backend)
+.. class:: Scrypt(salt, length, n, r, p, backend=None)
.. versionadded:: 1.6
@@ -759,8 +155,6 @@
>>> import os
>>> from cryptography.hazmat.primitives.kdf.scrypt import Scrypt
- >>> from cryptography.hazmat.backends import default_backend
- >>> backend = default_backend()
>>> salt = os.urandom(16)
>>> # derive
>>> kdf = Scrypt(
@@ -769,7 +163,6 @@
... n=2**14,
... r=8,
... p=1,
- ... backend=backend
... )
>>> key = kdf.derive(b"my great password")
>>> # verify
@@ -779,7 +172,6 @@
... n=2**14,
... r=8,
... p=1,
- ... backend=backend
... )
>>> kdf.verify(b"my great password", key)
@@ -789,6 +181,8 @@
power of 2.
:param int r: Block size parameter.
:param int p: Parallelization parameter.
+ :param backend: An optional instance of
+ :class:`~cryptography.hazmat.backends.interfaces.ScryptBackend`.
The computational and memory cost of Scrypt can be adjusted by manipulating
the 3 parameters: ``n``, ``r``, and ``p``. In general, the memory cost of
@@ -802,9 +196,6 @@
minimum value of ``n=2**14`` for interactive logins (t < 100ms), or
``n=2**20`` for more sensitive files (t < 5s).
- :param backend: An instance of
- :class:`~cryptography.hazmat.backends.interfaces.ScryptBackend`.
-
:raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the
provided ``backend`` does not implement
:class:`~cryptography.hazmat.backends.interfaces.ScryptBackend`
@@ -851,6 +242,640 @@
checking whether the password a user provides matches the stored derived
key.
+Fixed cost algorithms
+~~~~~~~~~~~~~~~~~~~~~
+
+
+ConcatKDF
+---------
+
+.. currentmodule:: cryptography.hazmat.primitives.kdf.concatkdf
+
+.. class:: ConcatKDFHash(algorithm, length, otherinfo, backend=None)
+
+ .. versionadded:: 1.0
+
+ ConcatKDFHash (Concatenation Key Derivation Function) is defined by the
+ NIST Special Publication `NIST SP 800-56Ar2`_ document, to be used to
+ derive keys for use after a Key Exchange negotiation operation.
+
+ .. warning::
+
+ ConcatKDFHash should not be used for password storage.
+
+ .. doctest::
+
+ >>> import os
+ >>> from cryptography.hazmat.primitives import hashes
+ >>> from cryptography.hazmat.primitives.kdf.concatkdf import ConcatKDFHash
+ >>> otherinfo = b"concatkdf-example"
+ >>> ckdf = ConcatKDFHash(
+ ... algorithm=hashes.SHA256(),
+ ... length=32,
+ ... otherinfo=otherinfo,
+ ... )
+ >>> key = ckdf.derive(b"input key")
+ >>> ckdf = ConcatKDFHash(
+ ... algorithm=hashes.SHA256(),
+ ... length=32,
+ ... otherinfo=otherinfo,
+ ... )
+ >>> ckdf.verify(b"input key", key)
+
+ :param algorithm: An instance of
+ :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`.
+
+ :param int length: The desired length of the derived key in bytes.
+ Maximum is ``hashlen * (2^32 -1)``.
+
+ :param bytes otherinfo: Application specific context information.
+ If ``None`` is explicitly passed an empty byte string will be used.
+
+ :param backend: An optional instance of
+ :class:`~cryptography.hazmat.backends.interfaces.HashBackend`.
+
+ :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised
+ if the provided ``backend`` does not implement
+ :class:`~cryptography.hazmat.backends.interfaces.HashBackend`
+
+ :raises TypeError: This exception is raised if ``otherinfo`` is not
+ ``bytes``.
+
+ .. method:: derive(key_material)
+
+ :param key_material: The input key material.
+ :type key_material: :term:`bytes-like`
+ :return bytes: The derived key.
+ :raises TypeError: This exception is raised if ``key_material`` is
+ not ``bytes``.
+ :raises cryptography.exceptions.AlreadyFinalized: This is raised when
+ :meth:`derive` or
+ :meth:`verify` is
+ called more than
+ once.
+
+ Derives a new key from the input key material.
+
+ .. method:: verify(key_material, expected_key)
+
+ :param bytes key_material: The input key material. This is the same as
+ ``key_material`` in :meth:`derive`.
+ :param bytes expected_key: The expected result of deriving a new key,
+ this is the same as the return value of
+ :meth:`derive`.
+ :raises cryptography.exceptions.InvalidKey: This is raised when the
+ derived key does not match
+ the expected key.
+ :raises cryptography.exceptions.AlreadyFinalized: This is raised when
+ :meth:`derive` or
+ :meth:`verify` is
+ called more than
+ once.
+
+ This checks whether deriving a new key from the supplied
+ ``key_material`` generates the same key as the ``expected_key``, and
+ raises an exception if they do not match.
+
+
+.. class:: ConcatKDFHMAC(algorithm, length, salt, otherinfo, backend=None)
+
+ .. versionadded:: 1.0
+
+ Similar to ConcatKFDHash but uses an HMAC function instead.
+
+ .. warning::
+
+ ConcatKDFHMAC should not be used for password storage.
+
+ .. doctest::
+
+ >>> import os
+ >>> from cryptography.hazmat.primitives import hashes
+ >>> from cryptography.hazmat.primitives.kdf.concatkdf import ConcatKDFHMAC
+ >>> salt = os.urandom(16)
+ >>> otherinfo = b"concatkdf-example"
+ >>> ckdf = ConcatKDFHMAC(
+ ... algorithm=hashes.SHA256(),
+ ... length=32,
+ ... salt=salt,
+ ... otherinfo=otherinfo,
+ ... )
+ >>> key = ckdf.derive(b"input key")
+ >>> ckdf = ConcatKDFHMAC(
+ ... algorithm=hashes.SHA256(),
+ ... length=32,
+ ... salt=salt,
+ ... otherinfo=otherinfo,
+ ... )
+ >>> ckdf.verify(b"input key", key)
+
+ :param algorithm: An instance of
+ :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`.
+
+ :param int length: The desired length of the derived key in bytes. Maximum
+ is ``hashlen * (2^32 -1)``.
+
+ :param bytes salt: A salt. Randomizes the KDF's output. Optional, but
+ highly recommended. Ideally as many bits of entropy as the security
+ level of the hash: often that means cryptographically random and as
+ long as the hash output. Does not have to be secret, but may cause
+ stronger security guarantees if secret; If ``None`` is explicitly
+ passed a default salt of ``algorithm.block_size`` null bytes will be
+ used.
+
+ :param bytes otherinfo: Application specific context information.
+ If ``None`` is explicitly passed an empty byte string will be used.
+
+ :param backend: An optional instance of
+ :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`.
+
+ :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the
+ provided ``backend`` does not implement
+ :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
+
+ :raises TypeError: This exception is raised if ``salt`` or ``otherinfo``
+ is not ``bytes``.
+
+ .. method:: derive(key_material)
+
+ :param bytes key_material: The input key material.
+ :return bytes: The derived key.
+ :raises TypeError: This exception is raised if ``key_material`` is not
+ ``bytes``.
+ :raises cryptography.exceptions.AlreadyFinalized: This is raised when
+ :meth:`derive` or
+ :meth:`verify` is
+ called more than
+ once.
+
+ Derives a new key from the input key material.
+
+ .. method:: verify(key_material, expected_key)
+
+ :param bytes key_material: The input key material. This is the same as
+ ``key_material`` in :meth:`derive`.
+ :param bytes expected_key: The expected result of deriving a new key,
+ this is the same as the return value of
+ :meth:`derive`.
+ :raises cryptography.exceptions.InvalidKey: This is raised when the
+ derived key does not match
+ the expected key.
+ :raises cryptography.exceptions.AlreadyFinalized: This is raised when
+ :meth:`derive` or
+ :meth:`verify` is
+ called more than
+ once.
+
+ This checks whether deriving a new key from the supplied
+ ``key_material`` generates the same key as the ``expected_key``, and
+ raises an exception if they do not match.
+
+
+HKDF
+----
+
+.. currentmodule:: cryptography.hazmat.primitives.kdf.hkdf
+
+.. class:: HKDF(algorithm, length, salt, info, backend=None)
+
+ .. versionadded:: 0.2
+
+ `HKDF`_ (HMAC-based Extract-and-Expand Key Derivation Function) is suitable
+ for deriving keys of a fixed size used for other cryptographic operations.
+
+ .. warning::
+
+ HKDF should not be used for password storage.
+
+ .. doctest::
+
+ >>> import os
+ >>> from cryptography.hazmat.primitives import hashes
+ >>> from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+ >>> salt = os.urandom(16)
+ >>> info = b"hkdf-example"
+ >>> hkdf = HKDF(
+ ... algorithm=hashes.SHA256(),
+ ... length=32,
+ ... salt=salt,
+ ... info=info,
+ ... )
+ >>> key = hkdf.derive(b"input key")
+ >>> hkdf = HKDF(
+ ... algorithm=hashes.SHA256(),
+ ... length=32,
+ ... salt=salt,
+ ... info=info,
+ ... )
+ >>> hkdf.verify(b"input key", key)
+
+ :param algorithm: An instance of
+ :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`.
+
+ :param int length: The desired length of the derived key in bytes. Maximum
+ is ``255 * (algorithm.digest_size // 8)``.
+
+ :param bytes salt: A salt. Randomizes the KDF's output. Optional, but
+ highly recommended. Ideally as many bits of entropy as the security
+ level of the hash: often that means cryptographically random and as
+ long as the hash output. Worse (shorter, less entropy) salt values can
+ still meaningfully contribute to security. May be reused. Does not have
+ to be secret, but may cause stronger security guarantees if secret; see
+ :rfc:`5869` and the `HKDF paper`_ for more details. If ``None`` is
+ explicitly passed a default salt of ``algorithm.digest_size // 8`` null
+ bytes will be used.
+
+ :param bytes info: Application specific context information. If ``None``
+ is explicitly passed an empty byte string will be used.
+
+ :param backend: An optional instance of
+ :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`.
+
+ :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the
+ provided ``backend`` does not implement
+ :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
+
+ :raises TypeError: This exception is raised if ``salt`` or ``info`` is not
+ ``bytes``.
+
+ .. method:: derive(key_material)
+
+ :param key_material: The input key material.
+ :type key_material: :term:`bytes-like`
+ :return bytes: The derived key.
+ :raises TypeError: This exception is raised if ``key_material`` is not
+ ``bytes``.
+ :raises cryptography.exceptions.AlreadyFinalized: This is raised when
+ :meth:`derive` or
+ :meth:`verify` is
+ called more than
+ once.
+
+ Derives a new key from the input key material by performing both the
+ extract and expand operations.
+
+ .. method:: verify(key_material, expected_key)
+
+ :param bytes key_material: The input key material. This is the same as
+ ``key_material`` in :meth:`derive`.
+ :param bytes expected_key: The expected result of deriving a new key,
+ this is the same as the return value of
+ :meth:`derive`.
+ :raises cryptography.exceptions.InvalidKey: This is raised when the
+ derived key does not match
+ the expected key.
+ :raises cryptography.exceptions.AlreadyFinalized: This is raised when
+ :meth:`derive` or
+ :meth:`verify` is
+ called more than
+ once.
+
+ This checks whether deriving a new key from the supplied
+ ``key_material`` generates the same key as the ``expected_key``, and
+ raises an exception if they do not match.
+
+
+.. class:: HKDFExpand(algorithm, length, info, backend=None)
+
+ .. versionadded:: 0.5
+
+ HKDF consists of two stages, extract and expand. This class exposes an
+ expand only version of HKDF that is suitable when the key material is
+ already cryptographically strong.
+
+ .. warning::
+
+ HKDFExpand should only be used if the key material is
+ cryptographically strong. You should use
+ :class:`~cryptography.hazmat.primitives.kdf.hkdf.HKDF` if
+ you are unsure.
+
+ .. doctest::
+
+ >>> import os
+ >>> from cryptography.hazmat.primitives import hashes
+ >>> from cryptography.hazmat.primitives.kdf.hkdf import HKDFExpand
+ >>> info = b"hkdf-example"
+ >>> key_material = os.urandom(16)
+ >>> hkdf = HKDFExpand(
+ ... algorithm=hashes.SHA256(),
+ ... length=32,
+ ... info=info,
+ ... )
+ >>> key = hkdf.derive(key_material)
+ >>> hkdf = HKDFExpand(
+ ... algorithm=hashes.SHA256(),
+ ... length=32,
+ ... info=info,
+ ... )
+ >>> hkdf.verify(key_material, key)
+
+ :param algorithm: An instance of
+ :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`.
+
+ :param int length: The desired length of the derived key in bytes. Maximum
+ is ``255 * (algorithm.digest_size // 8)``.
+
+ :param bytes info: Application specific context information. If ``None``
+ is explicitly passed an empty byte string will be used.
+
+ :param backend: An optional instance of
+ :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`.
+
+ :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the
+ provided ``backend`` does not implement
+ :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
+ :raises TypeError: This exception is raised if ``info`` is not ``bytes``.
+
+ .. method:: derive(key_material)
+
+ :param bytes key_material: The input key material.
+ :return bytes: The derived key.
+
+ :raises TypeError: This exception is raised if ``key_material`` is not
+ ``bytes``.
+ :raises cryptography.exceptions.AlreadyFinalized: This is raised when
+ :meth:`derive` or
+ :meth:`verify` is
+ called more than
+ once.
+
+ Derives a new key from the input key material by performing both the
+ extract and expand operations.
+
+ .. method:: verify(key_material, expected_key)
+
+ :param bytes key_material: The input key material. This is the same as
+ ``key_material`` in :meth:`derive`.
+ :param bytes expected_key: The expected result of deriving a new key,
+ this is the same as the return value of
+ :meth:`derive`.
+ :raises cryptography.exceptions.InvalidKey: This is raised when the
+ derived key does not match
+ the expected key.
+ :raises cryptography.exceptions.AlreadyFinalized: This is raised when
+ :meth:`derive` or
+ :meth:`verify` is
+ called more than
+ once.
+ :raises TypeError: This is raised if the provided ``key_material`` is
+ a ``unicode`` object
+
+ This checks whether deriving a new key from the supplied
+ ``key_material`` generates the same key as the ``expected_key``, and
+ raises an exception if they do not match.
+
+
+KBKDF
+-----
+
+.. currentmodule:: cryptography.hazmat.primitives.kdf.kbkdf
+
+.. class:: KBKDFHMAC(algorithm, mode, length, rlen, llen, location,\
+ label, context, fixed, backend=None)
+
+ .. versionadded:: 1.4
+
+ KBKDF (Key Based Key Derivation Function) is defined by the
+ `NIST SP 800-108`_ document, to be used to derive additional
+ keys from a key that has been established through an automated
+ key-establishment scheme.
+
+ .. warning::
+
+ KBKDFHMAC should not be used for password storage.
+
+ .. doctest::
+
+ >>> import os
+ >>> from cryptography.hazmat.primitives import hashes
+ >>> from cryptography.hazmat.primitives.kdf.kbkdf import (
+ ... CounterLocation, KBKDFHMAC, Mode
+ ... )
+ >>> label = b"KBKDF HMAC Label"
+ >>> context = b"KBKDF HMAC Context"
+ >>> kdf = KBKDFHMAC(
+ ... algorithm=hashes.SHA256(),
+ ... mode=Mode.CounterMode,
+ ... length=32,
+ ... rlen=4,
+ ... llen=4,
+ ... location=CounterLocation.BeforeFixed,
+ ... label=label,
+ ... context=context,
+ ... fixed=None,
+ ... )
+ >>> key = kdf.derive(b"input key")
+ >>> kdf = KBKDFHMAC(
+ ... algorithm=hashes.SHA256(),
+ ... mode=Mode.CounterMode,
+ ... length=32,
+ ... rlen=4,
+ ... llen=4,
+ ... location=CounterLocation.BeforeFixed,
+ ... label=label,
+ ... context=context,
+ ... fixed=None,
+ ... )
+ >>> kdf.verify(b"input key", key)
+
+ :param algorithm: An instance of
+ :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`.
+
+ :param mode: The desired mode of the PRF. A value from the
+ :class:`~cryptography.hazmat.primitives.kdf.kbkdf.Mode` enum.
+
+ :param int length: The desired length of the derived key in bytes.
+
+ :param int rlen: An integer that indicates the length of the binary
+ representation of the counter in bytes.
+
+ :param int llen: An integer that indicates the binary
+ representation of the ``length`` in bytes.
+
+ :param location: The desired location of the counter. A value from the
+ :class:`~cryptography.hazmat.primitives.kdf.kbkdf.CounterLocation` enum.
+
+ :param bytes label: Application specific label information. If ``None``
+ is explicitly passed an empty byte string will be used.
+
+ :param bytes context: Application specific context information. If ``None``
+ is explicitly passed an empty byte string will be used.
+
+ :param bytes fixed: Instead of specifying ``label`` and ``context`` you
+ may supply your own fixed data. If ``fixed`` is specified, ``label``
+ and ``context`` is ignored.
+
+ :param backend: An optional instance of
+ :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`.
+
+ :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised
+ if the provided ``backend`` does not implement
+ :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
+
+ :raises TypeError: This exception is raised if ``label`` or ``context``
+ is not ``bytes``. Also raised if ``rlen`` or ``llen`` is not ``int``.
+
+ :raises ValueError: This exception is raised if ``rlen`` or ``llen``
+ is greater than 4 or less than 1. This exception is also raised if
+ you specify a ``label`` or ``context`` and ``fixed``.
+
+ .. method:: derive(key_material)
+
+ :param key_material: The input key material.
+ :type key_material: :term:`bytes-like`
+ :return bytes: The derived key.
+ :raises TypeError: This exception is raised if ``key_material`` is
+ not ``bytes``.
+ :raises cryptography.exceptions.AlreadyFinalized: This is raised when
+ :meth:`derive` or
+ :meth:`verify` is
+ called more than
+ once.
+
+ Derives a new key from the input key material.
+
+ .. method:: verify(key_material, expected_key)
+
+ :param bytes key_material: The input key material. This is the same as
+ ``key_material`` in :meth:`derive`.
+ :param bytes expected_key: The expected result of deriving a new key,
+ this is the same as the return value of
+ :meth:`derive`.
+ :raises cryptography.exceptions.InvalidKey: This is raised when the
+ derived key does not match
+ the expected key.
+ :raises cryptography.exceptions.AlreadyFinalized: This is raised when
+ :meth:`derive` or
+ :meth:`verify` is
+ called more than
+ once.
+
+ This checks whether deriving a new key from the supplied
+ ``key_material`` generates the same key as the ``expected_key``, and
+ raises an exception if they do not match.
+
+.. class:: Mode
+
+ An enumeration for the key based key derivative modes.
+
+ .. attribute:: CounterMode
+
+ The output of the PRF is computed with a counter
+ as the iteration variable.
+
+.. class:: CounterLocation
+
+ An enumeration for the key based key derivative counter location.
+
+ .. attribute:: BeforeFixed
+
+ The counter iteration variable will be concatenated before
+ the fixed input data.
+
+ .. attribute:: AfterFixed
+
+ The counter iteration variable will be concatenated after
+ the fixed input data.
+
+
+X963KDF
+-------
+
+.. currentmodule:: cryptography.hazmat.primitives.kdf.x963kdf
+
+.. class:: X963KDF(algorithm, length, otherinfo, backend=None)
+
+ .. versionadded:: 1.1
+
+ X963KDF (ANSI X9.63 Key Derivation Function) is defined by ANSI
+ in the `ANSI X9.63:2001`_ document, to be used to derive keys for use
+ after a Key Exchange negotiation operation.
+
+ SECG in `SEC 1 v2.0`_ recommends that
+ :class:`~cryptography.hazmat.primitives.kdf.concatkdf.ConcatKDFHash` be
+ used for new projects. This KDF should only be used for backwards
+ compatibility with pre-existing protocols.
+
+
+ .. warning::
+
+ X963KDF should not be used for password storage.
+
+ .. doctest::
+
+ >>> import os
+ >>> from cryptography.hazmat.primitives import hashes
+ >>> from cryptography.hazmat.primitives.kdf.x963kdf import X963KDF
+ >>> sharedinfo = b"ANSI X9.63 Example"
+ >>> xkdf = X963KDF(
+ ... algorithm=hashes.SHA256(),
+ ... length=32,
+ ... sharedinfo=sharedinfo,
+ ... )
+ >>> key = xkdf.derive(b"input key")
+ >>> xkdf = X963KDF(
+ ... algorithm=hashes.SHA256(),
+ ... length=32,
+ ... sharedinfo=sharedinfo,
+ ... )
+ >>> xkdf.verify(b"input key", key)
+
+ :param algorithm: An instance of
+ :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`.
+
+ :param int length: The desired length of the derived key in bytes.
+ Maximum is ``hashlen * (2^32 -1)``.
+
+ :param bytes sharedinfo: Application specific context information.
+ If ``None`` is explicitly passed an empty byte string will be used.
+
+ :param backend: An optional instance of
+ :class:`~cryptography.hazmat.backends.interfaces.HashBackend`.
+
+ :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised
+ if the provided ``backend`` does not implement
+ :class:`~cryptography.hazmat.backends.interfaces.HashBackend`
+
+ :raises TypeError: This exception is raised if ``sharedinfo`` is not
+ ``bytes``.
+
+ .. method:: derive(key_material)
+
+ :param key_material: The input key material.
+ :type key_material: :term:`bytes-like`
+ :return bytes: The derived key.
+ :raises TypeError: This exception is raised if ``key_material`` is
+ not ``bytes``.
+ :raises cryptography.exceptions.AlreadyFinalized: This is raised when
+ :meth:`derive` or
+ :meth:`verify` is
+ called more than
+ once.
+
+ Derives a new key from the input key material.
+
+ .. method:: verify(key_material, expected_key)
+
+ :param bytes key_material: The input key material. This is the same as
+ ``key_material`` in :meth:`derive`.
+ :param bytes expected_key: The expected result of deriving a new key,
+ this is the same as the return value of
+ :meth:`derive`.
+ :raises cryptography.exceptions.InvalidKey: This is raised when the
+ derived key does not match
+ the expected key.
+ :raises cryptography.exceptions.AlreadyFinalized: This is raised when
+ :meth:`derive` or
+ :meth:`verify` is
+ called more than
+ once.
+
+ This checks whether deriving a new key from the supplied
+ ``key_material`` generates the same key as the ``expected_key``, and
+ raises an exception if they do not match.
+
+
Interface
~~~~~~~~~
@@ -904,8 +929,8 @@
.. _`NIST SP 800-108`: https://csrc.nist.gov/publications/detail/sp/800-108/final
.. _`NIST SP 800-56Ar2`: https://csrc.nist.gov/publications/detail/sp/800-56a/rev-2/final
.. _`ANSI X9.63:2001`: https://webstore.ansi.org
-.. _`SEC 1 v2.0`: http://www.secg.org/sec1-v2.pdf
-.. _`Password Storage Cheat Sheet`: https://www.owasp.org/index.php/Password_Storage_Cheat_Sheet
+.. _`SEC 1 v2.0`: https://www.secg.org/sec1-v2.pdf
+.. _`more detailed description`: https://security.stackexchange.com/a/3993/43116
.. _`PBKDF2`: https://en.wikipedia.org/wiki/PBKDF2
.. _`key stretching`: https://en.wikipedia.org/wiki/Key_stretching
.. _`HKDF`: https://en.wikipedia.org/wiki/HKDF
diff --git a/docs/hazmat/primitives/keywrap.rst b/docs/hazmat/primitives/keywrap.rst
index 1c15f9d..9d8abbd 100644
--- a/docs/hazmat/primitives/keywrap.rst
+++ b/docs/hazmat/primitives/keywrap.rst
@@ -11,7 +11,7 @@
protections offered by key wrapping are also offered by using authenticated
:doc:`symmetric encryption </hazmat/primitives/symmetric-encryption>`.
-.. function:: aes_key_wrap(wrapping_key, key_to_wrap, backend)
+.. function:: aes_key_wrap(wrapping_key, key_to_wrap, backend=None)
.. versionadded:: 1.1
@@ -22,14 +22,14 @@
:param bytes key_to_wrap: The key to wrap.
- :param backend: A
+ :param backend: An optional
:class:`~cryptography.hazmat.backends.interfaces.CipherBackend`
instance that supports
:class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES`.
:return bytes: The wrapped key as bytes.
-.. function:: aes_key_unwrap(wrapping_key, wrapped_key, backend)
+.. function:: aes_key_unwrap(wrapping_key, wrapped_key, backend=None)
.. versionadded:: 1.1
@@ -40,7 +40,7 @@
:param bytes wrapped_key: The wrapped key.
- :param backend: A
+ :param backend: An optional
:class:`~cryptography.hazmat.backends.interfaces.CipherBackend`
instance that supports
:class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES`.
@@ -50,7 +50,7 @@
:raises cryptography.hazmat.primitives.keywrap.InvalidUnwrap: This is
raised if the key is not successfully unwrapped.
-.. function:: aes_key_wrap_with_padding(wrapping_key, key_to_wrap, backend)
+.. function:: aes_key_wrap_with_padding(wrapping_key, key_to_wrap, backend=None)
.. versionadded:: 2.2
@@ -61,14 +61,14 @@
:param bytes key_to_wrap: The key to wrap.
- :param backend: A
+ :param backend: An optional
:class:`~cryptography.hazmat.backends.interfaces.CipherBackend`
instance that supports
:class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES`.
:return bytes: The wrapped key as bytes.
-.. function:: aes_key_unwrap_with_padding(wrapping_key, wrapped_key, backend)
+.. function:: aes_key_unwrap_with_padding(wrapping_key, wrapped_key, backend=None)
.. versionadded:: 2.2
@@ -79,7 +79,7 @@
:param bytes wrapped_key: The wrapped key.
- :param backend: A
+ :param backend: An optional
:class:`~cryptography.hazmat.backends.interfaces.CipherBackend`
instance that supports
:class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES`.
diff --git a/docs/hazmat/primitives/mac/cmac.rst b/docs/hazmat/primitives/mac/cmac.rst
index a5b13ca..b40a90a 100644
--- a/docs/hazmat/primitives/mac/cmac.rst
+++ b/docs/hazmat/primitives/mac/cmac.rst
@@ -17,7 +17,7 @@
A subset of CMAC with the AES-128 algorithm is described in :rfc:`4493`.
-.. class:: CMAC(algorithm, backend)
+.. class:: CMAC(algorithm, backend=None)
.. versionadded:: 0.4
@@ -26,10 +26,9 @@
.. doctest::
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives import cmac
>>> from cryptography.hazmat.primitives.ciphers import algorithms
- >>> c = cmac.CMAC(algorithms.AES(key), backend=default_backend())
+ >>> c = cmac.CMAC(algorithms.AES(key))
>>> c.update(b"message to authenticate")
>>> c.finalize()
b'CT\x1d\xc8\x0e\x15\xbe4e\xdb\xb6\x84\xca\xd9Xk'
@@ -47,7 +46,7 @@
.. doctest::
- >>> c = cmac.CMAC(algorithms.AES(key), backend=default_backend())
+ >>> c = cmac.CMAC(algorithms.AES(key))
>>> c.update(b"message to authenticate")
>>> c.verify(b"an incorrect signature")
Traceback (most recent call last):
@@ -56,7 +55,7 @@
:param algorithm: An instance of
:class:`~cryptography.hazmat.primitives.ciphers.BlockCipherAlgorithm`.
- :param backend: An instance of
+ :param backend: An optional instance of
:class:`~cryptography.hazmat.backends.interfaces.CMACBackend`.
:raises TypeError: This is raised if the provided ``algorithm`` is not an instance of
:class:`~cryptography.hazmat.primitives.ciphers.BlockCipherAlgorithm`
diff --git a/docs/hazmat/primitives/mac/hmac.rst b/docs/hazmat/primitives/mac/hmac.rst
index 9d11694..3695270 100644
--- a/docs/hazmat/primitives/mac/hmac.rst
+++ b/docs/hazmat/primitives/mac/hmac.rst
@@ -15,7 +15,7 @@
secret key. You can use an HMAC to verify both the integrity and authenticity
of a message.
-.. class:: HMAC(key, algorithm, backend)
+.. class:: HMAC(key, algorithm, backend=None)
HMAC objects take a ``key`` and a
:class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` instance.
@@ -27,9 +27,8 @@
.. doctest::
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives import hashes, hmac
- >>> h = hmac.HMAC(key, hashes.SHA256(), backend=default_backend())
+ >>> h = hmac.HMAC(key, hashes.SHA256())
>>> h.update(b"message to hash")
>>> h.finalize()
b'#F\xdaI\x8b"e\xc4\xf1\xbb\x9a\x8fc\xff\xf5\xdex.\xbc\xcd/+\x8a\x86\x1d\x84\'\xc3\xa6\x1d\xd8J'
@@ -47,7 +46,7 @@
.. doctest::
- >>> h = hmac.HMAC(key, hashes.SHA256(), backend=default_backend())
+ >>> h = hmac.HMAC(key, hashes.SHA256())
>>> h.update(b"message to hash")
>>> h.verify(b"an incorrect signature")
Traceback (most recent call last):
@@ -60,7 +59,7 @@
:class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`
instance such as those described in
:ref:`Cryptographic Hashes <cryptographic-hash-algorithms>`.
- :param backend: An
+ :param backend: An optional
:class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
instance.
diff --git a/docs/hazmat/primitives/mac/index.rst b/docs/hazmat/primitives/mac/index.rst
index 86c407c..8bfe29e 100644
--- a/docs/hazmat/primitives/mac/index.rst
+++ b/docs/hazmat/primitives/mac/index.rst
@@ -3,48 +3,17 @@
Message authentication codes
============================
-While cryptography supports both the CMAC and HMAC algorithms, we strongly
-recommend that HMAC should be used unless you have a good reason otherwise.
+While cryptography supports multiple MAC algorithms, we strongly
+recommend that HMAC should be used unless you have a very specific need.
For more information on why HMAC is preferred, see `Use cases for CMAC vs.
HMAC?`_
-HMAC and CMAC both use the ``MACContext`` interface:
-
-.. currentmodule:: cryptography.hazmat.primitives.mac
-
-.. class:: MACContext
-
- .. versionadded:: 0.7
-
- .. method:: update(data)
-
- :param bytes data: The data you want to authenticate.
-
- .. method:: finalize()
-
- :return: The message authentication code.
-
- .. method:: copy()
-
- :return: A
- :class:`~cryptography.hazmat.primitives.mac.MACContext` that
- is a copy of the current context.
-
- .. method:: verify(signature)
-
- :param bytes signature: The signature to verify.
-
- :raises cryptography.exceptions.InvalidSignature: This is raised when
- the provided signature does not match the expected signature.
-
-
-
-.. _`CMAC`: https://en.wikipedia.org/wiki/CMAC
-.. _`Use cases for CMAC vs. HMAC?`: https://crypto.stackexchange.com/questions/15721/use-cases-for-cmac-vs-hmac
-
.. toctree::
:maxdepth: 1
cmac
hmac
+ poly1305
+
+.. _`Use cases for CMAC vs. HMAC?`: https://crypto.stackexchange.com/questions/15721/use-cases-for-cmac-vs-hmac
diff --git a/docs/hazmat/primitives/mac/poly1305.rst b/docs/hazmat/primitives/mac/poly1305.rst
new file mode 100644
index 0000000..7504a07
--- /dev/null
+++ b/docs/hazmat/primitives/mac/poly1305.rst
@@ -0,0 +1,132 @@
+.. hazmat::
+
+Poly1305
+========
+
+.. currentmodule:: cryptography.hazmat.primitives.poly1305
+
+.. testsetup::
+
+ key = b"\x01" * 32
+
+Poly1305 is an authenticator that takes a 32-byte key and a message and
+produces a 16-byte tag. This tag is used to authenticate the message. Each key
+**must** only be used once. Using the same key to generate tags for multiple
+messages allows an attacker to forge tags. Poly1305 is described in
+:rfc:`7539`.
+
+.. class:: Poly1305(key)
+
+ .. versionadded:: 2.7
+
+ .. warning::
+
+ Using the same key to generate tags for multiple messages allows an
+ attacker to forge tags. Always generate a new key per message you want
+ to authenticate. If you are using this as a MAC for
+ symmetric encryption please use
+ :class:`~cryptography.hazmat.primitives.ciphers.aead.ChaCha20Poly1305`
+ instead.
+
+ .. doctest::
+
+ >>> from cryptography.hazmat.primitives import poly1305
+ >>> p = poly1305.Poly1305(key)
+ >>> p.update(b"message to authenticate")
+ >>> p.finalize()
+ b'T\xae\xff3\xbdW\xef\xd5r\x01\xe2n=\xb7\xd2h'
+
+ To check that a given tag is correct use the :meth:`verify` method.
+ You will receive an exception if the tag is wrong:
+
+ .. doctest::
+
+ >>> p = poly1305.Poly1305(key)
+ >>> p.update(b"message to authenticate")
+ >>> p.verify(b"an incorrect tag")
+ Traceback (most recent call last):
+ ...
+ cryptography.exceptions.InvalidSignature: Value did not match computed tag.
+
+ :param key: Secret key as ``bytes``.
+ :type key: :term:`bytes-like`
+ :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if
+ the version of OpenSSL ``cryptography`` is compiled against does not
+ support this algorithm.
+
+ .. method:: update(data)
+
+ :param data: The bytes to hash and authenticate.
+ :type data: :term:`bytes-like`
+ :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`
+ :raises TypeError: This exception is raised if ``data`` is not ``bytes``.
+
+ .. method:: verify(tag)
+
+ Finalize the current context and securely compare the MAC to
+ ``tag``.
+
+ :param bytes tag: The bytes to compare against.
+ :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`
+ :raises cryptography.exceptions.InvalidSignature: If tag does not
+ match.
+ :raises TypeError: This exception is raised if ``tag`` is not
+ ``bytes``.
+
+ .. method:: finalize()
+
+ Finalize the current context and return the message authentication code
+ as bytes.
+
+ After ``finalize`` has been called this object can no longer be used
+ and :meth:`update`, :meth:`verify`, and :meth:`finalize`
+ will raise an :class:`~cryptography.exceptions.AlreadyFinalized`
+ exception.
+
+ :return bytes: The message authentication code as bytes.
+ :raises cryptography.exceptions.AlreadyFinalized:
+
+ .. classmethod:: generate_tag(key, data)
+
+ A single step alternative to do sign operations. Returns the message
+ authentication code as ``bytes`` for the given ``key`` and ``data``.
+
+ :param key: Secret key as ``bytes``.
+ :type key: :term:`bytes-like`
+ :param data: The bytes to hash and authenticate.
+ :type data: :term:`bytes-like`
+ :return bytes: The message authentication code as bytes.
+ :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if
+ the version of OpenSSL ``cryptography`` is compiled against does not
+ support this algorithm.
+ :raises TypeError: This exception is raised if ``key`` or ``data`` are
+ not ``bytes``.
+
+ .. doctest::
+
+ >>> poly1305.Poly1305.generate_tag(key, b"message to authenticate")
+ b'T\xae\xff3\xbdW\xef\xd5r\x01\xe2n=\xb7\xd2h'
+
+ .. classmethod:: verify_tag(key, data, tag)
+
+ A single step alternative to do verify operations. Securely compares the
+ MAC to ``tag``, using the given ``key`` and ``data``.
+
+ :param key: Secret key as ``bytes``.
+ :type key: :term:`bytes-like`
+ :param data: The bytes to hash and authenticate.
+ :type data: :term:`bytes-like`
+ :param bytes tag: The bytes to compare against.
+ :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if
+ the version of OpenSSL ``cryptography`` is compiled against does not
+ support this algorithm.
+ :raises TypeError: This exception is raised if ``key``, ``data`` or
+ ``tag`` are not ``bytes``.
+ :raises cryptography.exceptions.InvalidSignature: If tag does not match.
+
+ .. doctest::
+
+ >>> poly1305.Poly1305.verify_tag(key, b"message to authenticate", b"an incorrect tag")
+ Traceback (most recent call last):
+ ...
+ cryptography.exceptions.InvalidSignature: Value did not match computed tag.
diff --git a/docs/hazmat/primitives/padding.rst b/docs/hazmat/primitives/padding.rst
index 9581df8..99d500a 100644
--- a/docs/hazmat/primitives/padding.rst
+++ b/docs/hazmat/primitives/padding.rst
@@ -107,7 +107,8 @@
.. method:: update(data)
- :param bytes data: The data you wish to pass into the context.
+ :param data: The data you wish to pass into the context.
+ :type data: :term:`bytes-like`
:return bytes: Returns the data that was padded or unpadded.
:raises TypeError: Raised if data is not bytes.
:raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`.
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst
index 21d12a3..8551acb 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -11,7 +11,8 @@
encryption is **not** sufficient for most applications because it only
provides secrecy but not authenticity. That means an attacker can't see the
message but an attacker can create bogus messages and force the application to
-decrypt them.
+decrypt them. In many contexts, a lack of authentication on encrypted messages
+can result in a loss of secrecy as well.
For this reason it is **strongly** recommended to combine encryption with a
message authentication code, such as :doc:`HMAC </hazmat/primitives/mac/hmac>`,
@@ -20,7 +21,7 @@
**To minimize the risk of security issues you should evaluate Fernet to see if
it fits your needs before implementing anything using this module.**
-.. class:: Cipher(algorithm, mode, backend)
+.. class:: Cipher(algorithm, mode, backend=None)
Cipher objects combine an algorithm such as
:class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES` with a
@@ -33,25 +34,23 @@
>>> import os
>>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
- >>> from cryptography.hazmat.backends import default_backend
- >>> backend = default_backend()
>>> key = os.urandom(32)
>>> iv = os.urandom(16)
- >>> cipher = Cipher(algorithms.AES(key), modes.CBC(iv), backend=backend)
+ >>> cipher = Cipher(algorithms.AES(key), modes.CBC(iv))
>>> encryptor = cipher.encryptor()
>>> ct = encryptor.update(b"a secret message") + encryptor.finalize()
>>> decryptor = cipher.decryptor()
>>> decryptor.update(ct) + decryptor.finalize()
b'a secret message'
- :param algorithms: A
+ :param algorithm: A
:class:`~cryptography.hazmat.primitives.ciphers.CipherAlgorithm`
instance such as those described
:ref:`below <symmetric-encryption-algorithms>`.
:param mode: A :class:`~cryptography.hazmat.primitives.ciphers.modes.Mode`
instance such as those described
:ref:`below <symmetric-encryption-modes>`.
- :param backend: A
+ :param backend: An optional
:class:`~cryptography.hazmat.backends.interfaces.CipherBackend`
instance.
@@ -147,10 +146,9 @@
.. doctest::
>>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
- >>> from cryptography.hazmat.backends import default_backend
>>> nonce = os.urandom(16)
>>> algorithm = algorithms.ChaCha20(key, nonce)
- >>> cipher = Cipher(algorithm, mode=None, backend=default_backend())
+ >>> cipher = Cipher(algorithm, mode=None)
>>> encryptor = cipher.encryptor()
>>> ct = encryptor.update(b"a secret message")
>>> decryptor = cipher.decryptor()
@@ -231,9 +229,8 @@
.. doctest::
>>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
- >>> from cryptography.hazmat.backends import default_backend
>>> algorithm = algorithms.ARC4(key)
- >>> cipher = Cipher(algorithm, mode=None, backend=default_backend())
+ >>> cipher = Cipher(algorithm, mode=None)
>>> encryptor = cipher.encryptor()
>>> ct = encryptor.update(b"a secret message")
>>> decryptor = cipher.decryptor()
@@ -418,9 +415,6 @@
:raises ValueError: This is raised if ``len(tag) < min_tag_length`` or the
``initialization_vector`` is too short.
- :raises NotImplementedError: This is raised if the version of the OpenSSL
- backend used is 1.0.1 or earlier.
-
An example of securely encrypting and decrypting data with ``AES`` in the
``GCM`` mode looks like:
@@ -428,7 +422,6 @@
import os
- from cryptography.hazmat.backends import default_backend
from cryptography.hazmat.primitives.ciphers import (
Cipher, algorithms, modes
)
@@ -442,7 +435,6 @@
encryptor = Cipher(
algorithms.AES(key),
modes.GCM(iv),
- backend=default_backend()
).encryptor()
# associated_data will be authenticated but not encrypted,
@@ -461,7 +453,6 @@
decryptor = Cipher(
algorithms.AES(key),
modes.GCM(iv, tag),
- backend=default_backend()
).decryptor()
# We put associated_data back in or the tag will fail to verify
@@ -598,11 +589,9 @@
>>> import os
>>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
- >>> from cryptography.hazmat.backends import default_backend
- >>> backend = default_backend()
>>> key = os.urandom(32)
>>> iv = os.urandom(16)
- >>> cipher = Cipher(algorithms.AES(key), modes.CBC(iv), backend=backend)
+ >>> cipher = Cipher(algorithms.AES(key), modes.CBC(iv))
>>> encryptor = cipher.encryptor()
>>> # the buffer needs to be at least len(data) + n - 1 where n is cipher/mode block size in bytes
>>> buf = bytearray(31)
@@ -681,18 +670,12 @@
.. method:: finalize_with_tag(tag)
- .. note::
-
- This method is not supported when compiled against OpenSSL 1.0.1.
-
:param bytes tag: The tag bytes to verify after decryption.
:return bytes: Returns the remainder of the data.
:raises ValueError: This is raised when the data provided isn't
a multiple of the algorithm's block size, if ``min_tag_length`` is
less than 4, or if ``len(tag) < min_tag_length``.
``min_tag_length`` is an argument to the ``GCM`` constructor.
- :raises NotImplementedError: This is raised if the version of the
- OpenSSL backend used is 1.0.1 or earlier.
If the authentication tag was not already supplied to the constructor
of the :class:`~cryptography.hazmat.primitives.ciphers.modes.GCM` mode
@@ -828,7 +811,7 @@
.. _`Communications Security Establishment`: https://www.cse-cst.gc.ca
.. _`encrypt`: https://ssd.eff.org/en/module/what-should-i-know-about-encryption
.. _`CRYPTREC`: https://www.cryptrec.go.jp/english/
-.. _`significant patterns in the output`: https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Electronic_Codebook_.28ECB.29
+.. _`significant patterns in the output`: https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Electronic_codebook_(ECB)
.. _`International Data Encryption Algorithm`: https://en.wikipedia.org/wiki/International_Data_Encryption_Algorithm
.. _`OpenPGP`: https://www.openpgp.org/
.. _`disk encryption`: https://en.wikipedia.org/wiki/Disk_encryption_theory#XTS
diff --git a/docs/hazmat/primitives/twofactor.rst b/docs/hazmat/primitives/twofactor.rst
index 51625df..1d2ab45 100644
--- a/docs/hazmat/primitives/twofactor.rst
+++ b/docs/hazmat/primitives/twofactor.rst
@@ -18,7 +18,7 @@
.. currentmodule:: cryptography.hazmat.primitives.twofactor.hotp
-.. class:: HOTP(key, length, algorithm, backend, enforce_key_length=True)
+.. class:: HOTP(key, length, algorithm, backend=None, enforce_key_length=True)
.. versionadded:: 0.3
@@ -33,11 +33,10 @@
.. doctest::
>>> import os
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives.twofactor.hotp import HOTP
>>> from cryptography.hazmat.primitives.hashes import SHA1
>>> key = os.urandom(20)
- >>> hotp = HOTP(key, 6, SHA1(), backend=default_backend())
+ >>> hotp = HOTP(key, 6, SHA1())
>>> hotp_value = hotp.generate(0)
>>> hotp.verify(hotp_value, 0)
@@ -49,15 +48,15 @@
:param cryptography.hazmat.primitives.hashes.HashAlgorithm algorithm: A
:class:`~cryptography.hazmat.primitives.hashes`
instance.
- :param backend: A
+ :param backend: An optional
:class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
instance.
:param enforce_key_length: A boolean flag defaulting to True that toggles
whether a minimum key length of 128 :term:`bits` is enforced. This
exists to work around the fact that as documented in `Issue #2915`_,
the Google Authenticator PAM module by default generates 80 bit keys.
- If this flag is set to False, the application develop should implement
- additional checks of the key length before passing it into
+ If this flag is set to False, the application developer should
+ implement additional checks of the key length before passing it into
:class:`~cryptography.hazmat.primitives.twofactor.hotp.HOTP`.
.. versionadded:: 1.5
@@ -129,7 +128,7 @@
assert look_ahead >= 0
correct_counter = None
- otp = HOTP(key, 6, default_backend())
+ otp = HOTP(key, 6)
for count in range(counter, counter + look_ahead):
try:
otp.verify(hotp, count)
@@ -141,7 +140,7 @@
.. currentmodule:: cryptography.hazmat.primitives.twofactor.totp
-.. class:: TOTP(key, length, algorithm, time_step, backend, enforce_key_length=True)
+.. class:: TOTP(key, length, algorithm, time_step, backend=None, enforce_key_length=True)
TOTP objects take a ``key``, ``length``, ``algorithm`` and ``time_step``
parameter. The ``key`` should be :doc:`randomly generated bytes
@@ -155,11 +154,10 @@
>>> import os
>>> import time
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives.twofactor.totp import TOTP
>>> from cryptography.hazmat.primitives.hashes import SHA1
>>> key = os.urandom(20)
- >>> totp = TOTP(key, 8, SHA1(), 30, backend=default_backend())
+ >>> totp = TOTP(key, 8, SHA1(), 30)
>>> time_value = time.time()
>>> totp_value = totp.generate(time_value)
>>> totp.verify(totp_value, time_value)
@@ -173,7 +171,7 @@
:class:`~cryptography.hazmat.primitives.hashes`
instance.
:param int time_step: The time step size. The recommended size is 30.
- :param backend: A
+ :param backend: An optional
:class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
instance.
:param enforce_key_length: A boolean flag defaulting to True that toggles
diff --git a/docs/index.rst b/docs/index.rst
index 9ff8664..ec3913f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -19,7 +19,8 @@
'A really secret message. Not for prying eyes.'
If you are interested in learning more about the field of cryptography, we
-recommend `Crypto 101, by Laurens Van Houtven`_.
+recommend `Crypto 101, by Laurens Van Houtven`_ and `The Cryptopals Crypto
+Challenges`_.
Installation
------------
@@ -67,7 +68,6 @@
exceptions
random-numbers
hazmat/backends/index
- hazmat/bindings/index
.. toctree::
:maxdepth: 2
@@ -92,3 +92,4 @@
:doc:`get in touch </community>`.
.. _`Crypto 101, by Laurens Van Houtven`: https://www.crypto101.io/
+.. _`The Cryptopals Crypto Challenges`: https://cryptopals.com/
diff --git a/docs/installation.rst b/docs/installation.rst
index 5b2854d..ea46255 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -10,29 +10,26 @@
Supported platforms
-------------------
-Currently we test ``cryptography`` on Python 2.7, 3.4+, and
-PyPy 5.4+ on these operating systems.
+Currently we test ``cryptography`` on Python 2.7, 3.6+,
+PyPy 7.3.1, and PyPy3 7.3.1 on these operating systems.
* x86-64 CentOS 7.x
-* macOS 10.12 Sierra, 10.11 El Capitan
-* x86-64 Ubuntu 14.04, 16.04, and rolling
-* x86-64 Debian Wheezy (7.x), Jessie (8.x), Stretch (9.x), and Sid (unstable)
+* x86-64 & AArch64 CentOS 8.x
+* x86-64 Fedora (latest)
+* x86-64 macOS 10.15 Catalina
+* x86-64 & AArch64 Ubuntu 18.04, 20.04
+* x86-64 Ubuntu rolling
+* x86-64 Debian Stretch (9.x), Buster (10.x), Bullseye (11.x), and Sid
+ (unstable)
* x86-64 Alpine (latest)
-* 32-bit and 64-bit Python on 64-bit Windows Server 2012
+* 32-bit and 64-bit Python on 64-bit Windows Server 2019
We test compiling with ``clang`` as well as ``gcc`` and use the following
OpenSSL releases:
-* ``OpenSSL 1.0.1``
-* ``OpenSSL 1.0.1e-fips`` (``RHEL/CentOS 7``)
-* ``OpenSSL 1.0.1f``
-* ``OpenSSL 1.0.2-latest``
* ``OpenSSL 1.1.0-latest``
* ``OpenSSL 1.1.1-latest``
-.. warning::
- Cryptography 2.4 has deprecated support for OpenSSL 1.0.1.
-
Building cryptography on Windows
--------------------------------
@@ -46,12 +43,11 @@
$ pip install cryptography
If you prefer to compile it yourself you'll need to have OpenSSL installed.
-You can compile OpenSSL yourself as well or use the binaries we build for our
-release infrastructure (`openssl-release`_). Be sure to download the proper
-version for your architecture and Python (2010 works for Python 2.7, 3.3,
-and 3.4 while 2015 is required for 3.5 and above). Wherever you place your copy
-of OpenSSL you'll need to set the ``LIB`` and ``INCLUDE`` environment variables
-to include the proper locations. For example:
+You can compile OpenSSL yourself as well or use `a binary distribution`_.
+Be sure to download the proper version for your architecture and Python
+(VC2010 works for Python 2.7 while VC2015 is required for 3.6 and above).
+Wherever you place your copy of OpenSSL you'll need to set the ``LIB`` and ``INCLUDE``
+environment variables to include the proper locations. For example:
.. code-block:: console
@@ -74,10 +70,10 @@
Building cryptography on Linux
------------------------------
-``cryptography`` ships a ``manylinux1`` wheel (as of 2.0) so all dependencies
-are included. For users on pip 8.1 or above running on a ``manylinux1``
-compatible distribution (almost everything except Alpine) all you should
-need to do is:
+``cryptography`` ships ``manylinux`` wheels (as of 2.0) so all dependencies
+are included. For users on pip 8.1 or above running on a ``manylinux1`` or
+``manylinux2010`` compatible distribution (almost everything except Alpine)
+all you should need to do is:
.. code-block:: console
@@ -121,8 +117,8 @@
~~~~~~~~
You should now be able to build and install cryptography. To avoid getting
-the pre-built wheel on ``manylinux1`` distributions you'll need to use
-``--no-binary``.
+the pre-built wheel on ``manylinux`` compatible distributions you'll need to
+use ``--no-binary``.
.. code-block:: console
@@ -162,9 +158,9 @@
~~~~~~~~~~~~~
Cryptography ships statically-linked wheels for macOS, Windows, and Linux (via
-``manylinux1``). This allows compatible environments to use the most recent
+``manylinux``). This allows compatible environments to use the most recent
OpenSSL, regardless of what is shipped by default on those platforms. Some
-Linux distributions (most notably Alpine) are not ``manylinux1`` compatible so
+Linux distributions (most notably Alpine) are not ``manylinux`` compatible so
we cannot distribute wheels for them.
However, you can build your own statically-linked wheels that will work on your
@@ -228,7 +224,7 @@
If you want to build cryptography yourself or are on an older macOS version,
cryptography requires the presence of a C compiler, development headers, and
the proper libraries. On macOS much of this is provided by Apple's Xcode
-development tools. To install the Xcode command line tools (on macOS 10.9+)
+development tools. To install the Xcode command line tools (on macOS 10.10+)
open a terminal window and run:
.. code-block:: console
@@ -279,7 +275,7 @@
.. _`Homebrew`: https://brew.sh
.. _`MacPorts`: https://www.macports.org
-.. _`openssl-release`: https://ci.cryptography.io/job/cryptography-support-jobs/job/openssl-release-1.1/
+.. _`a binary distribution`: https://wiki.openssl.org/index.php/Binaries
.. _virtualenv: https://virtualenv.pypa.io/en/latest/
.. _openssl.org: https://www.openssl.org/source/
.. _`wheel cache`: https://pip.pypa.io/en/stable/reference/pip_install/#caching
diff --git a/docs/limitations.rst b/docs/limitations.rst
index 503bdfe..5763ecd 100644
--- a/docs/limitations.rst
+++ b/docs/limitations.rst
@@ -1,19 +1,44 @@
Known security limitations
---------------------------
+==========================
-Lack of secure memory wiping
-============================
+Secure memory wiping
+--------------------
`Memory wiping`_ is used to protect secret data or key material from attackers
-with access to uninitialized memory. This can be either because the attacker
-has some kind of local user access or because of how other software uses
-uninitialized memory.
+with access to deallocated memory. This is a defense-in-depth measure against
+vulnerabilities that leak application memory.
-Python exposes no API for us to implement this reliably and as such almost all
-software in Python is potentially vulnerable to this attack. The
+Many ``cryptography`` APIs which accept ``bytes`` also accept types which
+implement the buffer interface. Thus, users wishing to do so can pass
+``memoryview`` or another mutable type to ``cryptography`` APIs, and overwrite
+the contents once the data is no longer needed.
+
+However, ``cryptography`` does not clear memory by default, as there is no way
+to clear immutable structures such as ``bytes``. As a result, ``cryptography``,
+like almost all software in Python is potentially vulnerable to this attack. The
`CERT secure coding guidelines`_ assesses this issue as "Severity: medium,
Likelihood: unlikely, Remediation Cost: expensive to repair" and we do not
consider this a high risk for most users.
-.. _`Memory wiping`: https://blogs.msdn.microsoft.com/oldnewthing/20130529-00/?p=4223/
-.. _`CERT secure coding guidelines`: https://www.securecoding.cert.org/confluence/display/c/MEM03-C.+Clear+sensitive+information+stored+in+reusable+resources
+RSA PKCS1 v1.5 constant time decryption
+---------------------------------------
+
+RSA decryption has several different modes, one of which is PKCS1 v1.5. When
+used in online contexts, a secure protocol implementation requires that peers
+not be able to tell whether RSA PKCS1 v1.5 decryption failed or succeeded,
+even by timing variability.
+
+``cryptography`` does not provide an API that makes this possible, due to the
+fact that RSA decryption raises an exception on failure, which takes a
+different amount of time than returning a value in the success case.
+
+For this reason, at present, we recommend not implementing online protocols
+that use RSA PKCS1 v1.5 decryption with ``cryptography`` -- independent of this
+limitation, such protocols generally have poor security properties due to their
+lack of forward security.
+
+If a constant time RSA PKCS1 v1.5 decryption API is truly required, you should
+contribute one to ``cryptography``.
+
+.. _`Memory wiping`: https://devblogs.microsoft.com/oldnewthing/?p=4223
+.. _`CERT secure coding guidelines`: https://wiki.sei.cmu.edu/confluence/display/c/MEM03-C.+Clear+sensitive+information+stored+in+reusable+resources
diff --git a/docs/security.rst b/docs/security.rst
index 01845a4..d11f270 100644
--- a/docs/security.rst
+++ b/docs/security.rst
@@ -9,9 +9,9 @@
--------------
In addition to ``cryptography``'s code, we're also concerned with the security
-of the infrastructure we run (primarily ``cryptography.io`` and
-``ci.cryptography.io``). If you discover a security vulnerability in our
-infrastructure, we ask you to report it using the same procedure.
+of the infrastructure we run (primarily ``cryptography.io``). If you discover
+a security vulnerability in our infrastructure, we ask you to report it using
+the same procedure.
What is a security issue?
-------------------------
@@ -53,10 +53,9 @@
tracker.
If you believe you've identified a security issue with ``cryptography``, please
-report it to ``alex.gaynor@gmail.com``. Messages may be optionally encrypted
-with PGP using key fingerprint
-``F7FC 698F AAE2 D2EF BECD E98E D1B3 ADC0 E023 8CA6`` (this public key is
-available from most commonly-used key servers).
+report it to ``alex.gaynor@gmail.com`` and/or ``paul.l.kehrer@gmail.com``. You
+should verify that your MTA uses TLS to ensure the confidentiality of your
+message.
Once you've submitted an issue via email, you should receive an acknowledgment
within 48 hours, and depending on the action to be taken, you may receive
@@ -72,9 +71,9 @@
--------------------------------
As of versions 0.5, 1.0.1, and 2.0.0, ``cryptography`` statically links OpenSSL
-on Windows, macOS, and Linux respectively, to ease installation. Due to this,
-``cryptography`` will release a new version whenever OpenSSL has a security or
-bug fix release to avoid shipping insecure software.
+in binary distributions for Windows, macOS, and Linux respectively, to ease
+installation. Due to this, ``cryptography`` will release a new version whenever
+OpenSSL has a security or bug fix release to avoid shipping insecure software.
Like all our other releases, this will be announced on the mailing list and we
strongly recommend that you upgrade as soon as possible.
diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt
index 7e08f12..f0486e0 100644
--- a/docs/spelling_wordlist.txt
+++ b/docs/spelling_wordlist.txt
@@ -1,14 +1,18 @@
+AArch
accessor
affine
Authenticator
+authenticator
backend
Backends
backends
bcrypt
+Bleichenbacher
Blowfish
boolean
Botan
Brainpool
+Bullseye
Capitan
changelog
Changelog
@@ -17,11 +21,13 @@
committer
committers
conda
+CPython
Cryptanalysis
crypto
cryptographic
cryptographically
Debian
+deallocated
decrypt
decrypts
Decrypts
@@ -50,9 +56,9 @@
hazmat
Homebrew
hostname
-idna
indistinguishability
initialisms
+interoperability
interoperable
introspectability
invariants
@@ -76,6 +82,7 @@
personalization
pickleable
plaintext
+Poly
pre
precompute
preprocessor
@@ -83,6 +90,7 @@
presentational
pseudorandom
pyOpenSSL
+pytest
relicensed
responder
runtime
@@ -95,6 +103,7 @@
syscall
Tanja
testability
+Thawte
timestamp
timestamps
tunable
diff --git a/docs/x509/ocsp.rst b/docs/x509/ocsp.rst
index d3815d6..0c2d07a 100644
--- a/docs/x509/ocsp.rst
+++ b/docs/x509/ocsp.rst
@@ -167,12 +167,11 @@
.. doctest::
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives import serialization
>>> from cryptography.hazmat.primitives.hashes import SHA1
>>> from cryptography.x509 import load_pem_x509_certificate, ocsp
- >>> cert = load_pem_x509_certificate(pem_cert, default_backend())
- >>> issuer = load_pem_x509_certificate(pem_issuer, default_backend())
+ >>> cert = load_pem_x509_certificate(pem_cert)
+ >>> issuer = load_pem_x509_certificate(pem_issuer)
>>> builder = ocsp.OCSPRequestBuilder()
>>> # SHA1 is in this example because RFC 5019 mandates its use.
>>> builder = builder.add_certificate(cert, issuer, SHA1())
@@ -292,27 +291,35 @@
:attr:`~cryptography.x509.ocsp.OCSPResponseStatus.SUCCESSFUL` response.
:param private_key: The
- :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`
- or
- :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey`
+ :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`,
+ :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey`,
+ :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey`,
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey` or
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed448.Ed448PrivateKey`
that will be used to sign the certificate.
:param algorithm: The
:class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` that
- will be used to generate the signature.
+ will be used to generate the signature. This must be ``None`` if
+ the ``private_key`` is an
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey`
+ or an
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed448.Ed448PrivateKey`
+ and an instance of a
+ :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`
+ otherwise.
:returns: A new :class:`~cryptography.x509.ocsp.OCSPResponse`.
.. doctest::
>>> import datetime
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives import hashes, serialization
>>> from cryptography.x509 import load_pem_x509_certificate, ocsp
- >>> cert = load_pem_x509_certificate(pem_cert, default_backend())
- >>> issuer = load_pem_x509_certificate(pem_issuer, default_backend())
- >>> responder_cert = load_pem_x509_certificate(pem_responder_cert, default_backend())
- >>> responder_key = serialization.load_pem_private_key(pem_responder_key, None, default_backend())
+ >>> cert = load_pem_x509_certificate(pem_cert)
+ >>> issuer = load_pem_x509_certificate(pem_issuer)
+ >>> responder_cert = load_pem_x509_certificate(pem_responder_cert)
+ >>> responder_key = serialization.load_pem_private_key(pem_responder_key, None)
>>> builder = ocsp.OCSPResponseBuilder()
>>> # SHA1 is in this example because RFC 5019 mandates its use.
>>> builder = builder.add_response(
@@ -341,7 +348,6 @@
.. doctest::
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives import hashes, serialization
>>> from cryptography.x509 import load_pem_x509_certificate, ocsp
>>> response = ocsp.OCSPResponseBuilder.build_unsuccessful(
@@ -434,7 +440,10 @@
Returns the
:class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` which
- was used in signing this response.
+ was used in signing this response. Can be ``None`` if signature
+ did not use separate hash
+ (:attr:`~cryptography.x509.oid.SignatureAlgorithmOID.ED25519`,
+ :attr:`~cryptography.x509.oid.SignatureAlgorithmOID.ED448`).
.. attribute:: signature
@@ -589,6 +598,14 @@
The extensions encoded in the response.
+ .. attribute:: single_extensions
+
+ .. versionadded:: 2.9
+
+ :type: :class:`~cryptography.x509.Extensions`
+
+ The single extensions encoded in the response.
+
.. method:: public_bytes(encoding)
:param encoding: The encoding to use. Only
diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst
index b2278d5..a46c5d6 100644
--- a/docs/x509/reference.rst
+++ b/docs/x509/reference.rst
@@ -22,22 +22,20 @@
pem_req_data = b"""
-----BEGIN CERTIFICATE REQUEST-----
- MIIC0zCCAbsCAQAwWTELMAkGA1UEBhMCVVMxETAPBgNVBAgMCElsbGlub2lzMRAw
- DgYDVQQHDAdDaGljYWdvMREwDwYDVQQKDAhyNTA5IExMQzESMBAGA1UEAwwJaGVs
- bG8uY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqhZx+Mo9VRd9
- vsnWWa6NBCws21rZ0+1B/JGgB4hDsZS7iDE4Bj5z4idheFRtl8bBbdjPknq7BfoF
- 8v15Zq/Zv7i2xMSDL+LUrTBZezRd4bRTGqCm6YJ5EYkhqdcqeZleHCFImguHoq1J
- Fh0+kObQrTHXw3ZP57a3o1IvyIUA3nNoCBL0QQhwBXaDXOojMKNR+bqB5ve8GS1y
- Elr0AM/+cJsfaIahNQUgFKx3Eu3GeEOMKYOAG1lycgdQdmTUybLrT3U7vkClTseM
- xHg1r5En7ALjONIhqRuq3rddYahrP8HXozb3zUy3cJ7P6IeaosuvNzvMXOX9P6HD
- Ha9urDAJ1wIDAQABoDUwMwYJKoZIhvcNAQkOMSYwJDAiBgNVHREEGzAZggl3b3Js
- ZC5jb22CDHdoYXRldmVyLmNvbTANBgkqhkiG9w0BAQUFAAOCAQEAS4Ro6h+z52SK
- YSLCYARpnEu/rmh4jdqndt8naqcNb6uLx9mlKZ2W9on9XDjnSdQD9q+ZP5aZfESw
- R0+rJhW9ZrNa/g1pt6M24ihclHYDAxYMWxT1z/TXXGM3TmZZ6gfYlNE1kkBuODHa
- UYsR/1Ht1E1EsmmUimt2n+zQR2K8T9Coa+boaUW/GsTEuz1aaJAkj5ZvTDiIhRG4
- AOCqFZOLAQmCCNgJnnspD9hDz/Ons085LF5wnYjN4/Nsk5tS6AGs3xjZ3jPoOGGn
- 82WQ9m4dBGoVDZXsobVTaN592JEYwN5iu72zRn7Einb4V4H5y3yD2dD4yWPlt4pk
- 5wFkeYsZEA==
+ MIICcDCCAVgCAQAwDTELMAkGA1UEBhMCVVMwggEiMA0GCSqGSIb3DQEBAQUAA4IB
+ DwAwggEKAoIBAQCb+ec0zYAYLzk/MDdDJYvzdvEO2ZUrBYM6z1r8NedwpJfxUWqC
+ hvK1cpc9EbQeCwS1eooTIGoNveeCrwL+pWdmf1sh6gz7SsxdN/07nyhSM8M6Xkec
+ +tGrjyi1H/N1afwWXox3WcvBNbxu3Df5RKLDb0yt9aqhmJylbl/tbvgJesXymwmp
+ Rc1vXL0fOedUtuAJ3xQ15M0pgLF8qDn4lySJz25x76pMYPeN5/a7x+SR/jj81kep
+ VaVpuh/2hePV5uwUX3uWoj5sAkrBCifi4NPge0Npd6KeKVvXytLOymH/4+WvV719
+ wCO+MyrkhpdHSakJDTIaQIxsqVeVVKdPLAPJAgMBAAGgHjAcBgkqhkiG9w0BCQcx
+ DwwNY2hhbGxlbmdlIG1lITANBgkqhkiG9w0BAQsFAAOCAQEAMmgeSa8szbjPFD/4
+ vcPBr/vBEROFGgL8mX3o5pF9gpr7nRjhLKBkgJvlRm6Ma3Xvdfc/r5Hp2ZBTA7sZ
+ ZYhyeezGfCQN/Qhda1v+sCwG58IjvGfCSS7Y5tGlEBQ4MDf0Q7PYPSxaNUEBH7vo
+ +M7U+nFuNSmyWlt6SFBSkohZkWoVSGx3KsAO+SAHYZ7JtqsAS/dm7Dflp8KxeDg7
+ wzGBDQRpGF4CpI1VQjGSJQXSEdD+J7mtvBEOD34abRfV6zOUGzOOo3NWE6wNpYgt
+ 0A7gVlzSYpdwqjBdvACfXR2r/mu+4KkAvYh8WwCiTcYgGjl2pT1bO4hEmcJ0RSWy
+ /fGD8Q==
-----END CERTIFICATE REQUEST-----
""".strip()
@@ -151,7 +149,7 @@
Loading Certificates
~~~~~~~~~~~~~~~~~~~~
-.. function:: load_pem_x509_certificate(data, backend)
+.. function:: load_pem_x509_certificate(data, backend=None)
.. versionadded:: 0.7
@@ -161,7 +159,7 @@
:param bytes data: The PEM encoded certificate data.
- :param backend: A backend supporting the
+ :param backend: An optional backend supporting the
:class:`~cryptography.hazmat.backends.interfaces.X509Backend`
interface.
@@ -170,12 +168,11 @@
.. doctest::
>>> from cryptography import x509
- >>> from cryptography.hazmat.backends import default_backend
- >>> cert = x509.load_pem_x509_certificate(pem_data, default_backend())
+ >>> cert = x509.load_pem_x509_certificate(pem_data)
>>> cert.serial_number
2
-.. function:: load_der_x509_certificate(data, backend)
+.. function:: load_der_x509_certificate(data, backend=None)
.. versionadded:: 0.7
@@ -185,7 +182,7 @@
:param bytes data: The DER encoded certificate data.
- :param backend: A backend supporting the
+ :param backend: An optional backend supporting the
:class:`~cryptography.hazmat.backends.interfaces.X509Backend`
interface.
@@ -194,7 +191,7 @@
Loading Certificate Revocation Lists
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.. function:: load_pem_x509_crl(data, backend)
+.. function:: load_pem_x509_crl(data, backend=None)
.. versionadded:: 1.1
@@ -204,7 +201,7 @@
:param bytes data: The PEM encoded request data.
- :param backend: A backend supporting the
+ :param backend: An optional backend supporting the
:class:`~cryptography.hazmat.backends.interfaces.X509Backend`
interface.
@@ -214,13 +211,12 @@
.. doctest::
>>> from cryptography import x509
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives import hashes
- >>> crl = x509.load_pem_x509_crl(pem_crl_data, default_backend())
+ >>> crl = x509.load_pem_x509_crl(pem_crl_data)
>>> isinstance(crl.signature_hash_algorithm, hashes.SHA256)
True
-.. function:: load_der_x509_crl(data, backend)
+.. function:: load_der_x509_crl(data, backend=None)
.. versionadded:: 1.1
@@ -229,7 +225,7 @@
:param bytes data: The DER encoded request data.
- :param backend: A backend supporting the
+ :param backend: An optional backend supporting the
:class:`~cryptography.hazmat.backends.interfaces.X509Backend`
interface.
@@ -239,7 +235,7 @@
Loading Certificate Signing Requests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.. function:: load_pem_x509_csr(data, backend)
+.. function:: load_pem_x509_csr(data, backend=None)
.. versionadded:: 0.9
@@ -250,7 +246,7 @@
:param bytes data: The PEM encoded request data.
- :param backend: A backend supporting the
+ :param backend: An optional backend supporting the
:class:`~cryptography.hazmat.backends.interfaces.X509Backend`
interface.
@@ -260,13 +256,12 @@
.. doctest::
>>> from cryptography import x509
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives import hashes
- >>> csr = x509.load_pem_x509_csr(pem_req_data, default_backend())
- >>> isinstance(csr.signature_hash_algorithm, hashes.SHA1)
+ >>> csr = x509.load_pem_x509_csr(pem_req_data)
+ >>> isinstance(csr.signature_hash_algorithm, hashes.SHA256)
True
-.. function:: load_der_x509_csr(data, backend)
+.. function:: load_der_x509_csr(data, backend=None)
.. versionadded:: 0.9
@@ -275,7 +270,7 @@
:param bytes data: The DER encoded request data.
- :param backend: A backend supporting the
+ :param backend: An optional backend supporting the
:class:`~cryptography.hazmat.backends.interfaces.X509Backend`
interface.
@@ -335,10 +330,12 @@
The public key associated with the certificate.
- :returns:
- :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey` or
- :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey` or
- :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`
+ :returns: One of
+ :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`,
+ :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey`,
+ :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`,
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PublicKey` or
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed448.Ed448PublicKey`
.. doctest::
@@ -393,7 +390,10 @@
Returns the
:class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` which
- was used in signing this certificate.
+ was used in signing this certificate. Can be ``None`` if signature
+ did not use separate hash
+ (:attr:`~cryptography.x509.oid.SignatureAlgorithmOID.ED25519`,
+ :attr:`~cryptography.x509.oid.SignatureAlgorithmOID.ED448`).
.. doctest::
@@ -429,16 +429,13 @@
:raises cryptography.x509.UnsupportedGeneralNameType: If an extension
contains a general name that is not supported.
- :raises UnicodeError: If an extension contains IDNA encoding that is
- invalid or not compliant with IDNA 2008.
-
.. doctest::
>>> for ext in cert.extensions:
... print(ext)
<Extension(oid=<ObjectIdentifier(oid=2.5.29.35, name=authorityKeyIdentifier)>, critical=False, value=<AuthorityKeyIdentifier(key_identifier=b'\xe4}_\xd1\\\x95\x86\x08,\x05\xae\xbeu\xb6e\xa7\xd9]\xa8f', authority_cert_issuer=None, authority_cert_serial_number=None)>)>
<Extension(oid=<ObjectIdentifier(oid=2.5.29.14, name=subjectKeyIdentifier)>, critical=False, value=<SubjectKeyIdentifier(digest=b'X\x01\x84$\x1b\xbc+R\x94J=\xa5\x10r\x14Q\xf5\xaf:\xc9')>)>
- <Extension(oid=<ObjectIdentifier(oid=2.5.29.15, name=keyUsage)>, critical=True, value=<KeyUsage(digital_signature=False, content_commitment=False, key_encipherment=False, data_encipherment=False, key_agreement=False, key_cert_sign=True, crl_sign=True, encipher_only=None, decipher_only=None)>)>
+ <Extension(oid=<ObjectIdentifier(oid=2.5.29.15, name=keyUsage)>, critical=True, value=<KeyUsage(digital_signature=False, content_commitment=False, key_encipherment=False, data_encipherment=False, key_agreement=False, key_cert_sign=True, crl_sign=True, encipher_only=False, decipher_only=False)>)>
<Extension(oid=<ObjectIdentifier(oid=2.5.29.32, name=certificatePolicies)>, critical=False, value=<CertificatePolicies([<PolicyInformation(policy_identifier=<ObjectIdentifier(oid=2.16.840.1.101.3.2.1.48.1, name=Unknown OID)>, policy_qualifiers=None)>])>)>
<Extension(oid=<ObjectIdentifier(oid=2.5.29.19, name=basicConstraints)>, critical=True, value=<BasicConstraints(ca=True, path_length=None)>)>
@@ -474,8 +471,8 @@
>>> from cryptography.hazmat.primitives.serialization import load_pem_public_key
>>> from cryptography.hazmat.primitives.asymmetric import padding
- >>> issuer_public_key = load_pem_public_key(pem_issuer_public_key, default_backend())
- >>> cert_to_check = x509.load_pem_x509_certificate(pem_data_to_check, default_backend())
+ >>> issuer_public_key = load_pem_public_key(pem_issuer_public_key)
+ >>> cert_to_check = x509.load_pem_x509_certificate(pem_data_to_check)
>>> issuer_public_key.verify(
... cert_to_check.signature,
... cert_to_check.tbs_certificate_bytes,
@@ -551,7 +548,10 @@
Returns the
:class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` which
- was used in signing this CRL.
+ was used in signing this CRL. Can be ``None`` if signature
+ did not use separate hash
+ (:attr:`~cryptography.x509.oid.SignatureAlgorithmOID.ED25519`,
+ :attr:`~cryptography.x509.oid.SignatureAlgorithmOID.ED448`).
.. doctest::
@@ -601,7 +601,7 @@
:type: :class:`datetime.datetime`
- A naïve datetime representing when the this CRL was last updated.
+ A naïve datetime representing when this CRL was last updated.
.. doctest::
@@ -668,7 +668,6 @@
.. doctest::
>>> from cryptography import x509
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives import hashes
>>> from cryptography.hazmat.primitives.asymmetric import rsa
>>> from cryptography.x509.oid import NameOID
@@ -677,7 +676,6 @@
>>> private_key = rsa.generate_private_key(
... public_exponent=65537,
... key_size=2048,
- ... backend=default_backend()
... )
>>> public_key = private_key.public_key()
>>> builder = x509.CertificateBuilder()
@@ -702,7 +700,6 @@
... )
>>> certificate = builder.sign(
... private_key=private_key, algorithm=hashes.SHA256(),
- ... backend=default_backend()
... )
>>> isinstance(certificate, x509.Certificate)
True
@@ -727,8 +724,10 @@
:param public_key: The subject's public key. This can be one of
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`,
- :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey` or
- :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`
+ :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey`,
+ :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`,
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PublicKey` or
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed448.Ed448PublicKey`.
.. method:: serial_number(serial_number)
@@ -775,21 +774,30 @@
:param critical: Set to ``True`` if the extension must be understood and
handled by whoever reads the certificate.
- .. method:: sign(private_key, algorithm, backend)
+ .. method:: sign(private_key, algorithm, backend=None)
Sign the certificate using the CA's private key.
:param private_key: The
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`,
- :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey` or
- :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey`
+ :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey`,
+ :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey`,
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey` or
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed448.Ed448PrivateKey`
that will be used to sign the certificate.
:param algorithm: The
:class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` that
- will be used to generate the signature.
+ will be used to generate the signature. This must be ``None`` if
+ the ``private_key`` is an
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey`
+ or an
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed448.Ed448PrivateKey`
+ and an instance of a
+ :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`
+ otherwise.
- :param backend: Backend that will be used to build the certificate.
+ :param backend: An optional backend used to build the certificate.
Must support the
:class:`~cryptography.hazmat.backends.interfaces.X509Backend`
interface.
@@ -808,10 +816,12 @@
The public key associated with the request.
- :returns:
- :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey` or
- :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey` or
- :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`
+ :returns: One of
+ :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`,
+ :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey`,
+ :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`,
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PublicKey` or
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed448.Ed448PublicKey`.
.. doctest::
@@ -832,12 +842,15 @@
Returns the
:class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` which
- was used in signing this request.
+ was used in signing this request. Can be ``None`` if signature
+ did not use separate hash
+ (:attr:`~cryptography.x509.oid.SignatureAlgorithmOID.ED25519`,
+ :attr:`~cryptography.x509.oid.SignatureAlgorithmOID.ED448`).
.. doctest::
>>> from cryptography.hazmat.primitives import hashes
- >>> isinstance(csr.signature_hash_algorithm, hashes.SHA1)
+ >>> isinstance(csr.signature_hash_algorithm, hashes.SHA256)
True
.. attribute:: signature_algorithm_oid
@@ -853,7 +866,7 @@
.. doctest::
>>> csr.signature_algorithm_oid
- <ObjectIdentifier(oid=1.2.840.113549.1.1.5, name=sha1WithRSAEncryption)>
+ <ObjectIdentifier(oid=1.2.840.113549.1.1.11, name=sha256WithRSAEncryption)>
.. attribute:: extensions
@@ -867,9 +880,17 @@
:raises cryptography.x509.UnsupportedGeneralNameType: If an extension
contains a general name that is not supported.
- :raises UnicodeError: If an extension contains IDNA encoding that is
- invalid or not compliant with IDNA 2008.
+ .. method:: get_attribute_for_oid(oid)
+ .. versionadded:: 3.0
+
+ :param oid: An :class:`ObjectIdentifier` instance.
+
+ :returns: The bytes value of the attribute or an exception if not
+ found.
+
+ :raises cryptography.x509.AttributeNotFound: If the request does
+ not have the attribute requested.
.. method:: public_bytes(encoding)
@@ -918,7 +939,6 @@
.. doctest::
>>> from cryptography import x509
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives import hashes
>>> from cryptography.hazmat.primitives.asymmetric import rsa
>>> from cryptography.x509.oid import NameOID
@@ -927,7 +947,6 @@
>>> private_key = rsa.generate_private_key(
... public_exponent=65537,
... key_size=2048,
- ... backend=default_backend()
... )
>>> builder = x509.CertificateRevocationListBuilder()
>>> builder = builder.issuer_name(x509.Name([
@@ -939,11 +958,10 @@
... 333
... ).revocation_date(
... datetime.datetime.today()
- ... ).build(default_backend())
+ ... ).build()
>>> builder = builder.add_revoked_certificate(revoked_cert)
>>> crl = builder.sign(
... private_key=private_key, algorithm=hashes.SHA256(),
- ... backend=default_backend()
... )
>>> len(crl)
1
@@ -994,21 +1012,30 @@
obtained from an existing CRL or created with
:class:`~cryptography.x509.RevokedCertificateBuilder`.
- .. method:: sign(private_key, algorithm, backend)
+ .. method:: sign(private_key, algorithm, backend=None)
Sign this CRL using the CA's private key.
:param private_key: The
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`,
- :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey` or
- :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey`
+ :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey`,
+ :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey`,
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey` or
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed448.Ed448PrivateKey`
that will be used to sign the certificate.
:param algorithm: The
:class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` that
will be used to generate the signature.
+ This must be ``None`` if the ``private_key`` is an
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey`
+ or an
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed448.Ed448PrivateKey`
+ and an instance of a
+ :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`
+ otherwise.
- :param backend: Backend that will be used to build the CRL.
+ :param backend: An optional backend used to build the CRL.
Must support the
:class:`~cryptography.hazmat.backends.interfaces.X509Backend`
interface.
@@ -1071,12 +1098,11 @@
.. doctest::
>>> from cryptography import x509
- >>> from cryptography.hazmat.backends import default_backend
>>> import datetime
>>> builder = x509.RevokedCertificateBuilder()
>>> builder = builder.revocation_date(datetime.datetime.today())
>>> builder = builder.serial_number(3333)
- >>> revoked_certificate = builder.build(default_backend())
+ >>> revoked_certificate = builder.build()
>>> isinstance(revoked_certificate, x509.RevokedCertificate)
True
@@ -1104,11 +1130,11 @@
:param critical: Set to ``True`` if the extension must be understood and
handled.
- .. method:: build(backend)
+ .. method:: build(backend=None)
Create a revoked certificate object using the provided backend.
- :param backend: Backend that will be used to build the revoked
+ :param backend: An optional backend used to build the revoked
certificate. Must support the
:class:`~cryptography.hazmat.backends.interfaces.X509Backend`
interface.
@@ -1125,14 +1151,12 @@
.. doctest::
>>> from cryptography import x509
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives import hashes
>>> from cryptography.hazmat.primitives.asymmetric import rsa
- >>> from cryptography.x509.oid import NameOID
+ >>> from cryptography.x509.oid import AttributeOID, NameOID
>>> private_key = rsa.generate_private_key(
... public_exponent=65537,
... key_size=2048,
- ... backend=default_backend()
... )
>>> builder = x509.CertificateSigningRequestBuilder()
>>> builder = builder.subject_name(x509.Name([
@@ -1141,8 +1165,11 @@
>>> builder = builder.add_extension(
... x509.BasicConstraints(ca=False, path_length=None), critical=True,
... )
+ >>> builder = builder.add_attribute(
+ ... AttributeOID.CHALLENGE_PASSWORD, b"changeit"
+ ... )
>>> request = builder.sign(
- ... private_key, hashes.SHA256(), default_backend()
+ ... private_key, hashes.SHA256()
... )
>>> isinstance(request, x509.CertificateSigningRequest)
True
@@ -1163,17 +1190,29 @@
:returns: A new
:class:`~cryptography.x509.CertificateSigningRequestBuilder`.
- .. method:: sign(private_key, algorithm, backend)
+ .. method:: add_attribute(oid, value)
- :param backend: Backend that will be used to sign the request.
+ .. versionadded:: 3.0
+
+ :param oid: An :class:`ObjectIdentifier` instance.
+ :param value: The value of the attribute.
+ :type value: bytes
+ :returns: A new
+ :class:`~cryptography.x509.CertificateSigningRequestBuilder`.
+
+ .. method:: sign(private_key, algorithm, backend=None)
+
+ :param backend: An optional backend used to sign the request.
Must support the
:class:`~cryptography.hazmat.backends.interfaces.X509Backend`
interface.
:param private_key: The
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`,
- :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey` or
- :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey`
+ :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey`,
+ :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey`,
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey` or
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed448.Ed448PrivateKey`
that will be used to sign the request. When the request is
signed by a certificate authority, the private key's associated
public key will be stored in the resulting certificate.
@@ -1181,6 +1220,13 @@
:param algorithm: The
:class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`
that will be used to generate the request signature.
+ This must be ``None`` if the ``private_key`` is an
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey`
+ or an
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed448.Ed448PrivateKey`
+ and an instance of a
+ :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`
+ otherwise.
:returns: A new
:class:`~cryptography.x509.CertificateSigningRequest`.
@@ -1236,11 +1282,11 @@
>>> cert.subject.get_attributes_for_oid(NameOID.COMMON_NAME)
[<NameAttribute(oid=<ObjectIdentifier(oid=2.5.4.3, name=commonName)>, value='Good CA')>]
- .. method:: public_bytes(backend)
+ .. method:: public_bytes(backend=None)
.. versionadded:: 1.6
- :param backend: A backend supporting the
+ :param backend: An optional backend supporting the
:class:`~cryptography.hazmat.backends.interfaces.X509Backend`
interface.
@@ -1348,17 +1394,10 @@
.. versionadded:: 0.9
- .. versionchanged:: 2.1
+ .. versionchanged:: 3.1
- .. warning::
-
- Starting with version 2.1 :term:`U-label` input is deprecated. If
- passing an internationalized domain name (IDN) you should first IDNA
- encode the value and then pass the result as a string. Accessing
- ``value`` will return the :term:`A-label` encoded form even if you pass
- a U-label. This breaks backwards compatibility, but only for
- internationalized domain names.
-
+ :term:`U-label` support has been removed. Encode them to
+ :term:`A-label` before use.
This corresponds to an email address. For example, ``user@example.com``.
@@ -1366,6 +1405,8 @@
internationalized domain name then it must be encoded to an
:term:`A-label` string before being passed.
+ :raises ValueError: If the provided string is not an :term:`A-label`.
+
.. attribute:: value
:type: :term:`text`
@@ -1374,16 +1415,10 @@
.. versionadded:: 0.9
- .. versionchanged:: 2.1
+ .. versionchanged:: 3.1
- .. warning::
-
- Starting with version 2.1 :term:`U-label` input is deprecated. If
- passing an internationalized domain name (IDN) you should first IDNA
- encode the value and then pass the result as a string. Accessing
- ``value`` will return the :term:`A-label` encoded form even if you pass
- a U-label. This breaks backwards compatibility, but only for
- internationalized domain names.
+ :term:`U-label` support has been removed. Encode them to
+ :term:`A-label` before use.
This corresponds to a domain name. For example, ``cryptography.io``.
@@ -1391,6 +1426,8 @@
name then it must be encoded to an :term:`A-label` string before being
passed.
+ :raises ValueError: If the provided string is not an :term:`A-label`.
+
:type: :term:`text`
.. attribute:: value
@@ -1411,16 +1448,10 @@
.. versionadded:: 0.9
- .. versionchanged:: 2.1
+ .. versionchanged:: 3.1
- .. warning::
-
- Starting with version 2.1 :term:`U-label` input is deprecated. If
- passing an internationalized domain name (IDN) you should first IDNA
- encode the value and then pass the result as a string. Accessing
- ``value`` will return the :term:`A-label` encoded form even if you pass
- a U-label. This breaks backwards compatibility, but only for
- internationalized domain names.
+ :term:`U-label` support has been removed. Encode them to
+ :term:`A-label` before use.
This corresponds to a uniform resource identifier. For example,
``https://cryptography.io``.
@@ -1429,6 +1460,8 @@
name then it must be encoded to an :term:`A-label` string before
being passed.
+ :raises ValueError: If the provided string is not an :term:`A-label`.
+
.. attribute:: value
:type: :term:`text`
@@ -1821,7 +1854,7 @@
:type: A list of :class:`GeneralName` instances or None
- The :class:`Name` of the issuer's issuer.
+ The :class:`GeneralName` (one or multiple) of the issuer's issuer.
.. attribute:: authority_cert_serial_number
@@ -1853,17 +1886,16 @@
section 4.2.1.2.
:param public_key: One of
- :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`
- ,
- :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey`
- , or
- :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`.
+ :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`,
+ :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey`,
+ :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`,
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PublicKey` or
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed448.Ed448PublicKey`.
.. doctest::
>>> from cryptography import x509
- >>> from cryptography.hazmat.backends import default_backend
- >>> issuer_cert = x509.load_pem_x509_certificate(pem_data, default_backend())
+ >>> issuer_cert = x509.load_pem_x509_certificate(pem_data)
>>> x509.AuthorityKeyIdentifier.from_issuer_public_key(issuer_cert.public_key())
<AuthorityKeyIdentifier(key_identifier=b'X\x01\x84$\x1b\xbc+R\x94J=\xa5\x10r\x14Q\xf5\xaf:\xc9', authority_cert_issuer=None, authority_cert_serial_number=None)>
@@ -1892,10 +1924,9 @@
.. doctest::
>>> from cryptography import x509
- >>> from cryptography.hazmat.backends import default_backend
- >>> issuer_cert = x509.load_pem_x509_certificate(pem_data, default_backend())
- >>> ski = issuer_cert.extensions.get_extension_for_class(x509.SubjectKeyIdentifier)
- >>> x509.AuthorityKeyIdentifier.from_issuer_subject_key_identifier(ski)
+ >>> issuer_cert = x509.load_pem_x509_certificate(pem_data)
+ >>> ski_ext = issuer_cert.extensions.get_extension_for_class(x509.SubjectKeyIdentifier)
+ >>> x509.AuthorityKeyIdentifier.from_issuer_subject_key_identifier(ski_ext.value)
<AuthorityKeyIdentifier(key_identifier=b'X\x01\x84$\x1b\xbc+R\x94J=\xa5\x10r\x14Q\xf5\xaf:\xc9', authority_cert_issuer=None, authority_cert_serial_number=None)>
.. class:: SubjectKeyIdentifier(digest)
@@ -1931,19 +1962,18 @@
recommendation in :rfc:`5280` section 4.2.1.2.
:param public_key: One of
- :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`
- ,
- :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey`
- , or
- :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`.
+ :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`,
+ :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey`,
+ :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`,
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PublicKey` or
+ :class:`~cryptography.hazmat.primitives.asymmetric.ed448.Ed448PublicKey`.
.. doctest::
>>> from cryptography import x509
- >>> from cryptography.hazmat.backends import default_backend
- >>> csr = x509.load_pem_x509_csr(pem_req_data, default_backend())
+ >>> csr = x509.load_pem_x509_csr(pem_req_data)
>>> x509.SubjectKeyIdentifier.from_public_key(csr.public_key())
- <SubjectKeyIdentifier(digest=b'\xdb\xaa\xf0\x06\x11\xdbD\xfe\xbf\x93\x03\x8av\x88WP7\xa6\x91\xf7')>
+ <SubjectKeyIdentifier(digest=b'\x8c"\x98\xe2\xb5\xbf]\xe8*2\xf8\xd2\'?\x00\xd2\xc7#\xe4c')>
.. class:: SubjectAlternativeName(general_names)
@@ -1976,9 +2006,8 @@
.. doctest::
>>> from cryptography import x509
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives import hashes
- >>> cert = x509.load_pem_x509_certificate(cryptography_cert_pem, default_backend())
+ >>> cert = x509.load_pem_x509_certificate(cryptography_cert_pem)
>>> # Get the subjectAltName extension from the certificate
>>> ext = cert.extensions.get_extension_for_oid(ExtensionOID.SUBJECT_ALTERNATIVE_NAME)
>>> # Get the dNSName entries from the SAN extension
@@ -2057,6 +2086,33 @@
Returns :attr:`~cryptography.x509.oid.ExtensionOID.PRECERT_POISON`.
+.. class:: SignedCertificateTimestamps(scts)
+
+ .. versionadded:: 3.0
+
+ This extension contains
+ :class:`~cryptography.x509.certificate_transparency.SignedCertificateTimestamp`
+ instances. These can be used to verify that the certificate is included
+ in a public Certificate Transparency log. This extension is only found
+ in OCSP responses. For SCTs in an X.509 certificate see
+ :class:`~cryptography.x509.PrecertificateSignedCertificateTimestamps`.
+
+ It is an iterable containing one or more
+ :class:`~cryptography.x509.certificate_transparency.SignedCertificateTimestamp`
+ objects.
+
+ :param list scts: A ``list`` of
+ :class:`~cryptography.x509.certificate_transparency.SignedCertificateTimestamp`
+ objects.
+
+ .. attribute:: oid
+
+ :type: :class:`ObjectIdentifier`
+
+ Returns
+ :attr:`~cryptography.x509.oid.ExtensionOID.SIGNED_CERTIFICATE_TIMESTAMPS`.
+
+
.. class:: DeltaCRLIndicator(crl_number)
.. versionadded:: 2.1
@@ -2104,6 +2160,29 @@
:attr:`~cryptography.x509.oid.ExtensionOID.AUTHORITY_INFORMATION_ACCESS`.
+.. class:: SubjectInformationAccess(descriptions)
+
+ .. versionadded:: 3.0
+
+ The subject information access extension indicates how to access
+ information and services for the subject of the certificate in which
+ the extension appears. When the subject is a CA, information and
+ services may include certificate validation services and CA policy
+ data. When the subject is an end entity, the information describes
+ the type of services offered and how to access them. It is an iterable,
+ containing one or more :class:`~cryptography.x509.AccessDescription`
+ instances.
+
+ :param list descriptions: A list of :class:`AccessDescription` objects.
+
+ .. attribute:: oid
+
+ :type: :class:`ObjectIdentifier`
+
+ Returns
+ :attr:`~cryptography.x509.oid.ExtensionOID.SUBJECT_INFORMATION_ACCESS`.
+
+
.. class:: AccessDescription(access_method, access_location)
.. versionadded:: 0.9
@@ -2113,16 +2192,23 @@
:type: :class:`ObjectIdentifier`
The access method defines what the ``access_location`` means. It must
- be either
+ be
:attr:`~cryptography.x509.oid.AuthorityInformationAccessOID.OCSP` or
- :attr:`~cryptography.x509.oid.AuthorityInformationAccessOID.CA_ISSUERS`.
+ :attr:`~cryptography.x509.oid.AuthorityInformationAccessOID.CA_ISSUERS`
+ when used with :class:`~cryptography.x509.AuthorityInformationAccess`
+ or
+ :attr:`~cryptography.x509.oid.SubjectInformationAccessOID.CA_REPOSITORY`
+ when used with :class:`~cryptography.x509.SubjectInformationAccess`.
+
If it is
:attr:`~cryptography.x509.oid.AuthorityInformationAccessOID.OCSP`
the access location will be where to obtain OCSP
information for the certificate. If it is
:attr:`~cryptography.x509.oid.AuthorityInformationAccessOID.CA_ISSUERS`
the access location will provide additional information about the
- issuing certificate.
+ issuing certificate. Finally, if it is
+ :attr:`~cryptography.x509.oid.SubjectInformationAccessOID.CA_REPOSITORY`
+ the access location will be the location of the CA's repository.
.. attribute:: access_location
@@ -2418,7 +2504,9 @@
.. versionadded:: 1.2
A generic extension class used to hold the raw value of extensions that
- ``cryptography`` does not know how to parse.
+ ``cryptography`` does not know how to parse. This can also be used when
+ creating new certificates, CRLs, or OCSP requests and responses to encode
+ extensions that ``cryptography`` does not know how to generate.
.. attribute:: oid
@@ -2441,6 +2529,18 @@
:param list policies: A list of :class:`PolicyInformation` instances.
+ As an example of how ``CertificatePolicies`` might be used, if you wanted
+ to check if a certificated contained the CAB Forum's "domain-validated"
+ policy, you might write code like:
+
+ .. code-block:: python
+
+ def contains_domain_validated(policies):
+ return any(
+ policy.oid.dotted_string == "2.23.140.1.2.1"
+ for policy in policies
+ )
+
.. attribute:: oid
.. versionadded:: 1.0
@@ -2752,6 +2852,12 @@
Corresponds to the dotted string ``"2.5.4.17"``.
+ .. attribute:: UNSTRUCTURED_NAME
+
+ .. versionadded:: 3.0
+
+ Corresponds to the dotted string ``"1.2.840.113549.1.9.2"``.
+
.. class:: SignatureAlgorithmOID
@@ -2836,6 +2942,20 @@
Corresponds to the dotted string ``"2.16.840.1.101.3.4.3.2"``. This is
a SHA256 digest signed by a DSA key.
+ .. attribute:: ED25519
+
+ .. versionadded:: 2.8
+
+ Corresponds to the dotted string ``"1.3.101.112"``. This is a signature
+ using an ed25519 key.
+
+ .. attribute:: ED448
+
+ .. versionadded:: 2.8
+
+ Corresponds to the dotted string ``"1.3.101.113"``. This is a signature
+ using an ed448 key.
+
.. class:: ExtendedKeyUsageOID
@@ -2878,7 +2998,12 @@
.. versionadded:: 2.0
Corresponds to the dotted string ``"2.5.29.37.0"``. This is used to
- denote that a certificate may be used for _any_ purposes.
+ denote that a certificate may be used for _any_ purposes. However,
+ :rfc:`5280` additionally notes that applications that require the
+ presence of a particular purpose _MAY_ reject certificates that include
+ the ``anyExtendedKeyUsage`` OID but not the particular OID expected for
+ the application. Therefore, the presence of this OID does not mean a
+ given application will accept the certificate for all purposes.
.. class:: AuthorityInformationAccessOID
@@ -2898,6 +3023,17 @@
:class:`~cryptography.x509.AccessDescription` objects.
+.. class:: SubjectInformationAccessOID
+
+ .. versionadded:: 3.0
+
+ .. attribute:: CA_REPOSITORY
+
+ Corresponds to the dotted string ``"1.3.6.1.5.5.7.48.5"``. Used as the
+ identifier for CA repository data in
+ :class:`~cryptography.x509.AccessDescription` objects.
+
+
.. class:: CertificatePoliciesOID
.. versionadded:: 1.0
@@ -2975,6 +3111,14 @@
for the :class:`~cryptography.x509.AuthorityInformationAccess` extension
type.
+ .. attribute:: SUBJECT_INFORMATION_ACCESS
+
+ .. versionadded:: 3.0
+
+ Corresponds to the dotted string ``"1.3.6.1.5.5.7.1.11"``. The
+ identifier for the :class:`~cryptography.x509.SubjectInformationAccess`
+ extension type.
+
.. attribute:: INHIBIT_ANY_POLICY
Corresponds to the dotted string ``"2.5.29.54"``. The identifier
@@ -3018,6 +3162,12 @@
Corresponds to the dotted string ``"1.3.6.1.4.1.11129.2.4.3"``.
+ .. attribute:: SIGNED_CERTIFICATE_TIMESTAMPS
+
+ .. versionadded:: 3.0
+
+ Corresponds to the dotted string ``"1.3.6.1.4.1.11129.2.4.5"``.
+
.. attribute:: POLICY_CONSTRAINTS
Corresponds to the dotted string ``"2.5.29.36"``. The identifier for the
@@ -3060,6 +3210,19 @@
Corresponds to the dotted string ``"1.3.6.1.5.5.7.48.1.2"``.
+
+.. class:: AttributeOID
+
+ .. versionadded:: 3.0
+
+ .. attribute:: CHALLENGE_PASSWORD
+
+ Corresponds to the dotted string ``"1.2.840.113549.1.9.7"``.
+
+ .. attribute:: UNSTRUCTURED_NAME
+
+ Corresponds to the dotted string ``"1.2.840.113549.1.9.2"``.
+
Helper Functions
~~~~~~~~~~~~~~~~
.. currentmodule:: cryptography.x509
@@ -3107,6 +3270,18 @@
Returns the OID.
+.. class:: AttributeNotFound
+
+ This is raised when calling
+ :meth:`CertificateSigningRequest.get_attribute_for_oid` with
+ an attribute OID that is not present in the request.
+
+ .. attribute:: oid
+
+ :type: :class:`ObjectIdentifier`
+
+ Returns the OID.
+
.. class:: UnsupportedGeneralNameType
This is raised when a certificate contains an unsupported general name
diff --git a/docs/x509/tutorial.rst b/docs/x509/tutorial.rst
index d34b350..f5ca416 100644
--- a/docs/x509/tutorial.rst
+++ b/docs/x509/tutorial.rst
@@ -27,14 +27,12 @@
.. code-block:: pycon
- >>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives import serialization
>>> from cryptography.hazmat.primitives.asymmetric import rsa
>>> # Generate our key
>>> key = rsa.generate_private_key(
... public_exponent=65537,
... key_size=2048,
- ... backend=default_backend()
... )
>>> # Write our key to disk for safe keeping
>>> with open("path/to/store/key.pem", "wb") as f:
@@ -63,7 +61,7 @@
>>> csr = x509.CertificateSigningRequestBuilder().subject_name(x509.Name([
... # Provide various details about who we are.
... x509.NameAttribute(NameOID.COUNTRY_NAME, u"US"),
- ... x509.NameAttribute(NameOID.STATE_OR_PROVINCE_NAME, u"CA"),
+ ... x509.NameAttribute(NameOID.STATE_OR_PROVINCE_NAME, u"California"),
... x509.NameAttribute(NameOID.LOCALITY_NAME, u"San Francisco"),
... x509.NameAttribute(NameOID.ORGANIZATION_NAME, u"My Company"),
... x509.NameAttribute(NameOID.COMMON_NAME, u"mysite.com"),
@@ -76,7 +74,7 @@
... ]),
... critical=False,
... # Sign the CSR with our private key.
- ... ).sign(key, hashes.SHA256(), default_backend())
+ ... ).sign(key, hashes.SHA256())
>>> # Write our CSR out to disk.
>>> with open("path/to/csr.pem", "wb") as f:
... f.write(csr.public_bytes(serialization.Encoding.PEM))
@@ -105,7 +103,6 @@
>>> key = rsa.generate_private_key(
... public_exponent=65537,
... key_size=2048,
- ... backend=default_backend()
... )
>>> # Write our key to disk for safe keeping
>>> with open("path/to/store/key.pem", "wb") as f:
@@ -123,7 +120,7 @@
>>> # subject and issuer are always the same.
>>> subject = issuer = x509.Name([
... x509.NameAttribute(NameOID.COUNTRY_NAME, u"US"),
- ... x509.NameAttribute(NameOID.STATE_OR_PROVINCE_NAME, u"CA"),
+ ... x509.NameAttribute(NameOID.STATE_OR_PROVINCE_NAME, u"California"),
... x509.NameAttribute(NameOID.LOCALITY_NAME, u"San Francisco"),
... x509.NameAttribute(NameOID.ORGANIZATION_NAME, u"My Company"),
... x509.NameAttribute(NameOID.COMMON_NAME, u"mysite.com"),
@@ -145,7 +142,7 @@
... x509.SubjectAlternativeName([x509.DNSName(u"localhost")]),
... critical=False,
... # Sign our certificate with our private key
- ... ).sign(key, hashes.SHA256(), default_backend())
+ ... ).sign(key, hashes.SHA256())
>>> # Write our certificate out to disk.
>>> with open("path/to/certificate.pem", "wb") as f:
... f.write(cert.public_bytes(serialization.Encoding.PEM))