diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/development/test-vectors.rst | 2 | ||||
-rw-r--r-- | docs/hazmat/primitives/asymmetric/dsa.rst | 10 | ||||
-rw-r--r-- | docs/hazmat/primitives/asymmetric/ec.rst | 46 | ||||
-rw-r--r-- | docs/hazmat/primitives/asymmetric/rsa.rst | 12 | ||||
-rw-r--r-- | docs/hazmat/primitives/asymmetric/serialization.rst | 6 | ||||
-rw-r--r-- | docs/hazmat/primitives/index.rst | 1 | ||||
-rw-r--r-- | docs/hazmat/primitives/key-exchange-agreements.rst | 23 | ||||
-rw-r--r-- | docs/installation.rst | 9 | ||||
-rw-r--r-- | docs/x509/reference.rst | 14 |
9 files changed, 81 insertions, 42 deletions
diff --git a/docs/development/test-vectors.rst b/docs/development/test-vectors.rst index bfe76330..0b249ccb 100644 --- a/docs/development/test-vectors.rst +++ b/docs/development/test-vectors.rst @@ -302,6 +302,8 @@ Custom X.509 Certificate Revocation List Vectors to "1.2.3.4". The CRL uses an unsupported MD2 signature algorithm. * ``crl_unsupported_reason.pem`` - Contains a CRL with one revocation which has an unsupported reason code. +* ``crl_inval_cert_issuer_entry_ext.pem`` - Contains a CRL with one revocation + which has one entry extension for certificate issuer with an empty value. Hashes ~~~~~~ diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst index 4eb17e30..1429cb09 100644 --- a/docs/hazmat/primitives/asymmetric/dsa.rst +++ b/docs/hazmat/primitives/asymmetric/dsa.rst @@ -86,8 +86,14 @@ described in :rfc:`3279`. This can be decoded using Verification ~~~~~~~~~~~~ -Using a :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey` -provider. +Verification is performed using a +:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey` provider. +You can get a public key object with +:func:`~cryptography.hazmat.primitives.serialization.load_pem_public_key`, +:func:`~cryptography.hazmat.primitives.serialization.load_der_public_key`, +:meth:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicNumbers.public_key` +, or +:meth:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey.public_key`. .. doctest:: diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst index 6356c278..e4df9b10 100644 --- a/docs/hazmat/primitives/asymmetric/ec.rst +++ b/docs/hazmat/primitives/asymmetric/ec.rst @@ -12,7 +12,7 @@ Elliptic curve cryptography Generate a new private key on ``curve`` for use with ``backend``. - :param backend: A :class:`EllipticCurve` provider. + :param curve: A :class:`EllipticCurve` provider. :param backend: A :class:`~cryptography.hazmat.backends.interfaces.EllipticCurveBackend` @@ -122,6 +122,32 @@ Elliptic Curve Signature Algorithms :returns: A new instance of a :class:`EllipticCurvePublicKey` provider. +Elliptic Curve Key Exchange algorithm +------------------------------------- + +.. class:: ECDH() + + .. versionadded:: 1.1 + + The Elliptic Curve Diffie-Hellman Key Exchange algorithm first standardized + in NIST publication `800-56A`_, and later in `800-56Ar2`_. + + For most applications the ``shared_key`` should be passed to a key + derivation function. + + .. doctest:: + + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.primitives.asymmetric import ec + >>> private_key = ec.generate_private_key( + ... ec.SECP384R1(), default_backend() + ... ) + >>> peer_public_key = ec.generate_private_key( + ... ec.SECP384R1(), default_backend() + ... ).public_key() + >>> shared_key = private_key.exchange(ec.ECDH(), peer_public_key) + + Elliptic Curves --------------- @@ -314,6 +340,22 @@ Key Interfaces :returns: :class:`~cryptography.hazmat.primitives.asymmetric.AsymmetricSignatureContext` + .. method:: exchange(algorithm, peer_public_key) + + Perform's a key exchange operation using the provided algorithm with + the peer's public key. + + For most applications the result should be passed to a key derivation + function. + + :param algorithm: The key exchange algorithm, currently only + :class:`~cryptography.hazmat.primitives.asymmetric.ec.ECDH` is + supported. + :param EllipticCurvePublicKey peer_public_key: The public key for the + peer. + + :returns bytes: A shared key. + .. method:: public_key() :return: :class:`EllipticCurvePublicKey` @@ -419,6 +461,8 @@ Key Interfaces .. _`FIPS 186-3`: http://csrc.nist.gov/publications/fips/fips186-3/fips_186-3.pdf .. _`FIPS 186-4`: http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf +.. _`800-56A`: http://csrc.nist.gov/publications/nistpubs/800-56A/SP800-56A_Revision1_Mar08-2007.pdf +.. _`800-56Ar2`: http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar2.pdf .. _`some concern`: https://crypto.stackexchange.com/questions/10263/should-we-trust-the-nist-recommended-ecc-parameters .. _`less than 224 bits`: http://www.ecrypt.eu.org/ecrypt2/documents/D.SPA.20.pdf .. _`elliptic curve diffie-hellman is faster than diffie-hellman`: http://digitalcommons.unl.edu/cgi/viewcontent.cgi?article=1100&context=cseconfwork diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index f88750cf..bc2402de 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -163,9 +163,15 @@ Verification ~~~~~~~~~~~~ The previous section describes what to do if you have a private key and want to -sign something. If you have a public key, a message, and a signature, you can -check that the public key genuinely was used to sign that specific message. You -also need to know which signing algorithm was used: +sign something. If you have a public key, a message, a signature, and the +signing algorithm that was used you can check that the private key associated +with a given public key was used to sign that specific message. You can obtain +a public key to use in verification using +:func:`~cryptography.hazmat.primitives.serialization.load_pem_public_key`, +:func:`~cryptography.hazmat.primitives.serialization.load_der_public_key`, +:meth:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicNumbers.public_key` +, or +:meth:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey.public_key`. .. doctest:: diff --git a/docs/hazmat/primitives/asymmetric/serialization.rst b/docs/hazmat/primitives/asymmetric/serialization.rst index 8d51f0d7..f14f4037 100644 --- a/docs/hazmat/primitives/asymmetric/serialization.rst +++ b/docs/hazmat/primitives/asymmetric/serialization.rst @@ -337,8 +337,6 @@ Serialization Encodings .. class:: Encoding - .. versionadded:: 0.8 - An enumeration for encoding types. Used with the ``private_bytes`` method available on :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKeyWithSerialization` @@ -353,10 +351,14 @@ Serialization Encodings .. attribute:: PEM + .. versionadded:: 0.8 + For PEM format. This is a base64 format with delimiters. .. attribute:: DER + .. versionadded:: 0.9 + For DER format. This is a binary format. diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst index 675111bb..a9ab38a0 100644 --- a/docs/hazmat/primitives/index.rst +++ b/docs/hazmat/primitives/index.rst @@ -15,4 +15,3 @@ Primitives constant-time interfaces twofactor - key-exchange-agreements diff --git a/docs/hazmat/primitives/key-exchange-agreements.rst b/docs/hazmat/primitives/key-exchange-agreements.rst deleted file mode 100644 index 8d79fbad..00000000 --- a/docs/hazmat/primitives/key-exchange-agreements.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. hazmat:: - -Key Exchange agreements -======================= - -.. module:: cryptography.hazmat.primitives.asymmetric.key_exchange - -Key exchange agreements are cryptographic operations, like Diffie-Hellman -key exchanges, that allow two parties to use their public-private key pairs -to establish a shared secret key over an insecure channel. Usually the -negotiated key is further derived before using it for symmetric operations. - -Interfaces -~~~~~~~~~~ - -.. class:: KeyExchangeContext - - .. versionadded:: 1.1 - - .. method:: agree(public_key) - - :param public_key: The peer public key, the type depends on the - crypto system used, for example :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey` diff --git a/docs/installation.rst b/docs/installation.rst index 5d629e9f..61f9348e 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -46,7 +46,9 @@ dependencies are included. Just run 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 (`32-bit`_ and `64-bit`_). Wherever you place your copy +release infrastructure (`openssl-release`_). Be sure to download the proper +version for your architecture and Python (2010 works for Python 2.6, 2.7, 3.3, +and 3.4 while 2015 is required for 3.5). 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: @@ -166,7 +168,7 @@ dependencies. ./config no-shared no-ssl2 -fPIC --prefix=${CWD}/openssl make && make install cd .. - CFLAGS="-I${CWD}/openssl/include" LDFLAGS="-L${CWD}/openssl/lib" pip wheel cryptography + CFLAGS="-I${CWD}/openssl/include" LDFLAGS="-L${CWD}/openssl/lib" pip wheel --no-use-wheel cryptography Building cryptography on OS X ----------------------------- @@ -250,8 +252,7 @@ information, consult `Greg Wilson's blog post`_ on the subject. .. _`Homebrew`: http://brew.sh .. _`MacPorts`: https://www.macports.org -.. _`32-bit`: https://jenkins.cryptography.io/job/openssl-win32-release/ -.. _`64-bit`: https://jenkins.cryptography.io/job/openssl-win64-release/ +.. _`openssl-release`: https://jenkins.cryptography.io/job/openssl-release/ .. _`bug in conda`: https://github.com/conda/conda-recipes/issues/110 .. _`Greg Wilson's blog post`: http://software-carpentry.org/blog/2014/04/mr-biczo-was-right.html .. _virtualenv: https://virtualenv.pypa.io/en/latest/ diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst index eec0cbcc..5ab6caa5 100644 --- a/docs/x509/reference.rst +++ b/docs/x509/reference.rst @@ -287,13 +287,13 @@ X.509 Certificate Object .. method:: public_key() - :type: + 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` - The public key associated with the certificate. - .. doctest:: >>> from cryptography.hazmat.primitives.asymmetric import rsa @@ -617,6 +617,8 @@ X.509 Certificate Builder :class:`~cryptography.hazmat.backends.interfaces.X509Backend` interface. + :returns: :class:`~cryptography.x509.Certificate` + X.509 CSR (Certificate Signing Request) Object ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -627,13 +629,13 @@ X.509 CSR (Certificate Signing Request) Object .. method:: public_key() - :type: + 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` - The public key associated with the request. - .. doctest:: >>> from cryptography.hazmat.primitives.asymmetric import rsa |