aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/development/custom-vectors/secp256k1.rst32
-rw-r--r--docs/development/custom-vectors/secp256k1/generate_secp256k1.py89
-rw-r--r--docs/development/custom-vectors/secp256k1/verify_secp256k1.py59
-rw-r--r--docs/development/test-vectors.rst21
-rw-r--r--docs/spelling_wordlist.txt1
-rw-r--r--docs/x509.rst100
6 files changed, 297 insertions, 5 deletions
diff --git a/docs/development/custom-vectors/secp256k1.rst b/docs/development/custom-vectors/secp256k1.rst
new file mode 100644
index 00000000..b19bf4e4
--- /dev/null
+++ b/docs/development/custom-vectors/secp256k1.rst
@@ -0,0 +1,32 @@
+SECP256K1 vector creation
+=========================
+
+This page documents the code that was used to generate the SECP256K1 elliptic
+curve test vectors as well as code used to verify them against another
+implementation.
+
+
+Creation
+--------
+
+The vectors are generated using a `pure Python ecdsa`_ implementation. The test
+messages and combinations of algorithms are derived from the NIST vector data.
+
+.. literalinclude:: /development/custom-vectors/secp256k1/generate_secp256k1.py
+
+Download link: :download:`generate_secp256k1.py
+</development/custom-vectors/secp256k1/generate_secp256k1.py>`
+
+
+Verification
+------------
+
+``cryptography`` was modified to support the SECP256K1 curve. Then
+the following python script was run to generate the vector files.
+
+.. literalinclude:: /development/custom-vectors/secp256k1/verify_secp256k1.py
+
+Download link: :download:`verify_secp256k1.py
+</development/custom-vectors/secp256k1/verify_secp256k1.py>`
+
+.. _`pure Python ecdsa`: https://pypi.python.org/pypi/ecdsa
diff --git a/docs/development/custom-vectors/secp256k1/generate_secp256k1.py b/docs/development/custom-vectors/secp256k1/generate_secp256k1.py
new file mode 100644
index 00000000..502a3ff6
--- /dev/null
+++ b/docs/development/custom-vectors/secp256k1/generate_secp256k1.py
@@ -0,0 +1,89 @@
+from __future__ import absolute_import, print_function
+
+import hashlib
+import os
+from binascii import hexlify
+from collections import defaultdict
+
+from ecdsa import SECP256k1, SigningKey
+from ecdsa.util import sigdecode_der, sigencode_der
+
+from cryptography_vectors import open_vector_file
+
+from tests.utils import (
+ load_fips_ecdsa_signing_vectors, load_vectors_from_file
+)
+
+HASHLIB_HASH_TYPES = {
+ "SHA-1": hashlib.sha1,
+ "SHA-224": hashlib.sha224,
+ "SHA-256": hashlib.sha256,
+ "SHA-384": hashlib.sha384,
+ "SHA-512": hashlib.sha512,
+}
+
+
+class TruncatedHash(object):
+ def __init__(self, hasher):
+ self.hasher = hasher
+
+ def __call__(self, data):
+ self.hasher.update(data)
+ return self
+
+ def digest(self):
+ 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'])
+
+ for digest_algorithm, messages in vectors.items():
+ if digest_algorithm not in HASHLIB_HASH_TYPES:
+ continue
+
+ yield ""
+ yield "[K-256,{0}]".format(digest_algorithm)
+ yield ""
+
+ for message in messages:
+ # Make a hash context
+ hash_func = TruncatedHash(HASHLIB_HASH_TYPES[digest_algorithm]())
+
+ # 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)
+
+ r, s = sigdecode_der(signature, None)
+
+ yield "Msg = {0}".format(hexlify(message))
+ yield "d = {0:x}".format(secret_key.privkey.secret_multiplier)
+ yield "Qx = {0:x}".format(public_key.pubkey.point.x())
+ yield "Qy = {0:x}".format(public_key.pubkey.point.y())
+ yield "R = {0:x}".format(r)
+ yield "S = {0:x}".format(s)
+ yield ""
+
+
+def write_file(lines, dest):
+ for line in lines:
+ print(line)
+ print(line, file=dest)
+
+source_path = os.path.join("asymmetric", "ECDSA", "FIPS_186-3", "SigGen.txt")
+dest_path = os.path.join("asymmetric", "ECDSA", "SECP256K1", "SigGen.txt")
+
+fips_vectors = load_vectors_from_file(
+ 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
+ )
diff --git a/docs/development/custom-vectors/secp256k1/verify_secp256k1.py b/docs/development/custom-vectors/secp256k1/verify_secp256k1.py
new file mode 100644
index 00000000..3d2c25b9
--- /dev/null
+++ b/docs/development/custom-vectors/secp256k1/verify_secp256k1.py
@@ -0,0 +1,59 @@
+from __future__ import absolute_import, print_function
+
+import os
+
+from cryptography.hazmat.backends import default_backend
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.primitives.asymmetric.utils import (
+ encode_rfc6979_signature
+)
+
+from tests.utils import (
+ load_fips_ecdsa_signing_vectors, load_vectors_from_file
+)
+
+CRYPTOGRAPHY_HASH_TYPES = {
+ "SHA-1": hashes.SHA1,
+ "SHA-224": hashes.SHA224,
+ "SHA-256": hashes.SHA256,
+ "SHA-384": hashes.SHA384,
+ "SHA-512": hashes.SHA512,
+}
+
+
+def verify_one_vector(vector):
+ digest_algorithm = vector['digest_algorithm']
+ message = vector['message']
+ x = vector['x']
+ y = vector['y']
+ signature = encode_rfc6979_signature(vector['r'], vector['s'])
+
+ numbers = ec.EllipticCurvePublicNumbers(
+ x, y,
+ ec.SECP256K1()
+ )
+
+ key = numbers.public_key(default_backend())
+
+ verifier = key.verifier(
+ signature,
+ ec.ECDSA(CRYPTOGRAPHY_HASH_TYPES[digest_algorithm]())
+ )
+ verifier.update(message)
+ return verifier.verify()
+
+
+def verify_vectors(vectors):
+ for vector in vectors:
+ assert 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
+)
+
+verify_vectors(secp256k1_vectors)
diff --git a/docs/development/test-vectors.rst b/docs/development/test-vectors.rst
index f6eecfec..41531f7b 100644
--- a/docs/development/test-vectors.rst
+++ b/docs/development/test-vectors.rst
@@ -37,9 +37,14 @@ Asymmetric ciphers
Ruby test suite.
-Custom Asymmetric Vectors
+Custom asymmetric vectors
~~~~~~~~~~~~~~~~~~~~~~~~~
+.. toctree::
+ :maxdepth: 1
+
+ custom-vectors/secp256k1
+
* ``asymmetric/PEM_Serialization/ec_private_key.pem`` and
``asymmetric/DER_Serialization/ec_private_key.der`` - Contains an Elliptic
Curve key generated by OpenSSL from the curve ``secp256r1``.
@@ -78,6 +83,7 @@ Custom Asymmetric Vectors
``asymmetric/public/PKCS1/rsa.pub.der`` are PKCS1 conversions of the public
key from ``asymmetric/PKCS8/unenc-rsa-pkcs8.pem`` using PEM and DER encoding.
+
Key exchange
~~~~~~~~~~~~
@@ -160,6 +166,19 @@ Custom X.509 Vectors
containing an inhibit any policy extension with the value 5.
* ``inhibit_any_policy_negative.pem`` - An RSA 2048 bit self-signed certificate
containing an inhibit any policy extension with the value -1.
+* ``authority_key_identifier.pem`` - An RSA 2048 bit self-signed certificate
+ containing an authority key identifier extension with key identifier,
+ authority certificate issuer, and authority certificate serial number fields.
+* ``authority_key_identifier_no_keyid.pem`` - An RSA 2048 bit self-signed
+ certificate containing an authority key identifier extension with authority
+ certificate issuer and authority certificate serial number fields.
+* ``aia_ocsp_ca_issuers.pem`` - An RSA 2048 bit self-signed certificate
+ containing an authority information access extension with two OCSP and one
+ CA issuers entry.
+* ``aia_ocsp.pem`` - An RSA 2048 bit self-signed certificate
+ containing an authority information access extension with an OCSP entry.
+* ``aia_ca_issuers.pem`` - An RSA 2048 bit self-signed certificate
+ containing an authority information access extension with a CA issuers entry.
Custom X.509 Request Vectors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt
index b7c4c6c2..badb500c 100644
--- a/docs/spelling_wordlist.txt
+++ b/docs/spelling_wordlist.txt
@@ -40,6 +40,7 @@ multi
naïve
namespace
namespaces
+online
paddings
pickleable
plaintext
diff --git a/docs/x509.rst b/docs/x509.rst
index 5f36a921..f4ea2a52 100644
--- a/docs/x509.rst
+++ b/docs/x509.rst
@@ -50,6 +50,42 @@ X.509
-----END CERTIFICATE-----
""".strip()
+ cryptography_cert_pem = b"""
+ -----BEGIN CERTIFICATE-----
+ MIIFvTCCBKWgAwIBAgICPyAwDQYJKoZIhvcNAQELBQAwRzELMAkGA1UEBhMCVVMx
+ FjAUBgNVBAoTDUdlb1RydXN0IEluYy4xIDAeBgNVBAMTF1JhcGlkU1NMIFNIQTI1
+ NiBDQSAtIEczMB4XDTE0MTAxNTEyMDkzMloXDTE4MTExNjAxMTUwM1owgZcxEzAR
+ BgNVBAsTCkdUNDg3NDI5NjUxMTAvBgNVBAsTKFNlZSB3d3cucmFwaWRzc2wuY29t
+ L3Jlc291cmNlcy9jcHMgKGMpMTQxLzAtBgNVBAsTJkRvbWFpbiBDb250cm9sIFZh
+ bGlkYXRlZCAtIFJhcGlkU1NMKFIpMRwwGgYDVQQDExN3d3cuY3J5cHRvZ3JhcGh5
+ LmlvMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAom/FebKJIot7Sp3s
+ itG1sicpe3thCssjI+g1JDAS7I3GLVNmbms1DOdIIqwf01gZkzzXBN2+9sOnyRaR
+ PPfCe1jTr3dk2y6rPE559vPa1nZQkhlzlhMhlPyjaT+S7g4Tio4qV2sCBZU01DZJ
+ CaksfohN+5BNVWoJzTbOcrHOEJ+M8B484KlBCiSxqf9cyNQKru4W3bHaCVNVJ8eu
+ 6i6KyhzLa0L7yK3LXwwXVs583C0/vwFhccGWsFODqD/9xHUzsBIshE8HKjdjDi7Y
+ 3BFQzVUQFjBB50NSZfAA/jcdt1blxJouc7z9T8Oklh+V5DDBowgAsrT4b6Z2Fq6/
+ r7D1GqivLK/ypUQmxq2WXWAUBb/Q6xHgxASxI4Br+CByIUQJsm8L2jzc7k+mF4hW
+ ltAIUkbo8fGiVnat0505YJgxWEDKOLc4Gda6d/7GVd5AvKrz242bUqeaWo6e4MTx
+ diku2Ma3rhdcr044Qvfh9hGyjqNjvhWY/I+VRWgihU7JrYvgwFdJqsQ5eiKT4OHi
+ gsejvWwkZzDtiQ+aQTrzM1FsY2swJBJsLSX4ofohlVRlIJCn/ME+XErj553431Lu
+ YQ5SzMd3nXzN78Vj6qzTfMUUY72UoT1/AcFiUMobgIqrrmwuNxfrkbVE2b6Bga74
+ FsJX63prvrJ41kuHK/16RQBM7fcCAwEAAaOCAWAwggFcMB8GA1UdIwQYMBaAFMOc
+ 8/zTRgg0u85Gf6B8W/PiCMtZMFcGCCsGAQUFBwEBBEswSTAfBggrBgEFBQcwAYYT
+ aHR0cDovL2d2LnN5bWNkLmNvbTAmBggrBgEFBQcwAoYaaHR0cDovL2d2LnN5bWNi
+ LmNvbS9ndi5jcnQwDgYDVR0PAQH/BAQDAgWgMB0GA1UdJQQWMBQGCCsGAQUFBwMB
+ BggrBgEFBQcDAjAvBgNVHREEKDAmghN3d3cuY3J5cHRvZ3JhcGh5Lmlvgg9jcnlw
+ dG9ncmFwaHkuaW8wKwYDVR0fBCQwIjAgoB6gHIYaaHR0cDovL2d2LnN5bWNiLmNv
+ bS9ndi5jcmwwDAYDVR0TAQH/BAIwADBFBgNVHSAEPjA8MDoGCmCGSAGG+EUBBzYw
+ LDAqBggrBgEFBQcCARYeaHR0cHM6Ly93d3cucmFwaWRzc2wuY29tL2xlZ2FsMA0G
+ CSqGSIb3DQEBCwUAA4IBAQAzIYO2jx7h17FBT74tJ2zbV9OKqGb7QF8y3wUtP4xc
+ dH80vprI/Cfji8s86kr77aAvAqjDjaVjHn7UzebhSUivvRPmfzRgyWBacomnXTSt
+ Xlt2dp2nDQuwGyK2vB7dMfKnQAkxwq1sYUXznB8i0IhhCAoXp01QGPKq51YoIlnF
+ 7DRMk6iEaL1SJbkIrLsCQyZFDf0xtfW9DqXugMMLoxeCsBhZJQzNyS2ryirrv9LH
+ aK3+6IZjrcyy9bkpz/gzJucyhU+75c4My/mnRCrtItRbCQuiI5pd5poDowm+HH9i
+ GVI9+0lAFwxOUnOnwsoI40iOoxjLMGB+CgFLKCGUcWxP
+ -----END CERTIFICATE-----
+ """.strip()
+
X.509 is an ITU-T standard for a `public key infrastructure`_. X.509v3 is
defined in :rfc:`5280` (which obsoletes :rfc:`2459` and :rfc:`3280`). X.509
certificates are commonly used in protocols like `TLS`_.
@@ -281,6 +317,7 @@ X.509 Certificate Object
>>> for ext in cert.extensions:
... print(ext)
+ <Extension(oid=<ObjectIdentifier(oid=2.5.29.35, name=authorityKeyIdentifier)>, critical=False, value=<AuthorityKeyIdentifier(key_identifier='\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='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.19, name=basicConstraints)>, critical=True, value=<BasicConstraints(ca=True, path_length=None)>)>
@@ -646,10 +683,10 @@ X.509 Extensions
certificate. This attribute only has meaning if ``ca`` is true.
If ``ca`` is true then a path length of None means there's no
restriction on the number of subordinate CAs in the certificate chain.
- If it is zero or greater then that number defines the maximum length.
- For example, a ``path_length`` of 1 means the certificate can sign a
- subordinate CA, but the subordinate CA is not allowed to create
- subordinates with ``ca`` set to true.
+ If it is zero or greater then it defines the maximum length for a
+ subordinate CA's certificate chain. For example, a ``path_length`` of 1
+ means the certificate can sign a subordinate CA, but the subordinate CA
+ is not allowed to create subordinates with ``ca`` set to true.
.. class:: ExtendedKeyUsage
@@ -718,6 +755,48 @@ X.509 Extensions
:returns: A list of values extracted from the matched general names.
+ .. 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())
+ >>> # Get the subjectAltName extension from the certificate
+ >>> ext = cert.extensions.get_extension_for_oid(x509.OID_SUBJECT_ALTERNATIVE_NAME)
+ >>> # Get the dNSName entries from the SAN extension
+ >>> ext.value.get_values_for_type(x509.DNSName)
+ [u'www.cryptography.io', u'cryptography.io']
+
+
+.. class:: AuthorityInformationAccess
+
+ .. versionadded:: 0.9
+
+ The authority information access extension indicates how to access
+ information and services for the issuer of the certificate in which
+ the extension appears. Information and services may include online
+ validation services (such as OCSP) and issuer data. It is an iterable,
+ containing one or more :class:`AccessDescription` instances.
+
+
+.. class:: AccessDescription
+
+ .. attribute:: access_method
+
+ :type: :class:`ObjectIdentifier`
+
+ The access method defines what the ``access_location`` means. It must
+ be either :data:`OID_OCSP` or :data:`OID_CA_ISSUERS`. If it is
+ :data:`OID_OCSP` the access location will be where to obtain OCSP
+ information for the certificate. If it is :data:`OID_CA_ISSUERS` the
+ access location will provide additional information about the issuing
+ certificate.
+
+ .. attribute:: access_location
+
+ :type: :class:`GeneralName`
+
+ Where to access the information defined by the access method.
Object Identifiers
~~~~~~~~~~~~~~~~~~
@@ -911,6 +990,19 @@ Extended Key Usage OIDs
Corresponds to the dotted string ``"1.3.6.1.5.5.7.3.9"``. This is used to
denote that a certificate may be used for signing OCSP responses.
+Authority Information Access OIDs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. data:: OID_OCSP
+
+ Corresponds to the dotted string ``"1.3.6.1.5.5.7.48.1"``. Used as the
+ identifier for OCSP data in :class:`AccessDescription` objects.
+
+.. data:: OID_CA_ISSUERS
+
+ Corresponds to the dotted string ``"1.3.6.1.5.5.7.48.2"``. Used as the
+ identifier for CA issuer data in :class:`AccessDescription` objects.
+
.. _extension_oids:
Extension OIDs
generated by cgit v1.2.3 (git 2.25.1) at 2025-04-06 18:54:29 +0000