Skip to content

Commit 79e38a3

Browse files
intgrintgr
authored
Make Union type aliases a documented public API (pyca#8168)
* Rename Union type aliases to CamelCase Many `typing.Union` type aliases were previously using `UPPER_SNAKE_CASE`, but Python's convention is `CamelCase` for these (e.g. https://docs.python.org/3/library/typing.html#type-aliases) * Add utils.deprecated for the old non-underscore type aliases * Added documentation for new type aliases & minor tweaks * Use 'versionadded:: 40.0.0' * Fix CertificatePublicKeyTypes vs CertificateIssuerPublicKeyTypes. Rename CertificatePrivateKeyTypes to CertificateIssuerPrivateKeyTypes * Fix imports (ruff) * Fix one more versionadded * Tweak docs & Reorder: CertificateIssuerPublicKeyTypes before CertificateIssuerPrivateKeyTypes * Fix test mypy errors using cast() * Fix black, oops * Revert "Fix black, oops" This reverts commit 85344e2. * Revert "Fix test mypy errors using cast()" This reverts commit b272d8c. * Revert type of SubjectKeyIdentifier.from_public_key arg * Changelog tweak
1 parent f36f899 commit 79e38a3

File tree

22 files changed

+386
-216
lines changed

22 files changed

+386
-216
lines changed

‎CHANGELOG.rst

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,31 @@ Changelog
4242
``cryptography``, this note is included as a courtesy.
4343
* The X.509 builder classes now raise ``UnsupportedAlgorithm`` instead of
4444
``ValueError`` if an unsupported hash algorithm is passed.
45+
* Added public union type aliases for type hinting:
46+
47+
* Asymmetric types:
48+
:const:`~cryptography.hazmat.primitives.asymmetric.types.PublicKeyTypes`,
49+
:const:`~cryptography.hazmat.primitives.asymmetric.types.PrivateKeyTypes`,
50+
:const:`~cryptography.hazmat.primitives.asymmetric.types.CertificatePublicKeyTypes`,
51+
:const:`~cryptography.hazmat.primitives.asymmetric.types.CertificateIssuerPublicKeyTypes`,
52+
:const:`~cryptography.hazmat.primitives.asymmetric.types.CertificateIssuerPrivateKeyTypes`.
53+
* SSH keys:
54+
:const:`~cryptography.hazmat.primitives.serialization.SSHPublicKeyTypes`,
55+
:const:`~cryptography.hazmat.primitives.serialization.SSHPrivateKeyTypes`,
56+
:const:`~cryptography.hazmat.primitives.serialization.SSHCertPublicKeyTypes`,
57+
:const:`~cryptography.hazmat.primitives.serialization.SSHCertPrivateKeyTypes`.
58+
* PKCS12:
59+
:const:`~cryptography.hazmat.primitives.serialization.pkcs12.PKCS12PrivateKeyTypes`
60+
* PKCS7:
61+
:const:`~cryptography.hazmat.primitives.serialization.pkcs7.PKCS7HashTypes`,
62+
:const:`~cryptography.hazmat.primitives.serialization.pkcs7.PKCS7PrivateKeyTypes`.
63+
* Two-factor:
64+
:const:`~cryptography.hazmat.primitives.twofactor.hotp.HOTPHashTypes`
65+
66+
* Deprecated previously undocumented but not private type aliases in the
67+
``cryptography.hazmat.primitives.asymmetric.types`` module in favor of new
68+
ones above.
69+
4570

4671
.. _v39-0-2:
4772

‎docs/hazmat/primitives/asymmetric/index.rst

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,3 +36,83 @@ private key is able to decrypt it.
3636

3737

3838
.. _`proof of identity`: https://en.wikipedia.org/wiki/Public-key_infrastructure
39+
40+
Common types
41+
~~~~~~~~~~~~
42+
43+
Asymmetric key types do not inherit from a common base class. The following
44+
union type aliases can be used instead to reference a multitude of key types.
45+
46+
.. currentmodule:: cryptography.hazmat.primitives.asymmetric.types
47+
48+
.. data:: PublicKeyTypes
49+
50+
.. versionadded:: 40.0.0
51+
52+
Type alias: A union of all public key types supported:
53+
:class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPublicKey`,
54+
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`,
55+
:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey`,
56+
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`,
57+
:class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PublicKey`,
58+
:class:`~cryptography.hazmat.primitives.asymmetric.ed448.Ed448PublicKey`,
59+
:class:`~cryptography.hazmat.primitives.asymmetric.x25519.X25519PublicKey`,
60+
:class:`~cryptography.hazmat.primitives.asymmetric.x448.X448PublicKey`.
61+
62+
.. data:: PrivateKeyTypes
63+
64+
.. versionadded:: 40.0.0
65+
66+
Type alias: A union of all private key types supported:
67+
:class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPrivateKey`,
68+
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`,
69+
:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey`,
70+
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey`,
71+
:class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey`,
72+
:class:`~cryptography.hazmat.primitives.asymmetric.ed448.Ed448PrivateKey`,
73+
:class:`~cryptography.hazmat.primitives.asymmetric.x25519.X25519PrivateKey`,
74+
:class:`~cryptography.hazmat.primitives.asymmetric.x448.X448PrivateKey`.
75+
76+
.. data:: CertificatePublicKeyTypes
77+
78+
.. versionadded:: 40.0.0
79+
80+
Type alias: A union of all public key types supported for X.509
81+
certificates:
82+
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`,
83+
:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey`,
84+
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`,
85+
:class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PublicKey`,
86+
:class:`~cryptography.hazmat.primitives.asymmetric.ed448.Ed448PublicKey`,
87+
:class:`~cryptography.hazmat.primitives.asymmetric.x25519.X25519PublicKey`,
88+
:class:`~cryptography.hazmat.primitives.asymmetric.x448.X448PublicKey`.
89+
90+
.. data:: CertificateIssuerPublicKeyTypes
91+
92+
.. versionadded:: 40.0.0
93+
94+
Type alias: A union of all public key types that can sign other X.509
95+
certificates as an issuer. x448/x25519 can be a public key, but cannot be
96+
used in signing, so they are not allowed in these contexts.
97+
98+
Allowed:
99+
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`,
100+
:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey`,
101+
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`,
102+
:class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PublicKey`,
103+
:class:`~cryptography.hazmat.primitives.asymmetric.ed448.Ed448PublicKey`.
104+
105+
.. data:: CertificateIssuerPrivateKeyTypes
106+
107+
.. versionadded:: 40.0.0
108+
109+
Type alias: A union of all private key types that can sign other X.509
110+
certificates as an issuer. x448/x25519 can be a public key, but cannot be
111+
used in signing, so they are not allowed in these contexts.
112+
113+
Allowed:
114+
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`,
115+
:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey`,
116+
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey`,
117+
:class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey`,
118+
:class:`~cryptography.hazmat.primitives.asymmetric.ed448.Ed448PrivateKey`.

‎docs/hazmat/primitives/asymmetric/serialization.rst

Lines changed: 101 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -388,6 +388,19 @@ DSA keys look almost identical but begin with ``ssh-dss`` rather than
388388
``ssh-rsa``. ECDSA keys have a slightly different format, they begin with
389389
``ecdsa-sha2-{curve}``.
390390

391+
392+
.. data:: SSHPublicKeyTypes
393+
394+
.. versionadded:: 40.0.0
395+
396+
Type alias: A union of public key types accepted for SSH:
397+
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`,
398+
:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey`,
399+
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`
400+
, or
401+
:class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PublicKey`.
402+
403+
391404
.. function:: load_ssh_public_key(data)
392405

393406
.. versionadded:: 0.7
@@ -404,13 +417,8 @@ DSA keys look almost identical but begin with ``ssh-dss`` rather than
404417
:param data: The OpenSSH encoded key data.
405418
:type data: :term:`bytes-like`
406419

407-
:returns: One of
408-
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`,
409-
:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey`,
410-
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`
411-
, or
412-
:class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PublicKey`,
413-
depending on the contents of ``data``.
420+
:returns: One of :data:`SSHPublicKeyTypes` depending on the contents of
421+
``data``.
414422

415423
:raises ValueError: If the OpenSSH data could not be properly decoded or
416424
if the key is not in the proper format.
@@ -436,6 +444,18 @@ An example ECDSA key in OpenSSH format::
436444
BAUGBw==
437445
-----END OPENSSH PRIVATE KEY-----
438446

447+
.. data:: SSHPrivateKeyTypes
448+
449+
.. versionadded:: 40.0.0
450+
451+
Type alias: A union of private key types accepted for SSH:
452+
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`,
453+
:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey`,
454+
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey`
455+
or
456+
:class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey`.
457+
458+
439459
.. function:: load_ssh_private_key(data, password)
440460

441461
.. versionadded:: 3.0
@@ -454,13 +474,8 @@ An example ECDSA key in OpenSSH format::
454474
:param bytes password: Password bytes to use to decrypt
455475
password-protected key. Or ``None`` if not needed.
456476

457-
:returns: One of
458-
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`,
459-
:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey`,
460-
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey`
461-
or
462-
:class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey`,
463-
depending on the contents of ``data``.
477+
:returns: One of :data:`SSHPrivateKeyTypes` depending on the contents of
478+
``data``.
464479

465480
:raises ValueError: If the OpenSSH data could not be properly decoded,
466481
if the key is not in the proper format or the incorrect password
@@ -476,6 +491,28 @@ OpenSSH Certificate
476491
The format used by OpenSSH for certificates, as specified in
477492
`PROTOCOL.certkeys`_.
478493

494+
.. data:: SSHCertPublicKeyTypes
495+
496+
.. versionadded:: 40.0.0
497+
498+
Type alias: A union of public key types supported for SSH
499+
certificates:
500+
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`,
501+
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`
502+
or
503+
:class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PublicKey`
504+
505+
.. data:: SSHCertPrivateKeyTypes
506+
507+
.. versionadded:: 40.0.0
508+
509+
Type alias: A union of private key types supported for SSH
510+
certificates:
511+
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`,
512+
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey`
513+
or
514+
:class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey`
515+
479516
.. function:: load_ssh_public_identity(data)
480517

481518
.. versionadded:: 40.0.0
@@ -494,12 +531,7 @@ The format used by OpenSSH for certificates, as specified in
494531
:param data: The OpenSSH encoded data.
495532
:type data: bytes
496533

497-
:returns: :class:`SSHCertificate` or one of
498-
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`,
499-
:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey`,
500-
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`
501-
, or
502-
:class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PublicKey`.
534+
:returns: :class:`SSHCertificate` or one of :data:`SSHCertPublicKeyTypes`.
503535

504536
:raises ValueError: If the OpenSSH data could not be properly decoded.
505537

@@ -521,12 +553,8 @@ The format used by OpenSSH for certificates, as specified in
521553

522554
.. method:: public_key()
523555

524-
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`,
525-
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`
526-
or
527-
:class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PublicKey`
528-
529-
The public key contained in the certificate.
556+
The public key contained in the certificate, one of
557+
:data:`SSHCertPublicKeyTypes`.
530558

531559
.. attribute:: serial
532560

@@ -597,12 +625,8 @@ The format used by OpenSSH for certificates, as specified in
597625

598626
.. method:: signature_key()
599627

600-
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`,
601-
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`
602-
or
603-
:class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PublicKey`
604-
605-
The public key used to sign the certificate.
628+
The public key used to sign the certificate, one of
629+
:data:`SSHCertPublicKeyTypes`.
606630

607631
.. method:: verify_cert_signature()
608632

@@ -689,10 +713,7 @@ SSH Certificate Builder
689713

690714
:param public_key: The public key to be included in the certificate.
691715
This value is required.
692-
:type public_key: :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`,
693-
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`
694-
or
695-
:class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PublicKey`
716+
:type public_key: :data:`SSHCertPublicKeyTypes`
696717

697718
.. method:: serial(serial)
698719

@@ -755,10 +776,7 @@ SSH Certificate Builder
755776

756777
:param private_key: The private key that will be used to sign the
757778
certificate.
758-
:type private_key: :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`,
759-
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey`
760-
or
761-
:class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey`
779+
:type private_key: :data:`SSHCertPrivateKeyTypes`
762780

763781
:return: The signed certificate.
764782
:rtype: :class:`SSHCertificate`
@@ -777,6 +795,23 @@ file suffix.
777795
``cryptography`` only supports a single private key and associated
778796
certificates when parsing PKCS12 files at this time.
779797

798+
799+
.. data:: PKCS12PrivateKeyTypes
800+
801+
.. versionadded:: 40.0.0
802+
803+
Type alias: A union of private key types supported for PKCS12
804+
serialization:
805+
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`
806+
,
807+
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey`
808+
,
809+
:class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey`
810+
,
811+
:class:`~cryptography.hazmat.primitives.asymmetric.ed448.Ed448PrivateKey`
812+
or
813+
:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey`.
814+
780815
.. function:: load_key_and_certificates(data, password)
781816

782817
.. versionadded:: 2.5
@@ -847,17 +882,7 @@ file suffix.
847882
:type name: bytes
848883

849884
:param key: The private key to include in the structure.
850-
:type key: An
851-
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`
852-
,
853-
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey`
854-
,
855-
:class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey`
856-
,
857-
:class:`~cryptography.hazmat.primitives.asymmetric.ed448.Ed448PrivateKey`
858-
, or
859-
:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey`
860-
object.
885+
:type key: :data:`PKCS12PrivateKeyTypes`
861886

862887
:param cert: The certificate associated with the private key.
863888
:type cert: :class:`~cryptography.x509.Certificate` or ``None``
@@ -933,7 +958,8 @@ file suffix.
933958
.. attribute:: key
934959

935960
An optional private key belonging to
936-
:attr:`~cryptography.hazmat.primitives.serialization.pkcs12.PKCS12KeyAndCertificates.cert`.
961+
:attr:`~cryptography.hazmat.primitives.serialization.pkcs12.PKCS12KeyAndCertificates.cert`
962+
(see :data:`PKCS12PrivateKeyTypes`).
937963

938964
.. attribute:: cert
939965

@@ -980,6 +1006,25 @@ contain certificates, CRLs, and much more. PKCS7 files commonly have a ``p7b``,
9801006
``cryptography`` only supports parsing certificates from PKCS7 files at
9811007
this time.
9821008

1009+
.. data:: PKCS7HashTypes
1010+
1011+
.. versionadded:: 40.0.0
1012+
1013+
Type alias: A union of hash types supported for PKCS7 serialization:
1014+
:class:`~cryptography.hazmat.primitives.hashes.SHA1`,
1015+
:class:`~cryptography.hazmat.primitives.hashes.SHA224`,
1016+
:class:`~cryptography.hazmat.primitives.hashes.SHA256`,
1017+
:class:`~cryptography.hazmat.primitives.hashes.SHA384`, or
1018+
:class:`~cryptography.hazmat.primitives.hashes.SHA512`.
1019+
1020+
.. data:: PKCS7PrivateKeyTypes
1021+
1022+
.. versionadded:: 40.0.0
1023+
1024+
Type alias: A union of private key types supported for PKCS7 serialization:
1025+
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey` or
1026+
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey`
1027+
9831028
.. function:: load_pem_pkcs7_certificates(data)
9841029

9851030
.. versionadded:: 3.1
@@ -1089,16 +1134,13 @@ contain certificates, CRLs, and much more. PKCS7 files commonly have a ``p7b``,
10891134
:param private_key: The
10901135
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey` or
10911136
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey`
1092-
associated with the certificate provided.
1137+
associated with the certificate provided
1138+
(matches :data:`PKCS7PrivateKeyTypes`).
10931139

10941140
:param hash_algorithm: The
10951141
:class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` that
1096-
will be used to generate the signature. This must be an instance of
1097-
:class:`~cryptography.hazmat.primitives.hashes.SHA1`,
1098-
:class:`~cryptography.hazmat.primitives.hashes.SHA224`,
1099-
:class:`~cryptography.hazmat.primitives.hashes.SHA256`,
1100-
:class:`~cryptography.hazmat.primitives.hashes.SHA384`, or
1101-
:class:`~cryptography.hazmat.primitives.hashes.SHA512`.
1142+
will be used to generate the signature. This must be one of the
1143+
types in :data:`PKCS7HashTypes`.
11021144

11031145
.. method:: add_certificate(certificate)
11041146

0 commit comments

Comments
 (0)