diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/development/test-vectors.rst | 18 | ||||
| -rw-r--r-- | docs/glossary.rst | 8 | ||||
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 13 | ||||
| -rw-r--r-- | docs/hazmat/primitives/twofactor.rst | 47 | ||||
| -rw-r--r-- | docs/spelling_wordlist.txt | 1 | ||||
| -rw-r--r-- | docs/x509.rst | 114 |
6 files changed, 191 insertions, 10 deletions
diff --git a/docs/development/test-vectors.rst b/docs/development/test-vectors.rst index b4f23eda..0bd1f69e 100644 --- a/docs/development/test-vectors.rst +++ b/docs/development/test-vectors.rst @@ -22,7 +22,7 @@ Asymmetric ciphers * RSA FIPS 186-2 and PKCS1 v1.5 vulnerability test vectors from `NIST CAVP`_. * FIPS 186-2 and FIPS 186-3 DSA test vectors from `NIST CAVP`_. * FIPS 186-2 and FIPS 186-3 ECDSA test vectors from `NIST CAVP`_. -* DH and ECDH test vectors from `NIST CAVP`_. +* DH and ECDH and ECDH+KDF(17.4) test vectors from `NIST CAVP`_. * Ed25519 test vectors from the `Ed25519 website_`. * OpenSSL PEM RSA serialization vectors from the `OpenSSL example key`_ and `GnuTLS key parsing tests`_. @@ -234,6 +234,22 @@ Custom X.509 Request Vectors 2048 bit key containing a basic constraints extension marked as critical. +Custom X.509 Certificate Revocation List Vectors +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* ``crl_all_reasons.pem`` - Contains a CRL with 12 revoked certificates, whose + serials match their list position. It includes one revocation without + any entry extensions, 10 revocations with every supported reason code and one + revocation with an unsupported, non-critical entry extension with the OID + value set to "1.2.3.4". +* ``crl_dup_entry_ext.pem`` - Contains a CRL with one revocation which has a + duplicate entry extension. +* ``crl_md2_unknown_crit_entry_ext.pem`` - Contains a CRL with one revocation + which contains an unsupported critical entry extension with the OID value set + 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. + Hashes ~~~~~~ diff --git a/docs/glossary.rst b/docs/glossary.rst index dc6f3ebf..202fa2de 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -64,3 +64,11 @@ Glossary text This type corresponds to ``unicode`` on Python 2 and ``str`` on Python 3. This is equivalent to ``six.text_type``. + + nonce + A nonce is a **n**\ umber used **once**. Nonces are used in many + cryptographic protocols. Generally, a nonce does not have to be secret + or unpredictable, but it must be unique. A nonce is often a random + or pseudo-random number (see :doc:`Random number generation + </random-numbers>`). Since a nonce does not have to be unpredictable, + it can also take a form of a counter. diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 47486895..309c6fd0 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -240,7 +240,7 @@ Modes **This mode does not require padding.** - :param bytes nonce: Should be :doc:`random bytes </random-numbers>`. It is + :param bytes nonce: Should be unique, a :term:`nonce`. It is critical to never reuse a ``nonce`` with a given key. Any reuse of a nonce with the same key compromises the security of every message encrypted with that key. Must be the same number of bytes as the @@ -305,12 +305,11 @@ Modes **This mode does not require padding.** - :param bytes initialization_vector: Must be :doc:`random bytes - </random-numbers>`. They do not need to be kept secret and they can be - included in a transmitted message. NIST `recommends a 96-bit IV - length`_ for performance critical situations but it can be up to - 2\ :sup:`64` - 1 bits. Do not reuse an ``initialization_vector`` with a - given ``key``. + :param bytes initialization_vector: Must be unique, a :term:`nonce`. + They do not need to be kept secret and they can be included in a + transmitted message. NIST `recommends a 96-bit IV length`_ for + performance critical situations but it can be up to 2\ :sup:`64` - 1 + bits. Do not reuse an ``initialization_vector`` with a given ``key``. .. note:: diff --git a/docs/hazmat/primitives/twofactor.rst b/docs/hazmat/primitives/twofactor.rst index dd3e0250..df70a58a 100644 --- a/docs/hazmat/primitives/twofactor.rst +++ b/docs/hazmat/primitives/twofactor.rst @@ -74,6 +74,18 @@ codes (HMAC). :raises cryptography.hazmat.primitives.twofactor.InvalidToken: This is raised when the supplied HOTP does not match the expected HOTP. + .. method:: get_provisioning_uri(account_name, counter, issuer) + + :param account_name: The display name of account, such as + ``'Alice Smith'`` or ``'alice@example.com'``. + :type account_name: :term:`text` + :param issuer: The optional display name of issuer. This is typically + the provider or service the user wants to access using the OTP + token. + :type issuer: :term:`text` or `None` + :param int counter: The current value of counter. + :return: A URI string. + Throttling ~~~~~~~~~~ @@ -171,3 +183,38 @@ similar to the following code. :param int time: The time value to validate against. :raises cryptography.hazmat.primitives.twofactor.InvalidToken: This is raised when the supplied TOTP does not match the expected TOTP. + + .. method:: get_provisioning_uri(account_name, issuer) + + :param account_name: The display name of account, such as + ``'Alice Smith'`` or ``'alice@example.com'``. + :type: :term:`text` + :param issuer: The optional display name of issuer. This is typically + the provider or service the user wants to access using the OTP + token. + :type issuer: :term:`text` or `None` + :return: A URI string. + +Provisioning URI +~~~~~~~~~~~~~~~~ + +The provisioning URI of HOTP and TOTP is not actual the part of RFC 4226 and +RFC 6238, but a `spec of Google Authenticator`_. It is widely supported by web +sites and mobile applications which are using Two-Factor authentication. + +For generating a provisioning URI, you could use the ``get_provisioning_uri`` +method of HOTP/TOTP instances. + +.. code-block:: python + + counter = 5 + account_name = 'alice@example.com' + issuer_name = 'Example Inc' + + hotp_uri = hotp.get_provisioning_uri(account_name, counter, issuer_name) + totp_uri = totp.get_provisioning_uri(account_name, issuer_name) + +A common usage is encoding the provisioning URI into QR code and guiding users +to scan it with Two-Factor authentication applications in their mobile devices. + +.. _`spec of Google Authenticator`: https://github.com/google/google-authenticator/wiki/Key-Uri-Format diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index badb500c..81510134 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -40,6 +40,7 @@ multi naïve namespace namespaces +Nonces online paddings pickleable diff --git a/docs/x509.rst b/docs/x509.rst index c570f196..bdcd60b1 100644 --- a/docs/x509.rst +++ b/docs/x509.rst @@ -208,7 +208,7 @@ X.509 Certificate Object :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` that will be used to generate the fingerprint. - :return bytes: The fingerprint using the supplied hash algorithm as + :return bytes: The fingerprint using the supplied hash algorithm, as bytes. .. doctest:: @@ -326,6 +326,70 @@ X.509 Certificate Object <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)>)> + .. method:: public_bytes(encoding) + + :param encoding: The + :class:`~cryptography.hazmat.primitives.serialization.Encoding` + that will be used to serialize the certificate. + + :return bytes: The data that can be written to a file or sent + over the network to be verified by clients. + +X.509 CRL (Certificate Revocation List) Object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: CertificateRevocationList + + .. versionadded:: 1.0 + + .. method:: fingerprint(algorithm) + + :param algorithm: The + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` + that will be used to generate the fingerprint. + + :return bytes: The fingerprint using the supplied hash algorithm, as + bytes. + + .. attribute:: signature_hash_algorithm + + :type: :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` + + Returns the + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` which + was used in signing this CRL. + + .. attribute:: issuer + + :type: :class:`Name` + + The :class:`Name` of the issuer. + + .. attribute:: next_update + + :type: :class:`datetime.datetime` + + A naïve datetime representing when the next update to this CRL is + expected. + + .. attribute:: last_update + + :type: :class:`datetime.datetime` + + A naïve datetime representing when the this CRL was last updated. + + .. attribute:: revoked_certificates + + :type: list of :class:`RevokedCertificate` + + The revoked certificates listed in this CRL. + + .. attribute:: extensions + + :type: :class:`Extensions` + + The extensions encoded in the CRL. + X.509 CSR (Certificate Signing Request) Object ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -379,6 +443,30 @@ X.509 CSR (Certificate Signing Request) Object over the network to be signed by the certificate authority. +X.509 Revoked Certificate Object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: RevokedCertificate + + .. versionadded:: 1.0 + + .. attribute:: serial_number + + :type: :class:`int` + + An integer representing the serial number of the revoked certificate. + + .. attribute:: revocation_date + + :type: :class:`datetime.datetime` + + A naïve datetime representing the date this certificates was revoked. + + .. attribute:: extensions + + :type: :class:`Extensions` + + The extensions encoded in the revoked certificate. .. class:: Name @@ -715,7 +803,7 @@ X.509 Extensions .. class:: OCSPNoCheck - .. versionadded:: 0.10 + .. versionadded:: 1.0 This presence of this extension indicates that an OCSP client can trust a responder for the lifetime of the responder's certificate. CAs issuing @@ -921,6 +1009,24 @@ X.509 Extensions removed from the CRL. This reason cannot be used as a reason flag in a :class:`DistributionPoint`. +.. class:: InhibitAnyPolicy + + .. versionadded:: 1.0 + + The inhibit ``anyPolicy`` extension indicates that the special OID + :data:`OID_ANY_POLICY`, is not considered an explicit match for other + :class:`CertificatePolicies` except when it appears in an intermediate + self-issued CA certificate. The value indicates the number of additional + non-self-issued certificates that may appear in the path before + :data:`OID_ANY_POLICY` is no longer permitted. For example, a value + of one indicates that :data:`OID_ANY_POLICY` may be processed in + certificates issued by the subject of this certificate, but not in + additional certificates in the path. + + .. attribute:: skip_certs + + :type: int + .. class:: CertificatePolicies .. versionadded:: 0.9 @@ -1212,6 +1318,10 @@ Policy Qualifier OIDs Corresponds to the dotted string ``"1.3.6.1.5.5.7.2.2"``. +.. data:: OID_ANY_POLICY + + Corresponds to the dotted string ``"2.5.29.32.0"``. + .. _extension_oids: Extension OIDs |