diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/community.rst | 2 | ||||
| -rw-r--r-- | docs/conf.py | 2 | ||||
| -rw-r--r-- | docs/development/c-bindings.rst | 2 | ||||
| -rw-r--r-- | docs/development/submitting-patches.rst | 3 | ||||
| -rw-r--r-- | docs/development/test-vectors.rst | 63 | ||||
| -rw-r--r-- | docs/hazmat/backends/openssl.rst | 2 | ||||
| -rw-r--r-- | docs/hazmat/bindings/openssl.rst | 2 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/dsa.rst | 3 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/ec.rst | 4 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/index.rst | 1 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/rsa.rst | 2 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/serialization.rst | 39 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/utils.rst | 26 | ||||
| -rw-r--r-- | docs/hazmat/primitives/interfaces.rst | 6 | ||||
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 2 | ||||
| -rw-r--r-- | docs/spelling_wordlist.txt | 1 |
16 files changed, 127 insertions, 33 deletions
diff --git a/docs/community.rst b/docs/community.rst index bf1cd1c7..2b7cdc60 100644 --- a/docs/community.rst +++ b/docs/community.rst @@ -17,4 +17,4 @@ Conduct`_. .. _`Source code`: https://github.com/pyca/cryptography .. _`Issue tracker`: https://github.com/pyca/cryptography/issues .. _`Documentation`: https://cryptography.io/ -.. _`Python Community Code of Conduct`: http://www.python.org/psf/codeofconduct/ +.. _`Python Community Code of Conduct`: https://www.python.org/psf/codeofconduct/ diff --git a/docs/conf.py b/docs/conf.py index b70114d8..fc16b38a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -268,6 +268,6 @@ texinfo_documents = [ # texinfo_show_urls = 'footnote' # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'http://docs.python.org/': None} +intersphinx_mapping = {'https://docs.python.org/': None} epub_theme = 'epub' diff --git a/docs/development/c-bindings.rst b/docs/development/c-bindings.rst index 10d5fc10..993a4ab2 100644 --- a/docs/development/c-bindings.rst +++ b/docs/development/c-bindings.rst @@ -3,7 +3,7 @@ C bindings C bindings are bindings to C libraries, using cffi_ whenever possible. -.. _cffi: http://cffi.readthedocs.org +.. _cffi: https://cffi.readthedocs.org Bindings live in :py:mod:`cryptography.hazmat.bindings`. diff --git a/docs/development/submitting-patches.rst b/docs/development/submitting-patches.rst index ff650c4f..810b8748 100644 --- a/docs/development/submitting-patches.rst +++ b/docs/development/submitting-patches.rst @@ -25,6 +25,9 @@ configuration. You can also run the ``tox`` job with ``tox -e pep8``. `Write comments as complete sentences.`_ +Class names which contains acronyms or initialisms should always be +capitalized. A class should be named ``HTTPClient``, not ``HttpClient``. + Every code file must start with the boilerplate licensing notice: .. code-block:: python diff --git a/docs/development/test-vectors.rst b/docs/development/test-vectors.rst index 8c2d1361..10c20dba 100644 --- a/docs/development/test-vectors.rst +++ b/docs/development/test-vectors.rst @@ -34,10 +34,48 @@ Asymmetric ciphers `enc2-rsa-pkcs8.pem`_ was re-encrypted using a stronger PKCS#8 cipher. * `Botan's ECC private keys`_. +Custom Asymmetric Vectors +~~~~~~~~~~~~~~~~~~~~~~~~~ + +* ``ec_private_key.pem`` - Contains an Elliptic Curve key generated by OpenSSL + from the curve ``secp256r1``. +* ``ec_private_key_encrypted.pem`` - Contains the same Elliptic Curve key as + ``ec_private_key.pem``, except that it is encrypted with AES-128 with the + password "123456". +* ``ec_public_key.pem`` - Contains the public key corresponding to + ``ec_private_key.pem``, generated using OpenSSL. +* ``rsa_private_key.pem`` - Contains an RSA 2048 bit key generated using + OpenSSL, protected by the secret "123456" with DES3 encryption. +* ``rsa_public_key.pem`` - Contains an RSA 2048 bit public generated using + OpenSSL from ``rsa_private_key.pem``. +* ``dsaparam.pem`` - Contains 2048-bit DSA parameters generated using OpenSSL; + contains no keys. +* ``dsa_private_key.pem`` - Contains a DSA 2048 bit key generated using + OpenSSL from the parameters in ``dsaparam.pem``, protected by the secret + "123456" with DES3 encryption. +* ``dsa_public_key.pem`` - Contains a DSA 2048 bit key generated using OpenSSL + from ``dsa_private_key.pem``. + + X.509 ~~~~~ * PKITS test suite from `NIST PKI Testing`_. +* ``v1_cert.pem`` from the OpenSSL source tree (`testx509.pem`_). +* ``ecdsa_root.pem`` - `DigiCert Global Root G3`_, a ``secp384r1`` ECDSA root + certificate. + +Custom X.509 Vectors +~~~~~~~~~~~~~~~~~~~~ + +* ``invalid_version.pem`` - Contains an RSA 2048 bit certificate with the + X.509 version field set to ``0x7``. +* ``post2000utctime.pem`` - Contains an RSA 2048 bit certificate with the + ``notBefore`` and ``notAfter`` fields encoded as post-2000 ``UTCTime``. +* ``dsa_selfsigned_ca.pem`` - Contains a DSA self-signed CA certificate + generated using OpenSSL. +* ``ec_no_named_curve.pem`` - Contains an ECDSA certificate that does not have + an embedded OID defining the curve. Hashes ~~~~~~ @@ -107,27 +145,8 @@ Creating test vectors When official vectors are unavailable ``cryptography`` may choose to build its own using existing vectors as source material. -Current custom vectors -~~~~~~~~~~~~~~~~~~~~~~ - -* ``ec_private_key.pem`` - Contains an Elliptic Curve key generated by OpenSSL - from the curve ``secp256r1``. -* ``ec_private_key_encrypted.pem`` - Contains the same Elliptic Curve key as - ``ec_private_key.pem``, except that it is encrypted with AES-128 with the - password "123456". -* ``ec_public_key.pem`` - Contains the public key corresponding to - ``ec_private_key.pem``, generated using OpenSSL. -* ``rsa_private_key.pem`` - Contains an RSA 2048 bit key generated using - OpenSSL, protected by the secret "123456" with DES3 encryption. -* ``rsa_public_key.pem`` - Contains an RSA 2048 bit public generated using - OpenSSL from ``rsa_private_key.pem``. -* ``dsaparam.pem`` - Contains 2048-bit DSA parameters generated using OpenSSL; - contains no keys. -* ``dsa_private_key.pem`` - Contains a DSA 2048 bit key generated using - OpenSSL from the parameters in ``dsaparam.pem``, protected by the secret - "123456" with DES3 encryption. -* ``dsa_public_key.pem`` - Contains a DSA 2048 bit key generated using OpenSSL - from ``dsa_private_key.pem``. +Custom Symmetric Vectors +~~~~~~~~~~~~~~~~~~~~~~~~ .. toctree:: :maxdepth: 1 @@ -174,3 +193,5 @@ header format (substituting the correct information): .. _`Ed25519 website`: http://ed25519.cr.yp.to/software.html .. _`NIST SP-800-38B`: http://csrc.nist.gov/publications/nistpubs/800-38B/Updated_CMAC_Examples.pdf .. _`NIST PKI Testing`: http://csrc.nist.gov/groups/ST/crypto_apps_infra/pki/pkitesting.html +.. _`testx509.pem`: https://github.com/openssl/openssl/blob/master/test/testx509.pem +.. _`DigiCert Global Root G3`: http://cacerts.digicert.com/DigiCertGlobalRootG3.crt diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index e829798a..b48e502d 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -78,5 +78,5 @@ seeded from the same pool as ``/dev/random``. .. _`OpenSSL`: https://www.openssl.org/ .. _`initializing the RNG`: https://en.wikipedia.org/wiki/OpenSSL#Predictable_keys_.28Debian-specific.29 -.. _`Yarrow`: http://en.wikipedia.org/wiki/Yarrow_algorithm +.. _`Yarrow`: https://en.wikipedia.org/wiki/Yarrow_algorithm .. _`Microsoft documentation`: http://msdn.microsoft.com/en-us/library/windows/desktop/aa379942(v=vs.85).aspx diff --git a/docs/hazmat/bindings/openssl.rst b/docs/hazmat/bindings/openssl.rst index a6d1c484..36255b52 100644 --- a/docs/hazmat/bindings/openssl.rst +++ b/docs/hazmat/bindings/openssl.rst @@ -46,4 +46,4 @@ OpenSSL. .. _`CFFI`: https://cffi.readthedocs.org/ .. _`OpenSSL`: https://www.openssl.org/ -.. _`thread safety facilities`: http://www.openssl.org/docs/crypto/threads.html +.. _`thread safety facilities`: https://www.openssl.org/docs/crypto/threads.html diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst index 43741ede..df3c99fc 100644 --- a/docs/hazmat/primitives/asymmetric/dsa.rst +++ b/docs/hazmat/primitives/asymmetric/dsa.rst @@ -80,7 +80,8 @@ provider. >>> signature = signer.finalize() The ``signature`` is a ``bytes`` object, whose contents is DER encoded as -described in :rfc:`6979`. +described in :rfc:`6979`. This can be decoded using +:func:`~cryptography.hazmat.primitives.asymmetric.utils.decode_rfc6979_signature`. Verification ~~~~~~~~~~~~ diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst index fd20cbb2..13ab7c11 100644 --- a/docs/hazmat/primitives/asymmetric/ec.rst +++ b/docs/hazmat/primitives/asymmetric/ec.rst @@ -53,7 +53,9 @@ Elliptic Curve Signature Algorithms >>> signature = signer.finalize() The ``signature`` is a ``bytes`` object, whose contents is DER encoded as - described in :rfc:`6979`. + described in :rfc:`6979`. This can be decoded using + :func:`~cryptography.hazmat.primitives.asymmetric.utils.decode_rfc6979_signature`. + .. class:: EllipticCurvePrivateNumbers(private_value, public_numbers) diff --git a/docs/hazmat/primitives/asymmetric/index.rst b/docs/hazmat/primitives/asymmetric/index.rst index 6a5228ba..24f0f5b1 100644 --- a/docs/hazmat/primitives/asymmetric/index.rst +++ b/docs/hazmat/primitives/asymmetric/index.rst @@ -11,3 +11,4 @@ Asymmetric algorithms rsa padding serialization + utils diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index a5cebb1d..6c96090a 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -271,4 +271,4 @@ this without having to do the math themselves. .. _`use 65537`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html .. _`at least 2048`: http://www.ecrypt.eu.org/documents/D.SPA.20.pdf .. _`OpenPGP`: https://en.wikipedia.org/wiki/Pretty_Good_Privacy -.. _`Chinese Remainder Theorem`: http://en.wikipedia.org/wiki/RSA_%28cryptosystem%29#Using_the_Chinese_remainder_algorithm +.. _`Chinese Remainder Theorem`: https://en.wikipedia.org/wiki/RSA_%28cryptosystem%29#Using_the_Chinese_remainder_algorithm diff --git a/docs/hazmat/primitives/asymmetric/serialization.rst b/docs/hazmat/primitives/asymmetric/serialization.rst index b0b37b80..a9392c7b 100644 --- a/docs/hazmat/primitives/asymmetric/serialization.rst +++ b/docs/hazmat/primitives/asymmetric/serialization.rst @@ -195,3 +195,42 @@ KEY-----`` or ``-----BEGIN DSA PRIVATE KEY-----``. :raises 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. + +OpenSSH Public Key +~~~~~~~~~~~~~~~~~~ + +The format used by OpenSSH to store public keys, as specified in :rfc:`4253`. + +Currently, only RSA public keys are supported. Any other type of key will +result in an exception being thrown. + +An example RSA key in OpenSSH format (line breaks added for formatting +purposes):: + + ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDDu/XRP1kyK6Cgt36gts9XAk + FiiuJLW6RU0j3KKVZSs1I7Z3UmU9/9aVh/rZV43WQG8jaR6kkcP4stOR0DEtll + PDA7ZRBnrfiHpSQYQ874AZaAoIjgkv7DBfsE6gcDQLub0PFjWyrYQUJhtOLQEK + vY/G0vt2iRL3juawWmCFdTK3W3XvwAdgGk71i6lHt+deOPNEPN2H58E4odrZ2f + sxn/adpDqfb2sM0kPwQs0aWvrrKGvUaustkivQE4XWiSFnB0oJB/lKK/CKVKuy + ///ImSCGHQRvhwariN2tvZ6CBNSLh3iQgeB0AkyJlng7MXB2qYq/Ci2FUOryCX + 2MzHvnbv testkey@localhost + +.. function:: load_ssh_public_key(data, backend) + + .. versionadded:: 0.7 + + Deserialize a public key from OpenSSH (:rfc:`4253`) encoded data to an + instance of the public key type for the specified backend. + + :param bytes data: The OpenSSH encoded key data. + + :param backend: An + :class:`~cryptography.hazmat.backends.interfaces.RSABackend` provider. + + :returns: A new instance of a public key type. + + :raises ValueError: If the OpenSSH data could not be properly decoded or + if the key is not in the proper format. + + :raises UnsupportedAlgorithm: If the serialized key is of a type that is + not supported. diff --git a/docs/hazmat/primitives/asymmetric/utils.rst b/docs/hazmat/primitives/asymmetric/utils.rst new file mode 100644 index 00000000..6b348801 --- /dev/null +++ b/docs/hazmat/primitives/asymmetric/utils.rst @@ -0,0 +1,26 @@ +.. hazmat:: + +Asymmetric Utilities +==================== + +.. currentmodule:: cryptography.hazmat.primitives.asymmetric.utils + + +.. function:: decode_rfc6979_signature(signature) + + Takes in :rfc:`6979` signatures generated by the DSA/ECDSA signers and + returns a tuple ``(r, s)``. + + :param bytes signature: The signature to decode. + + :returns: The decoded tuple ``(r, s)``. + +.. function:: encode_rfc6979_signature(r, s) + + Creates an :rfc:`6979` byte string from raw signature values. + + :param int r: The raw signature value ``r``. + + :param int s: The raw signature value ``s``. + + :return bytes: The encoded signature. diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index d964f25c..d87e8d66 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -9,7 +9,7 @@ properties and methods of most primitive constructs. Backends may also use this information to influence their operation. Interfaces should also be used to document argument and return types. -.. _`Abstract Base Classes`: http://docs.python.org/3.2/library/abc.html +.. _`Abstract Base Classes`: https://docs.python.org/3/library/abc.html Symmetric ciphers @@ -752,5 +752,5 @@ X509 .. _`Chinese remainder theorem`: https://en.wikipedia.org/wiki/Chinese_remainder_theorem .. _`DSA`: https://en.wikipedia.org/wiki/Digital_Signature_Algorithm .. _`CMAC`: https://en.wikipedia.org/wiki/CMAC -.. _`ECDSA`: http://en.wikipedia.org/wiki/ECDSA -.. _`EdDSA`: http://en.wikipedia.org/wiki/EdDSA +.. _`ECDSA`: https://en.wikipedia.org/wiki/ECDSA +.. _`EdDSA`: https://en.wikipedia.org/wiki/EdDSA diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 586285b7..b21ef612 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -510,6 +510,6 @@ Interfaces .. _`Communications Security Establishment`: http://www.cse-cst.gc.ca .. _`encrypt`: https://ssd.eff.org/tech/encryption .. _`CRYPTREC`: http://www.cryptrec.go.jp/english/ -.. _`significant patterns in the output`: http://en.wikipedia.org/wiki/Cipher_block_chaining#Electronic_codebook_.28ECB.29 +.. _`significant patterns in the output`: https://en.wikipedia.org/wiki/Cipher_block_chaining#Electronic_codebook_.28ECB.29 .. _`International Data Encryption Algorithm`: https://en.wikipedia.org/wiki/International_Data_Encryption_Algorithm .. _`OpenPGP`: http://www.openpgp.org diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index b7b33436..003e37d5 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -24,6 +24,7 @@ fernet Fernet hazmat indistinguishability +initialisms interoperable introspectability invariants |