diff options
Diffstat (limited to 'roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development')
27 files changed, 2824 insertions, 0 deletions
diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/c-bindings.rst b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/c-bindings.rst new file mode 100644 index 000000000..1b58dab62 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/c-bindings.rst @@ -0,0 +1,202 @@ +C bindings +========== + +C bindings are bindings to C libraries, using cffi_ whenever possible. + +.. _cffi: https://cffi.readthedocs.io + +Bindings live in :py:mod:`cryptography.hazmat.bindings`. + +When modifying the bindings you will need to recompile the C extensions to +test the changes. This can be accomplished with ``pip install -e .`` in the +project root. If you do not do this a ``RuntimeError`` will be raised. + +Style guide +----------- + +Don't name parameters: + +.. code-block:: c + + /* Good */ + long f(long); + /* Bad */ + long f(long x); + +...unless they're inside a struct: + +.. code-block:: c + + struct my_struct { + char *name; + int number; + ...; + }; + +Include ``void`` if the function takes no arguments: + +.. code-block:: c + + /* Good */ + long f(void); + /* Bad */ + long f(); + +Wrap lines at 80 characters like so: + +.. code-block:: c + + /* Pretend this went to 80 characters */ + long f(long, long, + int *) + +Include a space after commas between parameters: + +.. code-block:: c + + /* Good */ + long f(int, char *) + /* Bad */ + long f(int,char *) + +Use C-style ``/* */`` comments instead of C++-style ``//``: + +.. code-block:: c + + // Bad + /* Good */ + +Values set by ``#define`` should be assigned the appropriate type. If you see +this: + +.. code-block:: c + + #define SOME_INTEGER_LITERAL 0x0; + #define SOME_UNSIGNED_INTEGER_LITERAL 0x0001U; + #define SOME_STRING_LITERAL "hello"; + +...it should be added to the bindings like so: + +.. code-block:: c + + static const int SOME_INTEGER_LITERAL; + static const unsigned int SOME_UNSIGNED_INTEGER_LITERAL; + static const char *const SOME_STRING_LITERAL; + +Adding constant, types, functions... +------------------------------------ + +You can create bindings for any name that exists in some version of +the library you're binding against. However, the project also has to +keep supporting older versions of the library. In order to achieve this, +binding modules have a ``CUSTOMIZATIONS`` constant, and there is a +``CONDITIONAL_NAMES`` constants in +``src/cryptography/hazmat/bindings/openssl/_conditional.py``. + +Let's say you want to enable quantum transmogrification. The upstream +library implements this as the following API:: + + static const int QM_TRANSMOGRIFICATION_ALIGNMENT_LEFT; + static const int QM_TRANSMOGRIFICATION_ALIGNMENT_RIGHT; + typedef ... QM_TRANSMOGRIFICATION_CTX; + int QM_transmogrify(QM_TRANSMOGRIFICATION_CTX *, int); + +To start, create a new constant that defines if the *actual* library +has the feature you want, and add it to ``TYPES``:: + + static const long Cryptography_HAS_QUANTUM_TRANSMOGRIFICATION; + +This should start with ``Cryptography_``, since we're adding it in +this library. This prevents namespace collisions. + +Then, define the actual features (constants, types, functions...) you +want to expose. If it's a constant, just add it to ``TYPES``:: + + static const int QM_TRANSMOGRIFICATION_ALIGNMENT_LEFT; + static const int QM_TRANSMOGRIFICATION_ALIGNMENT_RIGHT; + +If it's a struct, add it to ``TYPES`` as well. The following is an +opaque struct:: + + typedef ... QM_TRANSMOGRIFICATION_CTX; + +... but you can also make some or all items in the struct accessible:: + + typedef struct { + /* Fundamental constant k for your particular universe */ + BIGNUM *k; + ...; + } QM_TRANSMOGRIFICATION_CTX; + +For functions just add the signature to ``FUNCTIONS``:: + + int QM_transmogrify(QM_TRANSMOGRIFICATION_CTX *, int); + +Then, we define the ``CUSTOMIZATIONS`` entry. To do that, we have to +come up with a C preprocessor expression that decides whether or not a +feature exists in the library. For example:: + + #ifdef QM_transmogrify + +Then, we set the flag that signifies the feature exists:: + + static const long Cryptography_HAS_QUANTUM_TRANSMOGRIFICATION = 1; + +Otherwise, we set that flag to 0:: + + #else + static const long Cryptography_HAS_QUANTUM_TRANSMOGRIFICATION = 0; + +Then, in that ``#else`` block, we define the names that aren't +available as dummy values. For an integer constant, use 0:: + + static const int QM_TRANSMOGRIFICATION_ALIGNMENT_LEFT = 0; + static const int QM_TRANSMOGRIFICATION_ALIGNMENT_RIGHT = 0; + +For a function, it's a bit trickier. You have to define a function +pointer of the appropriate type to be NULL:: + + int (*QM_transmogrify)(QM_TRANSMOGRIFICATION_CTX *, int) = NULL; + +(To do that, copy the signature, put a ``*`` in front of the function +name and wrap it in parentheses, and then put ``= NULL`` at the end). + +Note how types don't need to be conditionally defined, as long as all +the necessarily type definitions are in place. + +Finally, add an entry to ``CONDITIONAL_NAMES`` with all of the things +you want to conditionally export:: + + def cryptography_has_quantum_transmogrification(): + return [ + "QM_TRANSMOGRIFICATION_ALIGNMENT_LEFT", + "QM_TRANSMOGRIFICATION_ALIGNMENT_RIGHT", + "QM_transmogrify", + ] + + + CONDITIONAL_NAMES = { + ... + "Cryptography_HAS_QUANTUM_TRANSMOGRIFICATION": ( + cryptography_has_quantum_transmogrification + ), + } + + +Caveats +~~~~~~~ + +Sometimes, a set of loosely related features are added in the same +version, and it's impractical to create ``#ifdef`` statements for each +one. In that case, it may make sense to either check for a particular +version. For example, to check for OpenSSL 1.1.0 or newer:: + + #if CRYPTOGRAPHY_OPENSSL_110_OR_GREATER + +Sometimes, the version of a library on a particular platform will have +features that you thought it wouldn't, based on its version. +Occasionally, packagers appear to ship arbitrary VCS checkouts. As a +result, sometimes you may have to add separate ``#ifdef`` statements +for particular features. This kind of issue is typically only caught +by running the tests on a wide variety of systems, which is the job of +our continuous integration infrastructure. diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/arc4.rst b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/arc4.rst new file mode 100644 index 000000000..ed8cd5483 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/arc4.rst @@ -0,0 +1,30 @@ +ARC4 vector creation +==================== + +This page documents the code that was used to generate the ARC4 test +vectors for key lengths not available in RFC 6229. All the vectors +were generated using OpenSSL and verified with Go. + +Creation +-------- + +``cryptography`` was modified to support ARC4 key lengths not listed +in RFC 6229. Then the following Python script was run to generate the +vector files. + +.. literalinclude:: /development/custom-vectors/arc4/generate_arc4.py + +Download link: :download:`generate_arc4.py +</development/custom-vectors/arc4/generate_arc4.py>` + + +Verification +------------ + +The following Go code was used to verify the vectors. + +.. literalinclude:: /development/custom-vectors/arc4/verify_arc4.go + :language: go + +Download link: :download:`verify_arc4.go +</development/custom-vectors/arc4/verify_arc4.go>` diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/arc4/generate_arc4.py b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/arc4/generate_arc4.py new file mode 100644 index 000000000..3dee44a30 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/arc4/generate_arc4.py @@ -0,0 +1,98 @@ +# This file is dual licensed under the terms of the Apache License, Version +# 2.0, and the BSD License. See the LICENSE file in the root of this repository +# for complete details. + +from __future__ import absolute_import, division, print_function + +import binascii + +from cryptography.hazmat.backends import default_backend +from cryptography.hazmat.primitives import ciphers +from cryptography.hazmat.primitives.ciphers import algorithms + + +_RFC6229_KEY_MATERIALS = [ + (True, + 8 * '0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20'), + (False, + 8 * '1ada31d5cf688221c109163908ebe51debb46227c6cc8b37641910833222772a') +] + + +_RFC6229_OFFSETS = [ + 0, + 16, + 240, + 256, + 496, + 512, + 752, + 768, + 1008, + 1024, + 1520, + 1536, + 2032, + 2048, + 3056, + 3072, + 4080, + 4096 +] + + +_SIZES_TO_GENERATE = [ + 160 +] + + +def _key_for_size(size, keyinfo): + msb, key = keyinfo + if msb: + return key[:size // 4] + else: + return key[-size // 4:] + + +def _build_vectors(): + count = 0 + output = [] + key = None + plaintext = binascii.unhexlify(32 * '0') + for size in _SIZES_TO_GENERATE: + for keyinfo in _RFC6229_KEY_MATERIALS: + key = _key_for_size(size, keyinfo) + cipher = ciphers.Cipher( + algorithms.ARC4(binascii.unhexlify(key)), + None, + default_backend()) + encryptor = cipher.encryptor() + current_offset = 0 + for offset in _RFC6229_OFFSETS: + if offset % 16 != 0: + raise ValueError( + "Offset {} is not evenly divisible by 16" + .format(offset)) + while current_offset < offset: + encryptor.update(plaintext) + current_offset += len(plaintext) + output.append("\nCOUNT = {}".format(count)) + count += 1 + output.append("KEY = {}".format(key)) + output.append("OFFSET = {}".format(offset)) + output.append("PLAINTEXT = {}".format( + binascii.hexlify(plaintext))) + output.append("CIPHERTEXT = {}".format( + binascii.hexlify(encryptor.update(plaintext)))) + current_offset += len(plaintext) + assert not encryptor.finalize() + return "\n".join(output) + + +def _write_file(data, filename): + with open(filename, 'w') as f: + f.write(data) + + +if __name__ == '__main__': + _write_file(_build_vectors(), 'arc4.txt') diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/arc4/verify_arc4.go b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/arc4/verify_arc4.go new file mode 100644 index 000000000..508fe9807 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/arc4/verify_arc4.go @@ -0,0 +1,111 @@ +package main + +import ( + "bufio" + "bytes" + "crypto/rc4" + "encoding/hex" + "fmt" + "os" + "strconv" + "strings" +) + +func unhexlify(s string) []byte { + bytes, err := hex.DecodeString(s) + if err != nil { + panic(err) + } + return bytes +} + +type vectorArgs struct { + count string + offset uint64 + key string + plaintext string + ciphertext string +} + +type vectorVerifier interface { + validate(count string, offset uint64, key, plaintext, expectedCiphertext []byte) +} + +type arc4Verifier struct{} + +func (o arc4Verifier) validate(count string, offset uint64, key, plaintext, expectedCiphertext []byte) { + if offset%16 != 0 || len(plaintext) != 16 || len(expectedCiphertext) != 16 { + panic(fmt.Errorf("Unexpected input value encountered: offset=%v; len(plaintext)=%v; len(expectedCiphertext)=%v", + offset, + len(plaintext), + len(expectedCiphertext))) + } + stream, err := rc4.NewCipher(key) + if err != nil { + panic(err) + } + + var currentOffset uint64 = 0 + ciphertext := make([]byte, len(plaintext)) + for currentOffset <= offset { + stream.XORKeyStream(ciphertext, plaintext) + currentOffset += uint64(len(plaintext)) + } + if !bytes.Equal(ciphertext, expectedCiphertext) { + panic(fmt.Errorf("vector mismatch @ COUNT = %s:\n %s != %s\n", + count, + hex.EncodeToString(expectedCiphertext), + hex.EncodeToString(ciphertext))) + } +} + +func validateVectors(verifier vectorVerifier, filename string) { + vectors, err := os.Open(filename) + if err != nil { + panic(err) + } + defer vectors.Close() + + var segments []string + var vector *vectorArgs + + scanner := bufio.NewScanner(vectors) + for scanner.Scan() { + segments = strings.Split(scanner.Text(), " = ") + + switch { + case strings.ToUpper(segments[0]) == "COUNT": + if vector != nil { + verifier.validate(vector.count, + vector.offset, + unhexlify(vector.key), + unhexlify(vector.plaintext), + unhexlify(vector.ciphertext)) + } + vector = &vectorArgs{count: segments[1]} + case strings.ToUpper(segments[0]) == "OFFSET": + vector.offset, err = strconv.ParseUint(segments[1], 10, 64) + if err != nil { + panic(err) + } + case strings.ToUpper(segments[0]) == "KEY": + vector.key = segments[1] + case strings.ToUpper(segments[0]) == "PLAINTEXT": + vector.plaintext = segments[1] + case strings.ToUpper(segments[0]) == "CIPHERTEXT": + vector.ciphertext = segments[1] + } + } + if vector != nil { + verifier.validate(vector.count, + vector.offset, + unhexlify(vector.key), + unhexlify(vector.plaintext), + unhexlify(vector.ciphertext)) + } +} + +func main() { + validateVectors(arc4Verifier{}, "vectors/cryptography_vectors/ciphers/ARC4/arc4.txt") + fmt.Println("ARC4 OK.") +} diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/cast5.rst b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/cast5.rst new file mode 100644 index 000000000..97de90166 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/cast5.rst @@ -0,0 +1,31 @@ +CAST5 vector creation +===================== + +This page documents the code that was used to generate the CAST5 CBC, CFB, OFB, +and CTR test vectors as well as the code used to verify them against another +implementation. The CBC, CFB, and OFB vectors were generated using OpenSSL and +the CTR vectors were generated using Apple's CommonCrypto. All the generated +vectors were verified with Go. + +Creation +-------- + +``cryptography`` was modified to support CAST5 in CBC, CFB, and OFB modes. Then +the following Python script was run to generate the vector files. + +.. literalinclude:: /development/custom-vectors/cast5/generate_cast5.py + +Download link: :download:`generate_cast5.py +</development/custom-vectors/cast5/generate_cast5.py>` + + +Verification +------------ + +The following Go code was used to verify the vectors. + +.. literalinclude:: /development/custom-vectors/cast5/verify_cast5.go + :language: go + +Download link: :download:`verify_cast5.go +</development/custom-vectors/cast5/verify_cast5.go>` diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/cast5/generate_cast5.py b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/cast5/generate_cast5.py new file mode 100644 index 000000000..a0e28e36e --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/cast5/generate_cast5.py @@ -0,0 +1,68 @@ +# This file is dual licensed under the terms of the Apache License, Version +# 2.0, and the BSD License. See the LICENSE file in the root of this repository +# for complete details. + +from __future__ import absolute_import, division, print_function + +import binascii + +from cryptography.hazmat.backends import default_backend +from cryptography.hazmat.primitives.ciphers import algorithms, base, modes + + +def encrypt(mode, key, iv, plaintext): + cipher = base.Cipher( + algorithms.CAST5(binascii.unhexlify(key)), + mode(binascii.unhexlify(iv)), + default_backend() + ) + encryptor = cipher.encryptor() + ct = encryptor.update(binascii.unhexlify(plaintext)) + ct += encryptor.finalize() + return binascii.hexlify(ct) + + +def build_vectors(mode, filename): + vector_file = open(filename, "r") + + count = 0 + output = [] + key = None + iv = None + plaintext = None + for line in vector_file: + line = line.strip() + if line.startswith("KEY"): + if count != 0: + output.append("CIPHERTEXT = {}".format( + encrypt(mode, key, iv, plaintext)) + ) + output.append("\nCOUNT = {}".format(count)) + count += 1 + name, key = line.split(" = ") + output.append("KEY = {}".format(key)) + elif line.startswith("IV"): + name, iv = line.split(" = ") + iv = iv[0:16] + output.append("IV = {}".format(iv)) + elif line.startswith("PLAINTEXT"): + name, plaintext = line.split(" = ") + output.append("PLAINTEXT = {}".format(plaintext)) + + output.append("CIPHERTEXT = {}".format(encrypt(mode, key, iv, plaintext))) + return "\n".join(output) + + +def write_file(data, filename): + with open(filename, "w") as f: + f.write(data) + + +cbc_path = "tests/hazmat/primitives/vectors/ciphers/AES/CBC/CBCMMT128.rsp" +write_file(build_vectors(modes.CBC, cbc_path), "cast5-cbc.txt") +ofb_path = "tests/hazmat/primitives/vectors/ciphers/AES/OFB/OFBMMT128.rsp" +write_file(build_vectors(modes.OFB, ofb_path), "cast5-ofb.txt") +cfb_path = "tests/hazmat/primitives/vectors/ciphers/AES/CFB/CFB128MMT128.rsp" +write_file(build_vectors(modes.CFB, cfb_path), "cast5-cfb.txt") +ctr_path = "tests/hazmat/primitives/vectors/ciphers/AES/CTR/aes-128-ctr.txt" +write_file(build_vectors(modes.CTR, ctr_path), "cast5-ctr.txt") diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/cast5/verify_cast5.go b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/cast5/verify_cast5.go new file mode 100644 index 000000000..b2d711a9d --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/cast5/verify_cast5.go @@ -0,0 +1,164 @@ +package main + +import ( + "bufio" + "bytes" + "golang.org/x/crypto/cast5" + "crypto/cipher" + "encoding/hex" + "fmt" + "os" + "strings" +) + +func unhexlify(s string) []byte { + bytes, err := hex.DecodeString(s) + if err != nil { + panic(err) + } + return bytes +} + +type vectorArgs struct { + count string + key string + iv string + plaintext string + ciphertext string +} + +type vectorVerifier interface { + validate(count string, key, iv, plaintext, expectedCiphertext []byte) +} + +type ofbVerifier struct{} + +func (o ofbVerifier) validate(count string, key, iv, plaintext, expectedCiphertext []byte) { + block, err := cast5.NewCipher(key) + if err != nil { + panic(err) + } + + ciphertext := make([]byte, len(plaintext)) + stream := cipher.NewOFB(block, iv) + stream.XORKeyStream(ciphertext, plaintext) + + if !bytes.Equal(ciphertext, expectedCiphertext) { + panic(fmt.Errorf("vector mismatch @ COUNT = %s:\n %s != %s\n", + count, + hex.EncodeToString(expectedCiphertext), + hex.EncodeToString(ciphertext))) + } +} + +type cbcVerifier struct{} + +func (o cbcVerifier) validate(count string, key, iv, plaintext, expectedCiphertext []byte) { + block, err := cast5.NewCipher(key) + if err != nil { + panic(err) + } + + ciphertext := make([]byte, len(plaintext)) + mode := cipher.NewCBCEncrypter(block, iv) + mode.CryptBlocks(ciphertext, plaintext) + + if !bytes.Equal(ciphertext, expectedCiphertext) { + panic(fmt.Errorf("vector mismatch @ COUNT = %s:\n %s != %s\n", + count, + hex.EncodeToString(expectedCiphertext), + hex.EncodeToString(ciphertext))) + } +} + +type cfbVerifier struct{} + +func (o cfbVerifier) validate(count string, key, iv, plaintext, expectedCiphertext []byte) { + block, err := cast5.NewCipher(key) + if err != nil { + panic(err) + } + + ciphertext := make([]byte, len(plaintext)) + stream := cipher.NewCFBEncrypter(block, iv) + stream.XORKeyStream(ciphertext, plaintext) + + if !bytes.Equal(ciphertext, expectedCiphertext) { + panic(fmt.Errorf("vector mismatch @ COUNT = %s:\n %s != %s\n", + count, + hex.EncodeToString(expectedCiphertext), + hex.EncodeToString(ciphertext))) + } +} + +type ctrVerifier struct{} + +func (o ctrVerifier) validate(count string, key, iv, plaintext, expectedCiphertext []byte) { + block, err := cast5.NewCipher(key) + if err != nil { + panic(err) + } + + ciphertext := make([]byte, len(plaintext)) + stream := cipher.NewCTR(block, iv) + stream.XORKeyStream(ciphertext, plaintext) + + if !bytes.Equal(ciphertext, expectedCiphertext) { + panic(fmt.Errorf("vector mismatch @ COUNT = %s:\n %s != %s\n", + count, + hex.EncodeToString(expectedCiphertext), + hex.EncodeToString(ciphertext))) + } +} + +func validateVectors(verifier vectorVerifier, filename string) { + vectors, err := os.Open(filename) + if err != nil { + panic(err) + } + defer vectors.Close() + + var segments []string + var vector *vectorArgs + + scanner := bufio.NewScanner(vectors) + for scanner.Scan() { + segments = strings.Split(scanner.Text(), " = ") + + switch { + case strings.ToUpper(segments[0]) == "COUNT": + if vector != nil { + verifier.validate(vector.count, + unhexlify(vector.key), + unhexlify(vector.iv), + unhexlify(vector.plaintext), + unhexlify(vector.ciphertext)) + } + vector = &vectorArgs{count: segments[1]} + case strings.ToUpper(segments[0]) == "IV": + vector.iv = segments[1][:16] + case strings.ToUpper(segments[0]) == "KEY": + vector.key = segments[1] + case strings.ToUpper(segments[0]) == "PLAINTEXT": + vector.plaintext = segments[1] + case strings.ToUpper(segments[0]) == "CIPHERTEXT": + vector.ciphertext = segments[1] + } + } + +} + +func main() { + validateVectors(ofbVerifier{}, + "vectors/cryptography_vectors/ciphers/CAST5/cast5-ofb.txt") + fmt.Println("OFB OK.") + validateVectors(cfbVerifier{}, + "vectors/cryptography_vectors/ciphers/CAST5/cast5-cfb.txt") + fmt.Println("CFB OK.") + validateVectors(cbcVerifier{}, + "vectors/cryptography_vectors/ciphers/CAST5/cast5-cbc.txt") + fmt.Println("CBC OK.") + validateVectors(ctrVerifier{}, + "vectors/cryptography_vectors/ciphers/CAST5/cast5-ctr.txt") + fmt.Println("CTR OK.") +} diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/hkdf.rst b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/hkdf.rst new file mode 100644 index 000000000..0e1a729ab --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/hkdf.rst @@ -0,0 +1,28 @@ +HKDF vector creation +==================== + +This page documents the code that was used to generate a longer +HKDF test vector (1200 bytes) than is available in RFC 5869. All +the vectors were generated using OpenSSL and verified with Go. + +Creation +-------- + +The following Python script was run to generate the vector files. + +.. literalinclude:: /development/custom-vectors/hkdf/generate_hkdf.py + +Download link: :download:`generate_hkdf.py +</development/custom-vectors/hkdf/generate_hkdf.py>` + + +Verification +------------ + +The following Go code was used to verify the vectors. + +.. literalinclude:: /development/custom-vectors/hkdf/verify_hkdf.go + :language: go + +Download link: :download:`verify_hkdf.go +</development/custom-vectors/hkdf/verify_hkdf.go>` diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/hkdf/generate_hkdf.py b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/hkdf/generate_hkdf.py new file mode 100644 index 000000000..767aedd83 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/hkdf/generate_hkdf.py @@ -0,0 +1,39 @@ +# This file is dual licensed under the terms of the Apache License, Version +# 2.0, and the BSD License. See the LICENSE file in the root of this repository +# for complete details. + +from __future__ import absolute_import, division, print_function + +import binascii + +from cryptography.hazmat.backends import default_backend +from cryptography.hazmat.primitives import hashes +from cryptography.hazmat.primitives.kdf.hkdf import HKDF + +IKM = binascii.unhexlify(b"0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b") +L = 1200 +OKM = HKDF( + algorithm=hashes.SHA256(), length=L, salt=None, info=None, + backend=default_backend() +).derive(IKM) + + +def _build_vectors(): + output = [] + output.append("COUNT = 0") + output.append("Hash = SHA-256") + output.append("IKM = " + binascii.hexlify(IKM).decode("ascii")) + output.append("salt = ") + output.append("info = ") + output.append("L = {}".format(L)) + output.append("OKM = " + binascii.hexlify(OKM).decode("ascii")) + return "\n".join(output) + + +def _write_file(data, filename): + with open(filename, 'w') as f: + f.write(data) + + +if __name__ == '__main__': + _write_file(_build_vectors(), 'hkdf.txt') diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/hkdf/verify_hkdf.go b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/hkdf/verify_hkdf.go new file mode 100644 index 000000000..ddeb3d8e5 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/hkdf/verify_hkdf.go @@ -0,0 +1,69 @@ +package main + +import ( + "bufio" + "bytes" + "crypto/sha256" + "encoding/hex" + "fmt" + "golang.org/x/crypto/hkdf" + "io" + "os" + "strconv" + "strings" +) + +func unhexlify(s string) []byte { + bytes, err := hex.DecodeString(s) + if err != nil { + panic(err) + } + return bytes +} + +func verifier(l uint64, ikm, okm []byte) bool { + hash := sha256.New + hkdf := hkdf.New(hash, ikm, nil, nil) + okmComputed := make([]byte, l) + io.ReadFull(hkdf, okmComputed) + return bytes.Equal(okmComputed, okm) +} + +func validateVectors(filename string) bool { + vectors, err := os.Open(filename) + if err != nil { + panic(err) + } + defer vectors.Close() + + var segments []string + var l uint64 + var ikm, okm string + + scanner := bufio.NewScanner(vectors) + for scanner.Scan() { + segments = strings.Split(scanner.Text(), " = ") + + switch { + case strings.ToUpper(segments[0]) == "L": + l, err = strconv.ParseUint(segments[1], 10, 64) + if err != nil { + panic(err) + } + case strings.ToUpper(segments[0]) == "IKM": + ikm = segments[1] + case strings.ToUpper(segments[0]) == "OKM": + okm = segments[1] + } + } + return verifier(l, unhexlify(ikm), unhexlify(okm)) +} + +func main() { + if validateVectors("vectors/cryptography_vectors/KDF/hkdf-generated.txt") { + fmt.Println("HKDF OK.") + } else { + fmt.Println("HKDF failed.") + os.Exit(1) + } +} diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/idea.rst b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/idea.rst new file mode 100644 index 000000000..758a108ec --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/idea.rst @@ -0,0 +1,32 @@ +IDEA vector creation +===================== + +This page documents the code that was used to generate the IDEA CBC, CFB, and +OFB test vectors as well as the code used to verify them against another +implementation. The vectors were generated using OpenSSL and verified with +`Botan`_. + +Creation +-------- + +``cryptography`` was modified to support IDEA in CBC, CFB, and OFB modes. Then +the following python script was run to generate the vector files. + +.. literalinclude:: /development/custom-vectors/idea/generate_idea.py + +Download link: :download:`generate_idea.py +</development/custom-vectors/idea/generate_idea.py>` + + +Verification +------------ + +The following Python code was used to verify the vectors using the `Botan`_ +project's Python bindings. + +.. literalinclude:: /development/custom-vectors/idea/verify_idea.py + +Download link: :download:`verify_idea.py +</development/custom-vectors/idea/verify_idea.py>` + +.. _`Botan`: https://botan.randombit.net diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/idea/generate_idea.py b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/idea/generate_idea.py new file mode 100644 index 000000000..2eb6996ef --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/idea/generate_idea.py @@ -0,0 +1,61 @@ +import binascii + +from cryptography.hazmat.backends.openssl.backend import backend +from cryptography.hazmat.primitives.ciphers import algorithms, base, modes + + +def encrypt(mode, key, iv, plaintext): + cipher = base.Cipher( + algorithms.IDEA(binascii.unhexlify(key)), + mode(binascii.unhexlify(iv)), + backend + ) + encryptor = cipher.encryptor() + ct = encryptor.update(binascii.unhexlify(plaintext)) + ct += encryptor.finalize() + return binascii.hexlify(ct) + + +def build_vectors(mode, filename): + with open(filename, "r") as f: + vector_file = f.read().splitlines() + + count = 0 + output = [] + key = None + iv = None + plaintext = None + for line in vector_file: + line = line.strip() + if line.startswith("KEY"): + if count != 0: + output.append("CIPHERTEXT = {0}".format( + encrypt(mode, key, iv, plaintext)) + ) + output.append("\nCOUNT = {0}".format(count)) + count += 1 + name, key = line.split(" = ") + output.append("KEY = {0}".format(key)) + elif line.startswith("IV"): + name, iv = line.split(" = ") + iv = iv[0:16] + output.append("IV = {0}".format(iv)) + elif line.startswith("PLAINTEXT"): + name, plaintext = line.split(" = ") + output.append("PLAINTEXT = {0}".format(plaintext)) + + output.append("CIPHERTEXT = {0}".format(encrypt(mode, key, iv, plaintext))) + return "\n".join(output) + + +def write_file(data, filename): + with open(filename, "w") as f: + f.write(data) + + +CBC_PATH = "tests/hazmat/primitives/vectors/ciphers/AES/CBC/CBCMMT128.rsp" +write_file(build_vectors(modes.CBC, CBC_PATH), "idea-cbc.txt") +OFB_PATH = "tests/hazmat/primitives/vectors/ciphers/AES/OFB/OFBMMT128.rsp" +write_file(build_vectors(modes.OFB, OFB_PATH), "idea-ofb.txt") +CFB_PATH = "tests/hazmat/primitives/vectors/ciphers/AES/CFB/CFB128MMT128.rsp" +write_file(build_vectors(modes.CFB, CFB_PATH), "idea-cfb.txt") diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/idea/verify_idea.py b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/idea/verify_idea.py new file mode 100644 index 000000000..89713c801 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/idea/verify_idea.py @@ -0,0 +1,39 @@ +import binascii + +import botan + +from tests.utils import load_nist_vectors + +BLOCK_SIZE = 64 + + +def encrypt(mode, key, iv, plaintext): + encryptor = botan.Cipher("IDEA/{0}/NoPadding".format(mode), "encrypt", + binascii.unhexlify(key)) + + cipher_text = encryptor.cipher(binascii.unhexlify(plaintext), + binascii.unhexlify(iv)) + return binascii.hexlify(cipher_text) + + +def verify_vectors(mode, filename): + with open(filename, "r") as f: + vector_file = f.read().splitlines() + + vectors = load_nist_vectors(vector_file) + for vector in vectors: + ct = encrypt( + mode, + vector["key"], + vector["iv"], + vector["plaintext"] + ) + assert ct == vector["ciphertext"] + + +cbc_path = "tests/hazmat/primitives/vectors/ciphers/IDEA/idea-cbc.txt" +verify_vectors("CBC", cbc_path) +ofb_path = "tests/hazmat/primitives/vectors/ciphers/IDEA/idea-ofb.txt" +verify_vectors("OFB", ofb_path) +cfb_path = "tests/hazmat/primitives/vectors/ciphers/IDEA/idea-cfb.txt" +verify_vectors("CFB", cfb_path) diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/rsa-oaep-sha2.rst b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/rsa-oaep-sha2.rst new file mode 100644 index 000000000..36f256d7c --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/rsa-oaep-sha2.rst @@ -0,0 +1,56 @@ +RSA OAEP SHA2 vector creation +============================= + +This page documents the code that was used to generate the RSA OAEP SHA2 +test vectors as well as code used to verify them against another +implementation. + + +Creation +-------- + +``cryptography`` was modified to allow the use of SHA2 in OAEP encryption. Then +the following python script was run to generate the vector files. + +.. literalinclude:: /development/custom-vectors/rsa-oaep-sha2/generate_rsa_oaep_sha2.py + +Download link: :download:`generate_rsa_oaep_sha2.py +</development/custom-vectors/rsa-oaep-sha2/generate_rsa_oaep_sha2.py>` + + +Verification +------------ + +A Java 8 program was written using `Bouncy Castle`_ to load and verify the test +vectors. + + +.. literalinclude:: /development/custom-vectors/rsa-oaep-sha2/VerifyRSAOAEPSHA2.java + +Download link: :download:`VerifyRSAOAEPSHA2.java +</development/custom-vectors/rsa-oaep-sha2/VerifyRSAOAEPSHA2.java>` + +Using the Verifier +------------------ + +Download and install the `Java 8 SDK`_. Initial verification was performed +using ``jdk-8u77-macosx-x64.dmg``. + +Download the latest `Bouncy Castle`_ JAR. Initial verification was performed +using ``bcprov-jdk15on-154.jar``. + +Set the ``-classpath`` to include the Bouncy Castle jar and the path to +``VerifyRSAOAEPSHA2.java`` and compile the program. + +.. code-block:: console + + $ javac -classpath ~/Downloads/bcprov-jdk15on-154.jar:./ VerifyRSAOAEPSHA2.java + +Finally, run the program with the path to the SHA-2 vectors: + +.. code-block:: console + + $ java -classpath ~/Downloads/bcprov-jdk15on-154.jar:./ VerifyRSAOAEPSHA2 + +.. _`Bouncy Castle`: https://www.bouncycastle.org/ +.. _`Java 8 SDK`: https://www.oracle.com/technetwork/java/javase/downloads/index.html diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/rsa-oaep-sha2/VerifyRSAOAEPSHA2.java b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/rsa-oaep-sha2/VerifyRSAOAEPSHA2.java new file mode 100644 index 000000000..e1bfd3d1e --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/rsa-oaep-sha2/VerifyRSAOAEPSHA2.java @@ -0,0 +1,416 @@ +import java.io.BufferedReader; +import java.io.FileReader; +import java.io.IOException; +import java.math.BigInteger; +import java.security.AlgorithmParameters; +import java.security.GeneralSecurityException; +import java.security.KeyFactory; +import java.security.PrivateKey; +import java.security.Security; +import java.security.spec.AlgorithmParameterSpec; +import java.security.spec.MGF1ParameterSpec; +import java.security.spec.RSAPrivateKeySpec; +import java.util.Arrays; + +import javax.crypto.Cipher; +import javax.crypto.spec.OAEPParameterSpec; +import javax.crypto.spec.PSource; +import javax.xml.bind.DatatypeConverter; + +import org.bouncycastle.jce.provider.BouncyCastleProvider; + +class TestVectorData { + public BigInteger pub_key_modulus; + public BigInteger pub_key_exponent; + public BigInteger priv_key_public_exponent; + public BigInteger priv_key_modulus; + public BigInteger priv_key_exponent; + public BigInteger priv_key_prime_1; + public BigInteger priv_key_prime_2; + public BigInteger priv_key_prime_exponent_1; + public BigInteger priv_key_prime_exponent_2; + public BigInteger priv_key_coefficient; + public byte[] plaintext; + public byte[] ciphertext; +} + +class TestVectorLoader { + private static final String FILE_HEADER = "# RSA OAEP SHA2 vectors built"; + private static final String EXAMPLE_HEADER = "# ====="; + private static final String EXAMPLE = "# Example"; + private static final String PUBLIC_KEY = "# Public key"; + private static final String PUB_MODULUS = "# Modulus:"; + private static final String PUB_EXPONENT = "# Exponent:"; + private static final String PRIVATE_KEY = "# Private key"; + private static final String PRIV_MODULUS = "# Modulus:"; + private static final String PRIV_PUBLIC_EXPONENT = "# Public exponent:"; + private static final String PRIV_EXPONENT = "# Exponent:"; + private static final String PRIV_PRIME_1 = "# Prime 1:"; + private static final String PRIV_PRIME_2 = "# Prime 2:"; + private static final String PRIV_PRIME_EXPONENT_1 = "# Prime exponent 1:"; + private static final String PRIV_PRIME_EXPONENT_2 = "# Prime exponent 2:"; + private static final String PRIV_COEFFICIENT = "# Coefficient:"; + private static final String OAEP_EXAMPLE_HEADER = "# OAEP Example"; + private static final String MESSAGE = "# Message:"; + private static final String ENCRYPTION = "# Encryption:"; + + private BufferedReader m_reader = null; + private FileReader m_file_reader = null; + private TestVectorData m_data = null; + + TestVectorLoader() { + + } + + protected void finalize() { + close(); + } + + public void open(String path) throws IOException { + close(); + m_file_reader = new FileReader(path); + m_reader = new BufferedReader(m_file_reader); + m_data = new TestVectorData(); + } + + public void close() { + try { + if (m_reader != null) { + m_reader.close(); + m_reader = null; + } + if (m_file_reader != null) { + m_file_reader.close(); + m_file_reader = null; + } + m_data = null; + } catch (IOException e) { + System.out.println("Exception closing files"); + e.printStackTrace(); + } + } + + public TestVectorData loadNextTest() throws IOException { + if (m_file_reader == null || m_reader == null || m_data == null) { + throw new IOException("A test vector file must be opened first"); + } + + String line = m_reader.readLine(); + + if (line == null) { + // end of file + return null; + } + + if (line.startsWith(FILE_HEADER)) { + // start of file + skipFileHeader(m_reader); + line = m_reader.readLine(); + } + + if (line.startsWith(OAEP_EXAMPLE_HEADER)) { + // Next example, keep existing keys and load next message + loadMessage(m_reader, m_data); + return m_data; + } + + // otherwise it's a new example + if (!line.startsWith(EXAMPLE_HEADER)) { + throw new IOException("Test Header Missing"); + } + startNewTest(m_reader); + m_data = new TestVectorData(); + + line = m_reader.readLine(); + if (!line.startsWith(PUBLIC_KEY)) + throw new IOException("Public Key Missing"); + loadPublicKey(m_reader, m_data); + + line = m_reader.readLine(); + if (!line.startsWith(PRIVATE_KEY)) + throw new IOException("Private Key Missing"); + loadPrivateKey(m_reader, m_data); + + line = m_reader.readLine(); + if (!line.startsWith(OAEP_EXAMPLE_HEADER)) + throw new IOException("Message Missing"); + loadMessage(m_reader, m_data); + + return m_data; + } + + private byte[] unhexlify(String line) { + byte[] bytes = DatatypeConverter.parseHexBinary(line); + return bytes; + } + + private BigInteger readBigInteger(BufferedReader br) throws IOException { + return new BigInteger(br.readLine(), 16); + } + + private void skipFileHeader(BufferedReader br) throws IOException { + br.readLine(); // # # Derived from the NIST OAEP SHA1 vectors + br.readLine(); // # # Verified against the Bouncy Castle OAEP SHA2 implementation + br.readLine(); // # + } + + private void startNewTest(BufferedReader br) throws IOException { + String line = br.readLine(); + if (!line.startsWith(EXAMPLE)) + throw new IOException("Example Header Missing"); + } + + private void loadPublicKey(BufferedReader br, TestVectorData data) throws IOException { + String line = br.readLine(); + if (!line.startsWith(PUB_MODULUS)) + throw new IOException("Public Key Modulus Missing"); + data.pub_key_modulus = readBigInteger(br); + + line = br.readLine(); + if (!line.startsWith(PUB_EXPONENT)) + throw new IOException("Public Key Exponent Missing"); + data.pub_key_exponent = readBigInteger(br); + } + + private void loadPrivateKey(BufferedReader br, TestVectorData data) throws IOException { + String line = br.readLine(); + if (!line.startsWith(PRIV_MODULUS)) + throw new IOException("Private Key Modulus Missing"); + data.priv_key_modulus = readBigInteger(br); + + line = br.readLine(); + if (!line.startsWith(PRIV_PUBLIC_EXPONENT)) + throw new IOException("Private Key Public Exponent Missing"); + data.priv_key_public_exponent = readBigInteger(br); + + line = br.readLine(); + if (!line.startsWith(PRIV_EXPONENT)) + throw new IOException("Private Key Exponent Missing"); + data.priv_key_exponent = readBigInteger(br); + + line = br.readLine(); + if (!line.startsWith(PRIV_PRIME_1)) + throw new IOException("Private Key Prime 1 Missing"); + data.priv_key_prime_1 = readBigInteger(br); + + line = br.readLine(); + if (!line.startsWith(PRIV_PRIME_2)) + throw new IOException("Private Key Prime 2 Missing"); + data.priv_key_prime_2 = readBigInteger(br); + + line = br.readLine(); + if (!line.startsWith(PRIV_PRIME_EXPONENT_1)) + throw new IOException("Private Key Prime Exponent 1 Missing"); + data.priv_key_prime_exponent_1 = readBigInteger(br); + + line = br.readLine(); + if (!line.startsWith(PRIV_PRIME_EXPONENT_2)) + throw new IOException("Private Key Prime Exponent 2 Missing"); + data.priv_key_prime_exponent_2 = readBigInteger(br); + + line = br.readLine(); + if (!line.startsWith(PRIV_COEFFICIENT)) + throw new IOException("Private Key Coefficient Missing"); + data.priv_key_coefficient = readBigInteger(br); + } + + private void loadMessage(BufferedReader br, TestVectorData data) throws IOException { + String line = br.readLine(); + if (!line.startsWith(MESSAGE)) + throw new IOException("Plaintext Missing"); + data.plaintext = unhexlify(br.readLine()); + + line = br.readLine(); + if (!line.startsWith(ENCRYPTION)) + throw new IOException("Ciphertext Missing"); + data.ciphertext = unhexlify(br.readLine()); + } + +} + +public class VerifyRSAOAEPSHA2 { + + public enum SHAHash { + SHA1, SHA224, SHA256, SHA384, SHA512 + } + + private SHAHash m_mgf1_hash; + private SHAHash m_alg_hash; + private Cipher m_cipher; + private PrivateKey m_private_key; + private AlgorithmParameters m_algo_param; + + VerifyRSAOAEPSHA2(SHAHash mgf1_hash, SHAHash alg_hash, TestVectorData test_data) throws Exception { + + m_mgf1_hash = mgf1_hash; + m_alg_hash = alg_hash; + + MGF1ParameterSpec mgf1_spec = getMGF1ParameterSpec(m_mgf1_hash); + AlgorithmParameterSpec algo_param_spec = getAlgorithmParameterSpec(m_alg_hash, mgf1_spec); + + m_algo_param = AlgorithmParameters.getInstance("OAEP"); + m_algo_param.init(algo_param_spec); + + m_private_key = loadPrivateKey(test_data); + + m_cipher = getCipher(m_alg_hash); + } + + private Cipher getCipher(SHAHash alg_hash) throws GeneralSecurityException { + Cipher cipher = null; + + switch (alg_hash) { + + case SHA1: + cipher = Cipher.getInstance("RSA/ECB/OAEPwithSHA1andMGF1Padding", "BC"); + break; + + case SHA224: + cipher = Cipher.getInstance("RSA/ECB/OAEPwithSHA-224andMGF1Padding", "BC"); + break; + + case SHA256: + cipher = Cipher.getInstance("RSA/ECB/OAEPwithSHA-256andMGF1Padding", "BC"); + break; + + case SHA384: + cipher = Cipher.getInstance("RSA/ECB/OAEPwithSHA-384andMGF1Padding", "BC"); + break; + + case SHA512: + cipher = Cipher.getInstance("RSA/ECB/OAEPwithSHA-512andMGF1Padding", "BC"); + break; + } + + return cipher; + } + + private MGF1ParameterSpec getMGF1ParameterSpec(SHAHash mgf1_hash) { + MGF1ParameterSpec mgf1 = null; + + switch (mgf1_hash) { + + case SHA1: + mgf1 = MGF1ParameterSpec.SHA1; + break; + case SHA224: + mgf1 = MGF1ParameterSpec.SHA224; + break; + + case SHA256: + mgf1 = MGF1ParameterSpec.SHA256; + break; + + case SHA384: + mgf1 = MGF1ParameterSpec.SHA384; + break; + + case SHA512: + mgf1 = MGF1ParameterSpec.SHA512; + break; + } + + return mgf1; + } + + private AlgorithmParameterSpec getAlgorithmParameterSpec(SHAHash alg_hash, MGF1ParameterSpec mgf1_spec) { + + OAEPParameterSpec oaep_spec = null; + + switch (alg_hash) { + + case SHA1: + oaep_spec = new OAEPParameterSpec("SHA1", "MGF1", mgf1_spec, PSource.PSpecified.DEFAULT); + break; + + case SHA224: + oaep_spec = new OAEPParameterSpec("SHA-224", "MGF1", mgf1_spec, PSource.PSpecified.DEFAULT); + break; + + case SHA256: + oaep_spec = new OAEPParameterSpec("SHA-256", "MGF1", mgf1_spec, PSource.PSpecified.DEFAULT); + break; + + case SHA384: + oaep_spec = new OAEPParameterSpec("SHA-384", "MGF1", mgf1_spec, PSource.PSpecified.DEFAULT); + break; + + case SHA512: + oaep_spec = new OAEPParameterSpec("SHA-512", "MGF1", mgf1_spec, PSource.PSpecified.DEFAULT); + break; + } + + return oaep_spec; + } + + private PrivateKey loadPrivateKey(TestVectorData test_data) throws Exception { + KeyFactory kf = KeyFactory.getInstance("RSA"); + + RSAPrivateKeySpec keySpec = new RSAPrivateKeySpec(test_data.priv_key_modulus, test_data.priv_key_exponent); + + return kf.generatePrivate(keySpec); + } + + public void testDecrypt(byte[] plaintext, byte[] ciphertext) throws Exception { + System.out.println("Verifying OAEP with mgf1_hash: " + m_mgf1_hash + " alg_hash: " + m_alg_hash + " - " + + ciphertext.length + " bytes ciphertext - " + + plaintext.length + " bytes plaintext"); + + m_cipher.init(Cipher.DECRYPT_MODE, m_private_key, m_algo_param); + byte[] java_plaintext = m_cipher.doFinal(ciphertext); + + if (Arrays.equals(java_plaintext, plaintext) == false) { + throw new Exception("Verification failure - plaintext does not match after decryption."); + } + } + + public static void main(String[] args) { + Security.addProvider(new BouncyCastleProvider()); + + // assume current directory if no path given on command line + String vector_path = "./vectors/cryptography_vectors/asymmetric/RSA/oaep-custom"; + + if (args.length > 0) { + vector_path = args[0]; + } + + System.out.println("Vector file path: " + vector_path); + + try { + // loop over each combination of hash loading the vector file + // to verify for each + for (SHAHash mgf1_hash : SHAHash.values()) { + for (SHAHash alg_hash : SHAHash.values()) { + if (mgf1_hash.name().toLowerCase().equals("sha1") && + alg_hash.name().toLowerCase().equals("sha1")) { + continue; + } + String filename = "oaep-" + mgf1_hash.name().toLowerCase() + + "-" + alg_hash.name().toLowerCase() + ".txt"; + + System.out.println("Loading " + filename + "..."); + + TestVectorLoader loader = new TestVectorLoader(); + loader.open(vector_path + filename); + + TestVectorData test_data; + + // load each test in the file and verify + while ((test_data = loader.loadNextTest()) != null) { + VerifyRSAOAEPSHA2 verify = new VerifyRSAOAEPSHA2(mgf1_hash, alg_hash, test_data); + verify.testDecrypt(test_data.plaintext, test_data.ciphertext); + } + + System.out.println("Verifying " + filename + " completed successfully."); + } + } + + System.out.println("All verification completed successfully"); + + } catch (Exception e) { + // if any exception is thrown the verification has failed + e.printStackTrace(); + System.out.println("Verification Failed!"); + } + } +} diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/rsa-oaep-sha2/generate_rsa_oaep_sha2.py b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/rsa-oaep-sha2/generate_rsa_oaep_sha2.py new file mode 100644 index 000000000..bd5148f54 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/rsa-oaep-sha2/generate_rsa_oaep_sha2.py @@ -0,0 +1,128 @@ +# This file is dual licensed under the terms of the Apache License, Version +# 2.0, and the BSD License. See the LICENSE file in the root of this repository +# for complete details. + +from __future__ import absolute_import, division, print_function + +import binascii +import itertools +import os + +from cryptography.hazmat.backends.openssl.backend import backend +from cryptography.hazmat.primitives import hashes +from cryptography.hazmat.primitives.asymmetric import padding, rsa + +from tests.utils import load_pkcs1_vectors, load_vectors_from_file + + +def build_vectors(mgf1alg, hashalg, filename): + vectors = load_vectors_from_file(filename, load_pkcs1_vectors) + + output = [] + for vector in vectors: + # RSA keys for this must be long enough to accommodate the length of + # the underlying hash function. This means we can't use the keys from + # the sha1 test vectors for sha512 tests because 1024-bit keys are too + # small. Instead we parse the vectors for the test cases, then + # generate our own 2048-bit keys for each. + private, _ = vector + skey = rsa.generate_private_key(65537, 2048, backend) + pn = skey.private_numbers() + examples = private["examples"] + output.append(b"# =============================================") + output.append(b"# Example") + output.append(b"# Public key") + output.append(b"# Modulus:") + output.append(format(pn.public_numbers.n, "x")) + output.append(b"# Exponent:") + output.append(format(pn.public_numbers.e, "x")) + output.append(b"# Private key") + output.append(b"# Modulus:") + output.append(format(pn.public_numbers.n, "x")) + output.append(b"# Public exponent:") + output.append(format(pn.public_numbers.e, "x")) + output.append(b"# Exponent:") + output.append(format(pn.d, "x")) + output.append(b"# Prime 1:") + output.append(format(pn.p, "x")) + output.append(b"# Prime 2:") + output.append(format(pn.q, "x")) + output.append(b"# Prime exponent 1:") + output.append(format(pn.dmp1, "x")) + output.append(b"# Prime exponent 2:") + output.append(format(pn.dmq1, "x")) + output.append(b"# Coefficient:") + output.append(format(pn.iqmp, "x")) + pkey = skey.public_key() + vectorkey = rsa.RSAPrivateNumbers( + p=private["p"], + q=private["q"], + d=private["private_exponent"], + dmp1=private["dmp1"], + dmq1=private["dmq1"], + iqmp=private["iqmp"], + public_numbers=rsa.RSAPublicNumbers( + e=private["public_exponent"], + n=private["modulus"] + ) + ).private_key(backend) + count = 1 + + for example in examples: + message = vectorkey.decrypt( + binascii.unhexlify(example["encryption"]), + padding.OAEP( + mgf=padding.MGF1(algorithm=hashes.SHA1()), + algorithm=hashes.SHA1(), + label=None + ) + ) + assert message == binascii.unhexlify(example["message"]) + ct = pkey.encrypt( + message, + padding.OAEP( + mgf=padding.MGF1(algorithm=mgf1alg), + algorithm=hashalg, + label=None + ) + ) + output.append( + b"# OAEP Example {0} alg={1} mgf1={2}".format( + count, hashalg.name, mgf1alg.name + ) + ) + count += 1 + output.append(b"# Message:") + output.append(example["message"]) + output.append(b"# Encryption:") + output.append(binascii.hexlify(ct)) + + return b"\n".join(output) + + +def write_file(data, filename): + with open(filename, "w") as f: + f.write(data) + + +oaep_path = os.path.join( + "asymmetric", "RSA", "pkcs-1v2-1d2-vec", "oaep-vect.txt" +) +hashalgs = [ + hashes.SHA1(), + hashes.SHA224(), + hashes.SHA256(), + hashes.SHA384(), + hashes.SHA512(), +] +for hashtuple in itertools.product(hashalgs, hashalgs): + if ( + isinstance(hashtuple[0], hashes.SHA1) and + isinstance(hashtuple[1], hashes.SHA1) + ): + continue + + write_file( + build_vectors(hashtuple[0], hashtuple[1], oaep_path), + "oaep-{0}-{1}.txt".format(hashtuple[0].name, hashtuple[1].name) + ) diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/secp256k1.rst b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/secp256k1.rst new file mode 100644 index 000000000..e0579b4fb --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/secp256k1.rst @@ -0,0 +1,32 @@ +SECP256K1 vector creation +========================= + +This page documents the code that was used to generate the SECP256K1 elliptic +curve test vectors as well as code used to verify them against another +implementation. + + +Creation +-------- + +The vectors are generated using a `pure Python ecdsa`_ implementation. The test +messages and combinations of algorithms are derived from the NIST vector data. + +.. literalinclude:: /development/custom-vectors/secp256k1/generate_secp256k1.py + +Download link: :download:`generate_secp256k1.py +</development/custom-vectors/secp256k1/generate_secp256k1.py>` + + +Verification +------------ + +``cryptography`` was modified to support the SECP256K1 curve. Then +the following python script was run to generate the vector files. + +.. literalinclude:: /development/custom-vectors/secp256k1/verify_secp256k1.py + +Download link: :download:`verify_secp256k1.py +</development/custom-vectors/secp256k1/verify_secp256k1.py>` + +.. _`pure Python ecdsa`: https://pypi.org/project/ecdsa/ diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/secp256k1/generate_secp256k1.py b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/secp256k1/generate_secp256k1.py new file mode 100644 index 000000000..d6a2071ac --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/secp256k1/generate_secp256k1.py @@ -0,0 +1,90 @@ +from __future__ import absolute_import, print_function + +import hashlib +import os +from binascii import hexlify +from collections import defaultdict + +from ecdsa import SECP256k1, SigningKey +from ecdsa.util import sigdecode_der, sigencode_der + +from cryptography_vectors import open_vector_file + +from tests.utils import ( + load_fips_ecdsa_signing_vectors, load_vectors_from_file +) + +HASHLIB_HASH_TYPES = { + "SHA-1": hashlib.sha1, + "SHA-224": hashlib.sha224, + "SHA-256": hashlib.sha256, + "SHA-384": hashlib.sha384, + "SHA-512": hashlib.sha512, +} + + +class TruncatedHash(object): + def __init__(self, hasher): + self.hasher = hasher + + def __call__(self, data): + self.hasher.update(data) + return self + + def digest(self): + return self.hasher.digest()[:256 // 8] + + +def build_vectors(fips_vectors): + vectors = defaultdict(list) + for vector in fips_vectors: + vectors[vector['digest_algorithm']].append(vector['message']) + + for digest_algorithm, messages in vectors.items(): + if digest_algorithm not in HASHLIB_HASH_TYPES: + continue + + yield "" + yield "[K-256,{0}]".format(digest_algorithm) + yield "" + + for message in messages: + # Make a hash context + hash_func = TruncatedHash(HASHLIB_HASH_TYPES[digest_algorithm]()) + + # Sign the message using warner/ecdsa + secret_key = SigningKey.generate(curve=SECP256k1) + public_key = secret_key.get_verifying_key() + signature = secret_key.sign(message, hashfunc=hash_func, + sigencode=sigencode_der) + + r, s = sigdecode_der(signature, None) + + yield "Msg = {0}".format(hexlify(message)) + yield "d = {0:x}".format(secret_key.privkey.secret_multiplier) + yield "Qx = {0:x}".format(public_key.pubkey.point.x()) + yield "Qy = {0:x}".format(public_key.pubkey.point.y()) + yield "R = {0:x}".format(r) + yield "S = {0:x}".format(s) + yield "" + + +def write_file(lines, dest): + for line in lines: + print(line) + print(line, file=dest) + + +source_path = os.path.join("asymmetric", "ECDSA", "FIPS_186-3", "SigGen.txt") +dest_path = os.path.join("asymmetric", "ECDSA", "SECP256K1", "SigGen.txt") + +fips_vectors = load_vectors_from_file( + source_path, + load_fips_ecdsa_signing_vectors +) + +with open_vector_file(dest_path, "w") as dest_file: + write_file( + build_vectors(fips_vectors), + dest_file + ) diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/secp256k1/verify_secp256k1.py b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/secp256k1/verify_secp256k1.py new file mode 100644 index 000000000..b236d77fc --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/secp256k1/verify_secp256k1.py @@ -0,0 +1,59 @@ +from __future__ import absolute_import, print_function + +import os + +from cryptography.hazmat.backends import default_backend +from cryptography.hazmat.primitives import hashes +from cryptography.hazmat.primitives.asymmetric import ec +from cryptography.hazmat.primitives.asymmetric.utils import ( + encode_dss_signature +) + +from tests.utils import ( + load_fips_ecdsa_signing_vectors, load_vectors_from_file +) + +CRYPTOGRAPHY_HASH_TYPES = { + "SHA-1": hashes.SHA1, + "SHA-224": hashes.SHA224, + "SHA-256": hashes.SHA256, + "SHA-384": hashes.SHA384, + "SHA-512": hashes.SHA512, +} + + +def verify_one_vector(vector): + digest_algorithm = vector['digest_algorithm'] + message = vector['message'] + x = vector['x'] + y = vector['y'] + signature = encode_dss_signature(vector['r'], vector['s']) + + numbers = ec.EllipticCurvePublicNumbers( + x, y, + ec.SECP256K1() + ) + + key = numbers.public_key(default_backend()) + + verifier = key.verifier( + signature, + ec.ECDSA(CRYPTOGRAPHY_HASH_TYPES[digest_algorithm]()) + ) + verifier.update(message) + return verifier.verify() + + +def verify_vectors(vectors): + for vector in vectors: + assert verify_one_vector(vector) + + +vector_path = os.path.join("asymmetric", "ECDSA", "SECP256K1", "SigGen.txt") + +secp256k1_vectors = load_vectors_from_file( + vector_path, + load_fips_ecdsa_signing_vectors +) + +verify_vectors(secp256k1_vectors) diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/seed.rst b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/seed.rst new file mode 100644 index 000000000..8c4a7aabd --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/seed.rst @@ -0,0 +1,32 @@ +SEED vector creation +===================== + +This page documents the code that was used to generate the SEED CFB and OFB +test vectors as well as the code used to verify them against another +implementation. The vectors were generated using OpenSSL and verified +with `Botan`_. + +Creation +-------- + +``cryptography`` was modified to support SEED in CFB and OFB modes. Then +the following python script was run to generate the vector files. + +.. literalinclude:: /development/custom-vectors/seed/generate_seed.py + +Download link: :download:`generate_seed.py +</development/custom-vectors/seed/generate_seed.py>` + + +Verification +------------ + +The following Python code was used to verify the vectors using the `Botan`_ +project's Python bindings. + +.. literalinclude:: /development/custom-vectors/seed/verify_seed.py + +Download link: :download:`verify_seed.py +</development/custom-vectors/seed/verify_seed.py>` + +.. _`Botan`: https://botan.randombit.net diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/seed/generate_seed.py b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/seed/generate_seed.py new file mode 100644 index 000000000..5c62d6713 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/seed/generate_seed.py @@ -0,0 +1,58 @@ +import binascii + +from cryptography.hazmat.backends.openssl.backend import backend +from cryptography.hazmat.primitives.ciphers import algorithms, base, modes + + +def encrypt(mode, key, iv, plaintext): + cipher = base.Cipher( + algorithms.SEED(binascii.unhexlify(key)), + mode(binascii.unhexlify(iv)), + backend + ) + encryptor = cipher.encryptor() + ct = encryptor.update(binascii.unhexlify(plaintext)) + ct += encryptor.finalize() + return binascii.hexlify(ct) + + +def build_vectors(mode, filename): + with open(filename, "r") as f: + vector_file = f.read().splitlines() + + count = 0 + output = [] + key = None + iv = None + plaintext = None + for line in vector_file: + line = line.strip() + if line.startswith("KEY"): + if count != 0: + output.append("CIPHERTEXT = {0}".format( + encrypt(mode, key, iv, plaintext)) + ) + output.append("\nCOUNT = {0}".format(count)) + count += 1 + name, key = line.split(" = ") + output.append("KEY = {0}".format(key)) + elif line.startswith("IV"): + name, iv = line.split(" = ") + output.append("IV = {0}".format(iv)) + elif line.startswith("PLAINTEXT"): + name, plaintext = line.split(" = ") + output.append("PLAINTEXT = {0}".format(plaintext)) + + output.append("CIPHERTEXT = {0}".format(encrypt(mode, key, iv, plaintext))) + return "\n".join(output) + + +def write_file(data, filename): + with open(filename, "w") as f: + f.write(data) + + +OFB_PATH = "vectors/cryptography_vectors/ciphers/AES/OFB/OFBMMT128.rsp" +write_file(build_vectors(modes.OFB, OFB_PATH), "seed-ofb.txt") +CFB_PATH = "vectors/cryptography_vectors/ciphers/AES/CFB/CFB128MMT128.rsp" +write_file(build_vectors(modes.CFB, CFB_PATH), "seed-cfb.txt") diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/seed/verify_seed.py b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/seed/verify_seed.py new file mode 100644 index 000000000..e626428cb --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/custom-vectors/seed/verify_seed.py @@ -0,0 +1,35 @@ +import binascii + +import botan + +from tests.utils import load_nist_vectors + + +def encrypt(mode, key, iv, plaintext): + encryptor = botan.Cipher("SEED/{0}/NoPadding".format(mode), "encrypt", + binascii.unhexlify(key)) + + cipher_text = encryptor.cipher(binascii.unhexlify(plaintext), + binascii.unhexlify(iv)) + return binascii.hexlify(cipher_text) + + +def verify_vectors(mode, filename): + with open(filename, "r") as f: + vector_file = f.read().splitlines() + + vectors = load_nist_vectors(vector_file) + for vector in vectors: + ct = encrypt( + mode, + vector["key"], + vector["iv"], + vector["plaintext"] + ) + assert ct == vector["ciphertext"] + + +ofb_path = "vectors/cryptography_vectors/ciphers/SEED/seed-ofb.txt" +verify_vectors("OFB", ofb_path) +cfb_path = "vectors/cryptography_vectors/ciphers/SEED/seed-cfb.txt" +verify_vectors("CFB", cfb_path) diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/getting-started.rst b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/getting-started.rst new file mode 100644 index 000000000..953ae9597 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/getting-started.rst @@ -0,0 +1,115 @@ +Getting started +=============== + +Development dependencies +------------------------ +Working on ``cryptography`` requires the installation of a small number of +development dependencies in addition to the dependencies for +:doc:`/installation`. These are listed in ``dev-requirements.txt`` and they can +be installed in a `virtualenv`_ using `pip`_. Before you install them, follow +the **build** instructions in :doc:`/installation` (be sure to stop before +actually installing ``cryptography``). Once you've done that, install the +development dependencies, and then install ``cryptography`` in ``editable`` +mode. For example: + +.. code-block:: console + + $ # Create a virtualenv and activate it + $ # Set up your cryptography build environment + $ pip install --requirement dev-requirements.txt + $ pip install --editable . + +You will also need to install ``enchant`` using your system's package manager +to check spelling in the documentation. + +.. note:: + There is an upstream bug in ``enchant`` that prevents its installation on + Windows with 64-bit Python. See `this Github issue`_ for more information. + The easiest workaround is to use 32-bit Python for ``cryptography`` + development, even on 64-bit Windows. + +You are now ready to run the tests and build the documentation. + +OpenSSL on macOS +~~~~~~~~~~~~~~~~ + +You must have installed `OpenSSL`_ via `Homebrew`_ or `MacPorts`_ and must set +``CFLAGS`` and ``LDFLAGS`` environment variables before installing the +``dev-requirements.txt`` otherwise pip will fail with include errors. + +For example, with `Homebrew`_: + +.. code-block:: console + + $ env LDFLAGS="-L$(brew --prefix openssl@1.1)/lib" \ + CFLAGS="-I$(brew --prefix openssl@1.1)/include" \ + pip install --requirement ./dev-requirements.txt + +Alternatively for a static build you can specify +``CRYPTOGRAPHY_SUPPRESS_LINK_FLAGS=1`` and ensure ``LDFLAGS`` points to the +absolute path for the `OpenSSL`_ libraries before calling pip. + +.. tip:: + You will also need to set these values when `Building documentation`_. + +Running tests +------------- + +``cryptography`` unit tests are found in the ``tests/`` directory and are +designed to be run using `pytest`_. `pytest`_ will discover the tests +automatically, so all you have to do is: + +.. code-block:: console + + $ pytest + ... + 62746 passed in 220.43 seconds + +This runs the tests with the default Python interpreter. + +You can also verify that the tests pass on other supported Python interpreters. +For this we use `tox`_, which will automatically create a `virtualenv`_ for +each supported Python version and run the tests. For example: + +.. code-block:: console + + $ tox + ... + py27: commands succeeded + ERROR: pypy: InterpreterNotFound: pypy + py34: commands succeeded + docs: commands succeeded + pep8: commands succeeded + +You may not have all the required Python versions installed, in which case you +will see one or more ``InterpreterNotFound`` errors. + + +Building documentation +---------------------- + +``cryptography`` documentation is stored in the ``docs/`` directory. It is +written in `reStructured Text`_ and rendered using `Sphinx`_. + +Use `tox`_ to build the documentation. For example: + +.. code-block:: console + + $ tox -e docs + ... + docs: commands succeeded + congratulations :) + +The HTML documentation index can now be found at +``docs/_build/html/index.html``. + +.. _`Homebrew`: https://brew.sh +.. _`MacPorts`: https://www.macports.org +.. _`OpenSSL`: https://www.openssl.org +.. _`pytest`: https://pypi.org/project/pytest/ +.. _`tox`: https://pypi.org/project/tox/ +.. _`virtualenv`: https://pypi.org/project/virtualenv/ +.. _`pip`: https://pypi.org/project/pip/ +.. _`sphinx`: https://pypi.org/project/Sphinx/ +.. _`reStructured Text`: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html +.. _`this Github issue`: https://github.com/rfk/pyenchant/issues/42 diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/index.rst b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/index.rst new file mode 100644 index 000000000..f9bc9eea8 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/index.rst @@ -0,0 +1,20 @@ +Development +=========== + +As an open source project, ``cryptography`` welcomes contributions of all +forms. The sections below will help you get started. + +File bugs and feature requests on our issue tracker on `GitHub`_. If it is a +bug check out `what to put in your bug report`_. + +.. toctree:: + :maxdepth: 2 + + getting-started + submitting-patches + reviewing-patches + test-vectors + c-bindings + +.. _`GitHub`: https://github.com/pyca/cryptography +.. _`what to put in your bug report`: http://www.contribution-guide.org/#what-to-put-in-your-bug-report diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/reviewing-patches.rst b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/reviewing-patches.rst new file mode 100644 index 000000000..bd3ee96ac --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/reviewing-patches.rst @@ -0,0 +1,60 @@ +Reviewing and merging patches +============================= + +Everyone is encouraged to review open pull requests. We only ask that you try +and think carefully, ask questions and are `excellent to one another`_. Code +review is our opportunity to share knowledge, design ideas and make friends. + +When reviewing a patch try to keep each of these concepts in mind: + +Architecture +------------ + +* Is the proposed change being made in the correct place? Is it a fix in a + backend when it should be in the primitives? + +Intent +------ + +* What is the change being proposed? +* Do we want this feature or is the bug they're fixing really a bug? + +Implementation +-------------- + +* Does the change do what the author claims? +* Are there sufficient tests? +* Has it been documented? +* Will this change introduce new bugs? + +Grammar and style +----------------- + +These are small things that are not caught by the automated style checkers. + +* Does a variable need a better name? +* Should this be a keyword argument? + +Merge requirements +------------------ + +Because cryptography is so complex, and the implications of getting it wrong so +devastating, ``cryptography`` has a strict merge policy for committers: + +* Patches must *never* be pushed directly to ``master``, all changes (even the + most trivial typo fixes!) must be submitted as a pull request. +* A committer may *never* merge their own pull request, a second party must + merge their changes. If multiple people work on a pull request, it must be + merged by someone who did not work on it. +* A patch that breaks tests, or introduces regressions by changing or removing + existing tests should not be merged. Tests must always be passing on + ``master``. +* If somehow the tests get into a failing state on ``master`` (such as by a + backwards incompatible release of a dependency) no pull requests may be + merged until this is rectified. +* All merged patches must have 100% test coverage. + +The purpose of these policies is to minimize the chances we merge a change +that jeopardizes our users' security. + +.. _`excellent to one another`: https://speakerdeck.com/ohrite/better-code-review diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/submitting-patches.rst b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/submitting-patches.rst new file mode 100644 index 000000000..2e9bb0fd6 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/submitting-patches.rst @@ -0,0 +1,161 @@ +Submitting patches +================== + +* Always make a new branch for your work. +* Patches should be small to facilitate easier review. `Studies have shown`_ + that review quality falls off as patch size grows. Sometimes this will result + in many small PRs to land a single large feature. +* Larger changes should be discussed on `our mailing list`_ before submission. +* New features and significant bug fixes should be documented in the + :doc:`/changelog`. +* You must have legal permission to distribute any code you contribute to + ``cryptography``, and it must be available under both the BSD and Apache + Software License Version 2.0 licenses. + +If you believe you've identified a security issue in ``cryptography``, please +follow the directions on the :doc:`security page </security>`. + +Code +---- + +When in doubt, refer to :pep:`8` for Python code. You can check if your code +meets our automated requirements by running ``flake8`` against it. If you've +installed the development requirements this will automatically use our +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 + + # This file is dual licensed under the terms of the Apache License, Version + # 2.0, and the BSD License. See the LICENSE file in the root of this repository + # for complete details. + +Additionally, every Python code file must contain + +.. code-block:: python + + from __future__ import absolute_import, division, print_function + +API considerations +~~~~~~~~~~~~~~~~~~ + +Most projects' APIs are designed with a philosophy of "make easy things easy, +and make hard things possible". One of the perils of writing cryptographic code +is that secure code looks just like insecure code, and its results are almost +always indistinguishable. As a result, ``cryptography`` has, as a design +philosophy: "make it hard to do insecure things". Here are a few strategies for +API design that should be both followed, and should inspire other API choices: + +If it is necessary to compare a user provided value with a computed value (for +example, verifying a signature), there should be an API provided that performs +the verification in a secure way (for example, using a constant time +comparison), rather than requiring the user to perform the comparison +themselves. + +If it is incorrect to ignore the result of a method, it should raise an +exception, and not return a boolean ``True``/``False`` flag. For example, a +method to verify a signature should raise ``InvalidSignature``, and not return +whether the signature was valid. + +.. code-block:: python + + # This is bad. + def verify(sig): + # ... + return is_valid + + # Good! + def verify(sig): + # ... + if not is_valid: + raise InvalidSignature + +Every recipe should include a version or algorithmic marker of some sort in its +output in order to allow transparent upgrading of the algorithms in use, as +the algorithms or parameters needed to achieve a given security margin evolve. + +APIs at the :doc:`/hazmat/primitives/index` layer should always take an +explicit backend, APIs at the recipes layer should automatically use the +:func:`~cryptography.hazmat.backends.default_backend`, but optionally allow +specifying a different backend. + +C bindings +~~~~~~~~~~ + +More information on C bindings can be found in :doc:`the dedicated +section of the documentation <c-bindings>`. + +Tests +----- + +All code changes must be accompanied by unit tests with 100% code coverage (as +measured by the combined metrics across our build matrix). + +When implementing a new primitive or recipe ``cryptography`` requires that you +provide a set of test vectors. See :doc:`/development/test-vectors` for more +details. + +Documentation +------------- + +All features should be documented with prose in the ``docs`` section. To ensure +it builds and passes `doc8`_ style checks you can run ``tox -e docs``. + +Because of the inherent challenges in implementing correct cryptographic +systems, we want to make our documentation point people in the right directions +as much as possible. To that end: + +* When documenting a generic interface, use a strong algorithm in examples. + (e.g. when showing a hashing example, don't use + :class:`~cryptography.hazmat.primitives.hashes.MD5`) +* When giving prescriptive advice, always provide references and supporting + material. +* When there is real disagreement between cryptographic experts, represent both + sides of the argument and describe the trade-offs clearly. + +When documenting a new module in the ``hazmat`` package, its documentation +should begin with the "Hazardous Materials" warning: + +.. code-block:: rest + + .. hazmat:: + +Always prefer terminology that is most broadly accepted. For example: + +* When referring to class instances use "an instance of ``Foo``" + instead of "a ``Foo`` provider". + +When referring to a hypothetical individual (such as "a person receiving an +encrypted message") use gender neutral pronouns (they/them/their). + +Docstrings are typically only used when writing abstract classes, but should +be written like this if required: + +.. code-block:: python + + def some_function(some_arg): + """ + Does some things. + + :param some_arg: Some argument. + """ + +So, specifically: + +* Always use three double quotes. +* Put the three double quotes on their own line. +* No blank line at the end. +* Use Sphinx parameter/attribute documentation `syntax`_. + + +.. _`Write comments as complete sentences.`: https://nedbatchelder.com/blog/201401/comments_should_be_sentences.html +.. _`syntax`: http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists +.. _`Studies have shown`: https://smartbear.com/SmartBear/media/pdfs/11_Best_Practices_for_Peer_Code_Review.pdf +.. _`our mailing list`: https://mail.python.org/mailman/listinfo/cryptography-dev +.. _`doc8`: https://github.com/openstack/doc8 diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/test-vectors.rst b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/test-vectors.rst new file mode 100644 index 000000000..b56a4c563 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/test-vectors.rst @@ -0,0 +1,590 @@ +Test vectors +============ + +Testing the correctness of the primitives implemented in each ``cryptography`` +backend requires trusted test vectors. Where possible these vectors are +obtained from official sources such as `NIST`_ or `IETF`_ RFCs. When this is +not possible ``cryptography`` has chosen to create a set of custom vectors +using an official vector file as input to verify consistency between +implemented backends. + +Vectors are kept in the ``cryptography_vectors`` package rather than within our +main test suite. + +Sources +------- + +Project Wycheproof +~~~~~~~~~~~~~~~~~~ + +We run vectors from `Project Wycheproof`_ -- a collection of known edge-cases +for various cryptographic algorithms. These are not included in the repository +(or ``cryptography_vectors`` package), but rather cloned from Git in our +continuous integration environments. + +We have ensured all test vectors are used as of commit +``f89f4c53a8845fcefcdb9f14ee9191dbe167e3e3``. + +Asymmetric ciphers +~~~~~~~~~~~~~~~~~~ + +* RSA PKCS #1 from the RSA FTP site (ftp://ftp.rsasecurity.com/pub/pkcs/pkcs-1/ + and ftp://ftp.rsa.com/pub/rsalabs/tmp/). +* 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 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`_. +* OpenSSL PEM DSA serialization vectors from the `GnuTLS example keys`_. +* PKCS #8 PEM serialization vectors from + + * GnuTLS: `enc-rsa-pkcs8.pem`_, `enc2-rsa-pkcs8.pem`_, + `unenc-rsa-pkcs8.pem`_, `pkcs12_s2k_pem.c`_. The encoding error in + `unenc-rsa-pkcs8.pem`_ was fixed, and the contents of `enc-rsa-pkcs8.pem`_ + was re-encrypted to include it. The contents of `enc2-rsa-pkcs8.pem`_ + was re-encrypted using a stronger PKCS#8 cipher. + * `Botan's ECC private keys`_. +* `asymmetric/public/PKCS1/dsa.pub.pem`_ is a PKCS1 DSA public key from the + Ruby test suite. +* X25519 test vectors from :rfc:`7748`. +* RSA OAEP with custom label from the `BoringSSL evp tests`_. + + +Custom asymmetric vectors +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + custom-vectors/secp256k1 + custom-vectors/rsa-oaep-sha2 + +* ``asymmetric/PEM_Serialization/ec_private_key.pem`` and + ``asymmetric/DER_Serialization/ec_private_key.der`` - Contains an Elliptic + Curve key generated by OpenSSL from the curve ``secp256r1``. +* ``asymmetric/PEM_Serialization/ec_private_key_encrypted.pem`` and + ``asymmetric/DER_Serialization/ec_private_key_encrypted.der``- Contains the + same Elliptic Curve key as ``ec_private_key.pem``, except that it is + encrypted with AES-128 with the password "123456". +* ``asymmetric/PEM_Serialization/ec_public_key.pem`` and + ``asymmetric/DER_Serialization/ec_public_key.der``- Contains the public key + corresponding to ``ec_private_key.pem``, generated using OpenSSL. +* ``asymmetric/PEM_Serialization/rsa_private_key.pem`` - Contains an RSA 2048 + bit key generated using OpenSSL, protected by the secret "123456" with DES3 + encryption. +* ``asymmetric/PEM_Serialization/rsa_public_key.pem`` and + ``asymmetric/DER_Serialization/rsa_public_key.der``- Contains an RSA 2048 + bit public generated using OpenSSL from ``rsa_private_key.pem``. +* ``asymmetric/PEM_Serialization/dsaparam.pem`` - Contains 2048-bit DSA + parameters generated using OpenSSL; contains no keys. +* ``asymmetric/PEM_Serialization/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. +* ``asymmetric/PEM_Serialization/dsa_public_key.pem`` and + ``asymmetric/DER_Serialization/dsa_public_key.der`` - Contains a DSA 2048 bit + key generated using OpenSSL from ``dsa_private_key.pem``. +* ``asymmetric/PKCS8/unenc-dsa-pkcs8.pem`` and + ``asymmetric/DER_Serialization/unenc-dsa-pkcs8.der`` - Contains a DSA 1024 + bit key generated using OpenSSL. +* ``asymmetric/PKCS8/unenc-dsa-pkcs8.pub.pem`` and + ``asymmetric/DER_Serialization/unenc-dsa-pkcs8.pub.der`` - Contains a DSA + 2048 bit public key generated using OpenSSL from ``unenc-dsa-pkcs8.pem``. +* DER conversions of the `GnuTLS example keys`_ for DSA as well as the + `OpenSSL example key`_ for RSA. +* DER conversions of `enc-rsa-pkcs8.pem`_, `enc2-rsa-pkcs8.pem`_, and + `unenc-rsa-pkcs8.pem`_. +* ``asymmetric/public/PKCS1/rsa.pub.pem`` and + ``asymmetric/public/PKCS1/rsa.pub.der`` are PKCS1 conversions of the public + key from ``asymmetric/PKCS8/unenc-rsa-pkcs8.pem`` using PEM and DER encoding. + + +Key exchange +~~~~~~~~~~~~ + +* ``vectors/cryptography_vectors/asymmetric/DH/rfc3526.txt`` contains + several standardized Diffie-Hellman groups from :rfc:`3526`. + +* ``vectors/cryptography_vectors/asymmetric/DH/RFC5114.txt`` contains + Diffie-Hellman examples from appendix A.1, A.2 and A.3 of :rfc:`5114`. + +* ``vectors/cryptography_vectors/asymmetric/DH/vec.txt`` contains + Diffie-Hellman examples from `botan`_. + +* ``vectors/cryptography_vectors/asymmetric/DH/bad_exchange.txt`` contains + Diffie-Hellman vector pairs that were generated using OpenSSL + ``DH_generate_parameters_ex`` and ``DH_generate_key``. + +* ``vectors/cryptography_vectors/asymmetric/DH/dhp.pem``, + ``vectors/cryptography_vectors/asymmetric/DH/dhkey.pem`` and + ``vectors/cryptography_vectors/asymmetric/DH/dhpub.pem`` contains + Diffie-Hellman parameters and key respectively. The keys were + generated using OpenSSL following `DHKE`_ guide. + ``vectors/cryptography_vectors/asymmetric/DH/dhkey.txt`` contains + all parameter in text. + ``vectors/cryptography_vectors/asymmetric/DH/dhp.der``, + ``vectors/cryptography_vectors/asymmetric/DH/dhkey.der`` and + ``vectors/cryptography_vectors/asymmetric/DH/dhpub.der`` contains + are the above parameters and keys in DER format. + +* ``vectors/cryptography_vectors/asymmetric/DH/dhp_rfc5114_2.pem``, + ``vectors/cryptography_vectors/asymmetric/DH/dhkey_rfc5114_2.pem`` and + ``vectors/cryptography_vectors/asymmetric/DH/dhpub_rfc5114_2.pem`` contains + Diffie-Hellman parameters and key respectively. The keys were + generated using OpenSSL following `DHKE`_ guide. When creating the + parameters we added the `-pkeyopt dh_rfc5114:2` option to use + RFC5114 2048 bit DH parameters with 224 bit subgroup. + ``vectors/cryptography_vectors/asymmetric/DH/dhkey_rfc5114_2.txt`` contains + all parameter in text. + ``vectors/cryptography_vectors/asymmetric/DH/dhp_rfc5114_2.der``, + ``vectors/cryptography_vectors/asymmetric/DH/dhkey_rfc5114_2.der`` and + ``vectors/cryptography_vectors/asymmetric/DH/dhpub_rfc5114_2.der`` contains + are the above parameters and keys in DER format. + +* ``vectors/cryptoraphy_vectors/asymmetric/ECDH/brainpool.txt`` contains + Brainpool vectors from :rfc:`7027`. + +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. +* ``verisign-md2-root.pem`` - A legacy Verisign public root signed using the + MD2 algorithm. This is a PEM conversion of the `root data`_ in the NSS source + tree. +* ``cryptography.io.pem`` - A leaf certificate issued by RapidSSL for the + cryptography website. +* ``rapidssl_sha256_ca_g3.pem`` - The intermediate CA that issued the + ``cryptography.io.pem`` certificate. +* ``cryptography.io.precert.pem`` - A pre-certificate with the CT poison + extension for the cryptography website. +* ``wildcard_san.pem`` - A leaf certificate issued by a public CA for + ``langui.sh`` that contains wildcard entries in the SAN extension. +* ``san_edipartyname.der`` - A DSA certificate from a `Mozilla bug`_ + containing a SAN extension with an ``ediPartyName`` general name. +* ``san_x400address.der`` - A DSA certificate from a `Mozilla bug`_ containing + a SAN extension with an ``x400Address`` general name. +* ``department-of-state-root.pem`` - The intermediary CA for the Department of + State, issued by the United States Federal Government's Common Policy CA. + Notably has a ``critical`` policy constraints extensions. +* ``e-trust.ru.der`` - A certificate from a `Russian CA`_ signed using the GOST + cipher and containing numerous unusual encodings such as NUMERICSTRING in + the subject DN. +* ``alternate-rsa-sha1-oid.pem`` - A certificate from an + `unknown signature OID`_ Mozilla bug that uses an alternate signature OID for + RSA with SHA1. +* ``badssl-sct.pem`` - A certificate with the certificate transparency signed + certificate timestamp extension. +* ``bigoid.pem`` - A certificate with a rather long OID in the + Certificate Policies extension. We need to make sure we can parse + long OIDs. +* ``wosign-bc-invalid.pem`` - A certificate issued by WoSign that contains + a basic constraints extension with CA set to false and a path length of zero + in violation of :rfc:`5280`. +* ``tls-feature-ocsp-staple.pem`` - A certificate issued by Let's Encrypt that + contains a TLS Feature extension with the ``status_request`` feature + (commonly known as OCSP Must-Staple). +* ``unique-identifier.pem`` - A certificate containing + a distinguished name with an ``x500UniqueIdentifier``. +* ``utf8-dnsname.pem`` - A certificate containing non-ASCII characters in the + DNS name entries of the SAN extension. +* ``badasn1time.pem`` - A certificate containing an incorrectly specified + UTCTime in its validity->not_after. +* ``letsencryptx3.pem`` - A subordinate certificate used by Let's Encrypt to + issue end entity certificates. + +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. +* ``all_supported_names.pem`` - An RSA 2048 bit certificate generated using + OpenSSL that contains a subject and issuer that have two of each supported + attribute type from :rfc:`5280`. +* ``unsupported_subject_name.pem`` - An RSA 2048 bit self-signed CA certificate + generated using OpenSSL that contains the unsupported "initials" name. +* ``utf8_common_name.pem`` - An RSA 2048 bit self-signed CA certificate + generated using OpenSSL that contains a UTF8String common name with the value + "We heart UTF8!™". +* ``two_basic_constraints.pem`` - An RSA 2048 bit self-signed certificate + containing two basic constraints extensions. +* ``basic_constraints_not_critical.pem`` - An RSA 2048 bit self-signed + certificate containing a basic constraints extension that is not marked as + critical. +* ``bc_path_length_zero.pem`` - An RSA 2048 bit self-signed + certificate containing a basic constraints extension with a path length of + zero. +* ``unsupported_extension.pem`` - An RSA 2048 bit self-signed certificate + containing an unsupported extension type. The OID was encoded as + "1.2.3.4" with an ``extnValue`` of "value". +* ``unsupported_extension_2.pem`` - A ``secp256r1`` certificate + containing two unsupported extensions. The OIDs are ``1.3.6.1.4.1.41482.2`` + with an ``extnValue`` of ``1.3.6.1.4.1.41482.1.2`` and + ``1.3.6.1.4.1.45724.2.1.1`` with an ``extnValue`` of ``\x03\x02\x040`` +* ``unsupported_extension_critical.pem`` - An RSA 2048 bit self-signed + certificate containing an unsupported extension type marked critical. The OID + was encoded as "1.2.3.4" with an ``extnValue`` of "value". +* ``san_email_dns_ip_dirname_uri.pem`` - An RSA 2048 bit self-signed + certificate containing a subject alternative name extension with the + following general names: ``rfc822Name``, ``dNSName``, ``iPAddress``, + ``directoryName``, and ``uniformResourceIdentifier``. +* ``san_empty_hostname.pem`` - An RSA 2048 bit self-signed certificate + containing a subject alternative extension with an empty ``dNSName`` + general name. +* ``san_other_name.pem`` - An RSA 2048 bit self-signed certificate containing + a subject alternative name extension with the ``otherName`` general name. +* ``san_registered_id.pem`` - An RSA 1024 bit certificate containing a + subject alternative name extension with the ``registeredID`` general name. +* ``all_key_usages.pem`` - An RSA 2048 bit self-signed certificate containing + a key usage extension with all nine purposes set to true. +* ``extended_key_usage.pem`` - An RSA 2048 bit self-signed certificate + containing an extended key usage extension with eight usages. +* ``san_idna_names.pem`` - An RSA 2048 bit self-signed certificate containing + a subject alternative name extension with ``rfc822Name``, ``dNSName``, and + ``uniformResourceIdentifier`` general names with IDNA (:rfc:`5895`) encoding. +* ``san_wildcard_idna.pem`` - An RSA 2048 bit self-signed certificate + containing a subject alternative name extension with a ``dNSName`` general + name with a wildcard IDNA (:rfc:`5895`) domain. +* ``san_idna2003_dnsname.pem`` - An RSA 2048 bit self-signed certificate + containing a subject alternative name extension with an IDNA 2003 + (:rfc:`3490`) ``dNSName``. +* ``san_rfc822_names.pem`` - An RSA 2048 bit self-signed certificate containing + a subject alternative name extension with various ``rfc822Name`` values. +* ``san_rfc822_idna.pem`` - An RSA 2048 bit self-signed certificate containing + a subject alternative name extension with an IDNA ``rfc822Name``. +* ``san_uri_with_port.pem`` - An RSA 2048 bit self-signed certificate + containing a subject alternative name extension with various + ``uniformResourceIdentifier`` values. +* ``san_ipaddr.pem`` - An RSA 2048 bit self-signed certificate containing a + subject alternative name extension with an ``iPAddress`` value. +* ``san_dirname.pem`` - An RSA 2048 bit self-signed certificate containing a + subject alternative name extension with a ``directoryName`` value. +* ``inhibit_any_policy_5.pem`` - An RSA 2048 bit self-signed certificate + containing an inhibit any policy extension with the value 5. +* ``inhibit_any_policy_negative.pem`` - An RSA 2048 bit self-signed certificate + containing an inhibit any policy extension with the value -1. +* ``authority_key_identifier.pem`` - An RSA 2048 bit self-signed certificate + containing an authority key identifier extension with key identifier, + authority certificate issuer, and authority certificate serial number fields. +* ``authority_key_identifier_no_keyid.pem`` - An RSA 2048 bit self-signed + certificate containing an authority key identifier extension with authority + certificate issuer and authority certificate serial number fields. +* ``aia_ocsp_ca_issuers.pem`` - An RSA 2048 bit self-signed certificate + containing an authority information access extension with two OCSP and one + CA issuers entry. +* ``aia_ocsp.pem`` - An RSA 2048 bit self-signed certificate + containing an authority information access extension with an OCSP entry. +* ``aia_ca_issuers.pem`` - An RSA 2048 bit self-signed certificate + containing an authority information access extension with a CA issuers entry. +* ``cdp_empty_hostname.pem`` - An RSA 2048 bit self-signed certificate + containing a CRL distribution point extension with ``fullName`` URI without + a hostname. +* ``cdp_fullname_reasons_crl_issuer.pem`` - An RSA 1024 bit certificate + containing a CRL distribution points extension with ``fullName``, + ``cRLIssuer``, and ``reasons`` data. +* ``cdp_crl_issuer.pem`` - An RSA 1024 bit certificate containing a CRL + distribution points extension with ``cRLIssuer`` data. +* ``cdp_all_reasons.pem`` - An RSA 1024 bit certificate containing a CRL + distribution points extension with all ``reasons`` bits set. +* ``cdp_reason_aa_compromise.pem`` - An RSA 1024 bit certificate containing a + CRL distribution points extension with the ``AACompromise`` ``reasons`` bit + set. +* ``nc_permitted_excluded.pem`` - An RSA 2048 bit self-signed certificate + containing a name constraints extension with both permitted and excluded + elements. Contains ``IPv4`` and ``IPv6`` addresses with network mask as well + as ``dNSName`` with a leading period. +* ``nc_permitted_excluded_2.pem`` - An RSA 2048 bit self-signed certificate + containing a name constraints extension with both permitted and excluded + elements. Unlike ``nc_permitted_excluded.pem``, the general names do not + contain any name constraints specific values. +* ``nc_permitted.pem`` - An RSA 2048 bit self-signed certificate containing a + name constraints extension with permitted elements. +* ``nc_permitted_2.pem`` - An RSA 2048 bit self-signed certificate containing a + name constraints extension with permitted elements that do not contain any + name constraints specific values. +* ``nc_excluded.pem`` - An RSA 2048 bit self-signed certificate containing a + name constraints extension with excluded elements. +* ``nc_invalid_ip_netmask.pem`` - An RSA 2048 bit self-signed certificate + containing a name constraints extension with a permitted element that has an + ``IPv6`` IP and an invalid network mask. +* ``nc_single_ip_netmask.pem`` - An RSA 2048 bit self-signed certificate + containing a name constraints extension with a permitted element that has two + IPs with ``/32`` and ``/128`` network masks. +* ``cp_user_notice_with_notice_reference.pem`` - An RSA 2048 bit self-signed + certificate containing a certificate policies extension with a + notice reference in the user notice. +* ``cp_user_notice_with_explicit_text.pem`` - An RSA 2048 bit self-signed + certificate containing a certificate policies extension with explicit + text and no notice reference. +* ``cp_cps_uri.pem`` - An RSA 2048 bit self-signed certificate containing a + certificate policies extension with a CPS URI and no user notice. +* ``cp_user_notice_no_explicit_text.pem`` - An RSA 2048 bit self-signed + certificate containing a certificate policies extension with a user notice + with no explicit text. +* ``cp_invalid.pem`` - An RSA 2048 bit self-signed certificate containing a + certificate policies extension with invalid data. +* ``ian_uri.pem`` - An RSA 2048 bit certificate containing an issuer + alternative name extension with a ``URI`` general name. +* ``ocsp_nocheck.pem`` - An RSA 2048 bit self-signed certificate containing + an ``OCSPNoCheck`` extension. +* ``pc_inhibit_require.pem`` - An RSA 2048 bit self-signed certificate + containing a policy constraints extension with both inhibit policy mapping + and require explicit policy elements. +* ``pc_inhibit.pem`` - An RSA 2048 bit self-signed certificate containing a + policy constraints extension with an inhibit policy mapping element. +* ``pc_require.pem`` - An RSA 2048 bit self-signed certificate containing a + policy constraints extension with a require explicit policy element. +* ``unsupported_subject_public_key_info.pem`` - A certificate whose public key + is an unknown OID (``1.3.6.1.4.1.8432.1.1.2``). +* ``policy_constraints_explicit.pem`` - A self-signed certificate containing + a ``policyConstraints`` extension with a ``requireExplicitPolicy`` value. +* ``freshestcrl.pem`` - A self-signed certificate containing a ``freshestCRL`` + extension. + +Custom X.509 Request Vectors +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* ``dsa_sha1.pem`` and ``dsa_sha1.der`` - Contain a certificate request using + 1024-bit DSA parameters and SHA1 generated using OpenSSL. +* ``rsa_md4.pem`` and ``rsa_md4.der`` - Contain a certificate request using + 2048 bit RSA and MD4 generated using OpenSSL. +* ``rsa_sha1.pem`` and ``rsa_sha1.der`` - Contain a certificate request using + 2048 bit RSA and SHA1 generated using OpenSSL. +* ``rsa_sha256.pem`` and ``rsa_sha256.der`` - Contain a certificate request + using 2048 bit RSA and SHA256 generated using OpenSSL. +* ``ec_sha256.pem`` and ``ec_sha256.der`` - Contain a certificate request + using EC (``secp384r1``) and SHA256 generated using OpenSSL. +* ``san_rsa_sha1.pem`` and ``san_rsa_sha1.der`` - Contain a certificate + request using RSA and SHA1 with a subject alternative name extension + generated using OpenSSL. +* ``two_basic_constraints.pem`` - A certificate signing request + for an RSA 2048 bit key containing two basic constraints extensions. +* ``unsupported_extension.pem`` - A certificate signing request + for an RSA 2048 bit key containing containing an unsupported + extension type. The OID was encoded as "1.2.3.4" with an + ``extnValue`` of "value". +* ``unsupported_extension_critical.pem`` - A certificate signing + request for an RSA 2048 bit key containing containing an unsupported + extension type marked critical. The OID was encoded as "1.2.3.4" + with an ``extnValue`` of "value". +* ``basic_constraints.pem`` - A certificate signing request for an RSA + 2048 bit key containing a basic constraints extension marked as + critical. +* ``invalid_signature.pem`` - A certificate signing request for an RSA + 1024 bit key containing an invalid signature with correct padding. + +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. +* ``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. +* ``crl_empty.pem`` - Contains a CRL with no revoked certificates. +* ``crl_ian_aia_aki.pem`` - Contains a CRL with ``IssuerAlternativeName``, + ``AuthorityInformationAccess``, ``AuthorityKeyIdentifier`` and ``CRLNumber`` + extensions. +* ``valid_signature.pem`` - Contains a CRL with the public key which was used + to generate it. +* ``invalid_signature.pem`` - Contains a CRL with the last signature byte + incremented by 1 to produce an invalid signature, and the public key which + was used to generate it. +* ``crl_delta_crl_indicator.pem`` - Contains a CRL with the + ``DeltaCRLIndicator`` extension. + +X.509 OCSP Test Vectors +~~~~~~~~~~~~~~~~~~~~~~~ +* ``x509/ocsp/resp-sha256.der`` - An OCSP response for ``cryptography.io`` with + a SHA256 signature. +* ``x509/ocsp/resp-unauthorized.der`` - An OCSP response with an unauthorized + status. +* ``x509/ocsp/resp-revoked.der`` - An OCSP response for ``revoked.badssl.com`` + with a revoked status. +* ``x509/ocsp/resp-delegate-unknown-cert.der`` - An OCSP response for an + unknown cert from ``AC Camerafirma``. This response also contains a delegate + certificate. +* ``x509/ocsp/resp-responder-key-hash.der`` - An OCSP response from the + ``DigiCert`` OCSP responder that uses a key hash for the responder ID. +* ``x509/ocsp/resp-revoked-reason.der`` - An OCSP response from the + ``QuoVadis`` OCSP responder that contains a revoked certificate with a + revocation reason. + +Custom X.509 OCSP Test Vectors +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* ``x509/ocsp/req-sha1.der`` - An OCSP request containing a single request and + using SHA1 as the hash algorithm. +* ``x509/ocsp/req-multi-sha1.der`` - An OCSP request containing multiple + requests. +* ``x509/ocsp/req-invalid-hash-alg.der`` - An OCSP request containing an + invalid hash algorithm OID. +* ``x509/ocsp/req-ext-nonce.der`` - An OCSP request containing a nonce + extension. + +Hashes +~~~~~~ + +* MD5 from :rfc:`1321`. +* RIPEMD160 from the `RIPEMD website`_. +* SHA1 from `NIST CAVP`_. +* SHA2 (224, 256, 384, 512, 512/224, 512/256) from `NIST CAVP`_. +* SHA3 (224, 256, 384, 512) from `NIST CAVP`_. +* SHAKE (128, 256) from `NIST CAVP`_. +* Blake2s and Blake2b from OpenSSL `test/evptests.txt`_. + +HMAC +~~~~ + +* HMAC-MD5 from :rfc:`2202`. +* HMAC-SHA1 from :rfc:`2202`. +* HMAC-RIPEMD160 from :rfc:`2286`. +* HMAC-SHA2 (224, 256, 384, 512) from :rfc:`4231`. + +Key derivation functions +~~~~~~~~~~~~~~~~~~~~~~~~ + +* HKDF (SHA1, SHA256) from :rfc:`5869`. +* PBKDF2 (HMAC-SHA1) from :rfc:`6070`. +* scrypt from the `draft RFC`_. +* X9.63 KDF from `NIST CAVP`_. +* SP 800-108 Counter Mode KDF (HMAC-SHA1, HMAC-SHA224, HMAC-SHA256, + HMAC-SHA384, HMAC-SHA512) from `NIST CAVP`_. + +Key wrapping +~~~~~~~~~~~~ + +* AES key wrap (AESKW) and 3DES key wrap test vectors from `NIST CAVP`_. +* AES key wrap with padding vectors from `Botan's key wrap vectors`_. + +Recipes +~~~~~~~ + +* Fernet from its `specification repository`_. + +Symmetric ciphers +~~~~~~~~~~~~~~~~~ + +* AES (CBC, CFB, ECB, GCM, OFB, CCM) from `NIST CAVP`_. +* AES CTR from :rfc:`3686`. +* 3DES (CBC, CFB, ECB, OFB) from `NIST CAVP`_. +* ARC4 (KEY-LENGTH: 40, 56, 64, 80, 128, 192, 256) from :rfc:`6229`. +* ARC4 (KEY-LENGTH: 160) generated by this project. + See: :doc:`/development/custom-vectors/arc4` +* Blowfish (CBC, CFB, ECB, OFB) from `Bruce Schneier's vectors`_. +* Camellia (ECB) from NTT's `Camellia page`_ as linked by `CRYPTREC`_. +* Camellia (CBC, CFB, OFB) from `OpenSSL's test vectors`_. +* CAST5 (ECB) from :rfc:`2144`. +* CAST5 (CBC, CFB, OFB) generated by this project. + See: :doc:`/development/custom-vectors/cast5` +* ChaCha20 from :rfc:`7539`. +* ChaCha20Poly1305 from :rfc:`7539`, `OpenSSL's evpciph.txt`_, and the + `BoringSSL ChaCha20Poly1305 tests`_. +* IDEA (ECB) from the `NESSIE IDEA vectors`_ created by `NESSIE`_. +* IDEA (CBC, CFB, OFB) generated by this project. + See: :doc:`/development/custom-vectors/idea` +* SEED (ECB) from :rfc:`4269`. +* SEED (CBC) from :rfc:`4196`. +* SEED (CFB, OFB) generated by this project. + See: :doc:`/development/custom-vectors/seed` + +Two factor authentication +~~~~~~~~~~~~~~~~~~~~~~~~~ + +* HOTP from :rfc:`4226` +* TOTP from :rfc:`6238` (Note that an `errata`_ for the test vectors in RFC + 6238 exists) + +CMAC +~~~~ + +* AES-128, AES-192, AES-256, 3DES from `NIST SP-800-38B`_ + +Creating test vectors +--------------------- + +When official vectors are unavailable ``cryptography`` may choose to build +its own using existing vectors as source material. + +Created Vectors +~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + custom-vectors/arc4 + custom-vectors/cast5 + custom-vectors/idea + custom-vectors/seed + custom-vectors/hkdf + + +If official test vectors appear in the future the custom generated vectors +should be discarded. + +Any vectors generated by this method must also be prefixed with the following +header format (substituting the correct information): + +.. code-block:: python + + # CAST5 CBC vectors built for https://github.com/pyca/cryptography + # Derived from the AESVS MMT test data for CBC + # Verified against the CommonCrypto and Go crypto packages + # Key Length : 128 + +.. _`NIST`: https://www.nist.gov/ +.. _`IETF`: https://www.ietf.org/ +.. _`Project Wycheproof`: https://github.com/google/wycheproof +.. _`NIST CAVP`: https://csrc.nist.gov/projects/cryptographic-algorithm-validation-program +.. _`Bruce Schneier's vectors`: https://www.schneier.com/code/vectors.txt +.. _`Camellia page`: https://info.isl.ntt.co.jp/crypt/eng/camellia/ +.. _`CRYPTREC`: https://www.cryptrec.go.jp +.. _`OpenSSL's test vectors`: https://github.com/openssl/openssl/blob/97cf1f6c2854a3a955fd7dd3a1f113deba00c9ef/crypto/evp/evptests.txt#L232 +.. _`OpenSSL's evpciph.txt`: https://github.com/openssl/openssl/blob/5a7bc0be97dee9ac715897fe8180a08e211bc6ea/test/evpciph.txt#L2362 +.. _`BoringSSL ChaCha20Poly1305 tests`: https://boringssl.googlesource.com/boringssl/+/2e2a226ac9201ac411a84b5e79ac3a7333d8e1c9/crypto/cipher_extra/test/chacha20_poly1305_tests.txt +.. _`BoringSSL evp tests`: https://boringssl.googlesource.com/boringssl/+/ce3773f9fe25c3b54390bc51d72572f251c7d7e6/crypto/evp/evp_tests.txt +.. _`RIPEMD website`: https://homes.esat.kuleuven.be/~bosselae/ripemd160.html +.. _`draft RFC`: https://tools.ietf.org/html/draft-josefsson-scrypt-kdf-01 +.. _`Specification repository`: https://github.com/fernet/spec +.. _`errata`: https://www.rfc-editor.org/errata_search.php?rfc=6238 +.. _`OpenSSL example key`: https://github.com/openssl/openssl/blob/d02b48c63a58ea4367a0e905979f140b7d090f86/test/testrsa.pem +.. _`GnuTLS key parsing tests`: https://gitlab.com/gnutls/gnutls/commit/f16ef39ef0303b02d7fa590a37820440c466ce8d +.. _`enc-rsa-pkcs8.pem`: https://gitlab.com/gnutls/gnutls/blob/f8d943b38bf74eaaa11d396112daf43cb8aa82ae/tests/pkcs8-decode/encpkcs8.pem +.. _`enc2-rsa-pkcs8.pem`: https://gitlab.com/gnutls/gnutls/blob/f8d943b38bf74eaaa11d396112daf43cb8aa82ae/tests/pkcs8-decode/enc2pkcs8.pem +.. _`unenc-rsa-pkcs8.pem`: https://gitlab.com/gnutls/gnutls/blob/f8d943b38bf74eaaa11d396112daf43cb8aa82ae/tests/pkcs8-decode/unencpkcs8.pem +.. _`pkcs12_s2k_pem.c`: https://gitlab.com/gnutls/gnutls/blob/f8d943b38bf74eaaa11d396112daf43cb8aa82ae/tests/pkcs12_s2k_pem.c +.. _`Botan's ECC private keys`: https://github.com/randombit/botan/tree/4917f26a2b154e841cd27c1bcecdd41d2bdeb6ce/src/tests/data/ecc +.. _`GnuTLS example keys`: https://gitlab.com/gnutls/gnutls/commit/ad2061deafdd7db78fd405f9d143b0a7c579da7b +.. _`NESSIE IDEA vectors`: https://www.cosic.esat.kuleuven.be/nessie/testvectors/bc/idea/Idea-128-64.verified.test-vectors +.. _`NESSIE`: https://en.wikipedia.org/wiki/NESSIE +.. _`Ed25519 website`: https://ed25519.cr.yp.to/software.html +.. _`NIST SP-800-38B`: https://csrc.nist.gov/publications/detail/sp/800-38b/archive/2005-05-01 +.. _`NIST PKI Testing`: https://csrc.nist.gov/Projects/PKI-Testing +.. _`testx509.pem`: https://github.com/openssl/openssl/blob/master/test/testx509.pem +.. _`DigiCert Global Root G3`: http://cacerts.digicert.com/DigiCertGlobalRootG3.crt +.. _`root data`: https://hg.mozilla.org/projects/nss/file/25b2922cc564/security/nss/lib/ckfw/builtins/certdata.txt#l2053 +.. _`asymmetric/public/PKCS1/dsa.pub.pem`: https://github.com/ruby/ruby/blob/4ccb387f3bc436a08fc6d72c4931994f5de95110/test/openssl/test_pkey_dsa.rb#L53 +.. _`Mozilla bug`: https://bugzilla.mozilla.org/show_bug.cgi?id=233586 +.. _`Russian CA`: https://e-trust.gosuslugi.ru/MainCA +.. _`test/evptests.txt`: https://github.com/openssl/openssl/blob/2d0b44126763f989a4cbffbffe9d0c7518158bb7/test/evptests.txt +.. _`unknown signature OID`: https://bugzilla.mozilla.org/show_bug.cgi?id=405966 +.. _`botan`: https://github.com/randombit/botan/blob/57789bdfc55061002b2727d0b32587612829a37c/src/tests/data/pubkey/dh.vec +.. _`DHKE`: https://sandilands.info/sgordon/diffie-hellman-secret-key-exchange-with-openssl +.. _`Botan's key wrap vectors`: https://github.com/randombit/botan/blob/737f33c09a18500e044dca3e2ae13bd2c08bafdd/src/tests/data/keywrap/nist_key_wrap.vec |