@@ -491,12 +491,20 @@ file suffix.
491
491
492
492
.. versionadded :: 3.0
493
493
494
+ .. note ::
495
+ With OpenSSL 3.0.0+ the defaults for encryption when serializing PKCS12
496
+ have changed and some versions of Windows and macOS will not be able to
497
+ read the new format. Maximum compatibility can be achieved by using
498
+ ``SHA1 `` for MAC algorithm and
499
+ :attr: `~cryptography.hazmat.primitives.serialization.pkcs12.PBES.PBESv1SHA1And3KeyTripleDESCBC `
500
+ for encryption algorithm as seen in the example below. However, users
501
+ should avoid this unless required for compatibility.
502
+
494
503
.. warning ::
495
504
496
- PKCS12 encryption is not secure and should not be used as a security
497
- mechanism. Wrap a PKCS12 blob in a more secure envelope if you need
498
- to store or send it safely. Encryption is provided for compatibility
499
- reasons only.
505
+ PKCS12 encryption is typically not secure and should not be used as a
506
+ security mechanism. Wrap a PKCS12 blob in a more secure envelope if you
507
+ need to store or send it safely.
500
508
501
509
Serialize a PKCS12 blob.
502
510
@@ -535,11 +543,41 @@ file suffix.
535
543
:param encryption_algorithm: The encryption algorithm that should be used
536
544
for the key and certificate. An instance of an object conforming to the
537
545
:class: `~cryptography.hazmat.primitives.serialization.KeySerializationEncryption `
538
- interface. PKCS12 encryption is **very weak ** and should not be used
539
- as a security boundary.
546
+ interface. PKCS12 encryption is typically **very weak ** and should not
547
+ be used as a security boundary.
540
548
541
549
:return bytes: Serialized PKCS12.
542
550
551
+ .. doctest ::
552
+
553
+ >>> from cryptography import x509
554
+ >>> from cryptography.hazmat.primitives.serialization import BestAvailableEncryption, load_pem_private_key, pkcs12
555
+ >>> cert = x509.load_pem_x509_certificate(ca_cert)
556
+ >>> key = load_pem_private_key(ca_key, None )
557
+ >>> p12 = pkcs12.serialize_key_and_certificates(
558
+ ... b " friendlyname" , key, cert, None , BestAvailableEncryption(b " password" )
559
+ ... )
560
+
561
+ This example uses an ``encryption_builder() `` to create a PKCS12 with more
562
+ compatible, but substantially less secure, encryption.
563
+
564
+ .. doctest ::
565
+
566
+ >>> from cryptography import x509
567
+ >>> from cryptography.hazmat.primitives import hashes
568
+ >>> from cryptography.hazmat.primitives.serialization import PrivateFormat, load_pem_private_key, pkcs12
569
+ >>> encryption = (
570
+ ... PrivateFormat.PKCS12 .encryption_builder().
571
+ ... kdf_rounds(50000 ).
572
+ ... key_cert_algorithm(pkcs12.PBES .PBESv1SHA1And3KeyTripleDESCBC).
573
+ ... hmac_hash(hashes.SHA1()).build(b " my password" )
574
+ ... )
575
+ >>> cert = x509.load_pem_x509_certificate(ca_cert)
576
+ >>> key = load_pem_private_key(ca_key, None )
577
+ >>> p12 = pkcs12.serialize_key_and_certificates(
578
+ ... b " friendlyname" , key, None , None , encryption
579
+ ... )
580
+
543
581
.. class :: PKCS12Certificate
544
582
545
583
.. versionadded :: 36.0
@@ -579,6 +617,24 @@ file suffix.
579
617
A list of :class: `~cryptography.hazmat.primitives.serialization.pkcs12.PKCS12Certificate `
580
618
instances.
581
619
620
+ .. class :: PBES
621
+
622
+ .. versionadded :: 38.0.0
623
+
624
+ An enumeration of password-based encryption schemes used in PKCS12. These
625
+ values are used with
626
+ :class: `~cryptography.hazmat.primitives.serialization.KeySerializationEncryptionBuilder `.
627
+
628
+ .. attribute :: PBESv1SHA1And3KeyTripleDESCBC
629
+
630
+ PBESv1 using SHA1 as the KDF PRF and 3-key triple DES-CBC as the cipher.
631
+
632
+ .. attribute :: PBESv2SHA256AndAES256CBC
633
+
634
+ PBESv2 using SHA256 as the KDF PRF and AES256-CBC as the cipher. This
635
+ is only supported on OpenSSL 3.0.0 or newer.
636
+
637
+
582
638
PKCS7
583
639
~~~~~
584
640
@@ -841,16 +897,40 @@ Serialization Formats
841
897
...
842
898
-----END OPENSSH PRIVATE KEY-----
843
899
900
+ .. attribute :: PKCS12
901
+
902
+ .. versionadded :: 38.0.0
903
+
904
+ The PKCS#12 format is a binary format used to store private keys and
905
+ certificates. This attribute is used in conjunction with
906
+ ``encryption_builder() `` to allow control of the encryption algorithm
907
+ and parameters.
908
+
909
+ .. doctest ::
910
+
911
+ >>> from cryptography.hazmat.primitives import hashes
912
+ >>> from cryptography.hazmat.primitives.serialization import PrivateFormat, pkcs12
913
+ >>> encryption = (
914
+ ... PrivateFormat.PKCS12 .encryption_builder().
915
+ ... kdf_rounds(50000 ).
916
+ ... key_cert_algorithm(pkcs12.PBES .PBESv2SHA256AndAES256CBC).
917
+ ... hmac_hash(hashes.SHA256()).build(b " my password" )
918
+ ... )
919
+ >>> p12 = pkcs12.serialize_key_and_certificates(
920
+ ... b " friendlyname" , key, None , None , encryption
921
+ ... )
922
+
844
923
.. method :: encryption_builder()
845
924
846
925
.. versionadded :: 38.0.0
847
926
848
927
Returns a builder for configuring how values are encrypted with this
849
- format.
928
+ format. You must call this method on an element of the enumeration.
929
+ For example, ``PrivateFormat.OpenSSH.encryption_builder() ``.
850
930
851
931
For most use cases, :class: `BestAvailableEncryption ` is preferred.
852
932
853
- :returns KeySerializationEncryptionBuilder : A new builder.
933
+ :returns: A new instance of :class: ` KeySerializationEncryptionBuilder `
854
934
855
935
.. doctest ::
856
936
@@ -1022,7 +1102,8 @@ Serialization Encryption Types
1022
1102
1023
1103
Encrypt using the best available encryption for a given key.
1024
1104
This is a curated encryption choice and the algorithm may change over
1025
- time.
1105
+ time. The encryption algorithm may vary based on which version of OpenSSL
1106
+ the library is compiled against.
1026
1107
1027
1108
:param bytes password: The password to use for encryption.
1028
1109
@@ -1033,25 +1114,43 @@ Serialization Encryption Types
1033
1114
1034
1115
.. class :: KeySerializationEncryptionBuilder
1035
1116
1036
- A builder that can be used to configure how key data is encrypted. To
1037
- create one, call :meth: `PrivateFormat.encryption_builder `.
1117
+ .. versionadded :: 38.0.0
1118
+
1119
+ A builder that can be used to configure how data is encrypted. To
1120
+ create one, call :meth: `PrivateFormat.encryption_builder `. Different
1121
+ serialization types will support different options on this builder.
1038
1122
1039
1123
.. method :: kdf_rounds(rounds)
1040
1124
1041
1125
Set the number of rounds the Key Derivation Function should use. The
1042
1126
meaning of the number of rounds varies on the KDF being used.
1043
1127
1044
1128
:param int rounds: Number of rounds.
1045
- :returns KeySerializationEncryptionBuilder: A new builder.
1129
+
1130
+ .. method :: key_cert_algorithm(algorithm)
1131
+
1132
+ Set the encryption algorithm to use when encrypting the key and
1133
+ certificate in a PKCS12 structure.
1134
+
1135
+ :param algorithm: A value from the :class: `~cryptography.hazmat.primitives.serialization.pkcs12.PBES `
1136
+ enumeration.
1137
+
1138
+ .. method :: hmac_hash(algorithm)
1139
+
1140
+ Set the hash algorithm to use within the MAC for a PKCS12 structure.
1141
+
1142
+ :param algorithm: An instance of a
1143
+ :class: `~cryptography.hazmat.primitives.hashes.HashAlgorithm `
1046
1144
1047
1145
.. method :: build(password)
1048
1146
1049
1147
Turns the builder into an instance of
1050
1148
:class: `KeySerializationEncryption ` with a given password.
1051
1149
1052
1150
:param bytes password: The password.
1053
- :returns KeySerializationEncryption: A key key serialization
1054
- encryption that can be passed to ``private_bytes `` methods.
1151
+ :returns: A :class: `KeySerializationEncryption ` encryption object
1152
+ that can be passed to methods like ``private_bytes `` or
1153
+ :func: `~cryptography.hazmat.primitives.serialization.pkcs12.serialize_key_and_certificates `.
1055
1154
1056
1155
.. _`a bug in Firefox` : https://bugzilla.mozilla.org/show_bug.cgi?id=773111
1057
1156
.. _`PKCS3` : https://www.teletrust.de/fileadmin/files/oid/oid_pkcs-3v1-4.pdf
0 commit comments