Merge integrate-pq into main

[WillChilds-Klein]

Issues:

Partially addresses CryptoAlg-1665

Notes

There were a few issues in the merge that I had to manually resolve:

1. NID conflict on 973 for Dilithium3 and Kyber768. I resolved this by
   giving Dilithium3 an NID of 975 instead (Kyber1024 is 974).
   • After updating nid.h, I re-ran util/generate_build_files.py.
   • After updating files in crypto/obj, I reran the objects.go script.
2. Dilithium3's EVP_PKEY_ASN1_METHOD struct definition was slightly
   outdated and didn't have a priv_encode_v2 implementation. So, I gave
   it a trivial implementation that returns error, specifically EVP err
   EVP_R_OPERATION_NOT_SUPPORTED_FOR_THIS_KEYTYPE. We may want to come
   back and implement this method which "encodes |key| as a
   OneAsymmetricKey (RFC 5958)".

To simplify this PR's diff and facilitate reviewing, some portions of the merge
contents have been deleted in discrete commits. These deletions are temporary,
and will be reverted immediately post-merge in a two fast-follow PRs:

1. Reinstate Dilithium KATs and fuzzing corpus
2. Reinstate Dilithium documentation, and adjust the example code per
   @dkostic's guidance

Regarding the code remaining in this PR, much of it has been reviewed
previously. Here's a summary of the PRs for Dilithium-related code:

• PR Import Reference PQCrystals Dilithium3 Implementation #614
• PR Add Dilithium3 higher level API integration #674
• PR Add Dilithium to bssl speed benchmarks #724
• PR Add Dilithium3 as choice of public key algorithm to x509 #759
• PR Dilithium3 - added fixed public/private key decoding tests #805

Testing

• CI checks
• local testing for the feature guard

Against test binary built with default build flags (i.e. ENABLE_DILITHIUM=OFF):

$ /build/crypto/crypto_test --gtest_filter='Dilithium3Test.*'
...
[==========] Running 1 test from 1 test suite.
[----------] Global test environment set-up.
[----------] 1 test from Dilithium3Test
[ RUN      ] Dilithium3Test.EvpDisabled
[       OK ] Dilithium3Test.EvpDisabled (0 ms)
[----------] 1 test from Dilithium3Test (0 ms total)

[----------] Global test environment tear-down
[==========] 1 test from 1 test suite ran. (0 ms total)
[  PASSED  ] 1 test.

Against test binary built with -DENABLE_DILITHIUM=ON set in cmake invocation:

$ /build/crypto/crypto_test --gtest_filter='Dilithium3Test.*'
...
[==========] Running 7 tests from 1 test suite.
[----------] Global test environment set-up.
[----------] 7 tests from Dilithium3Test
[ RUN      ] Dilithium3Test.KeyGeneration
[       OK ] Dilithium3Test.KeyGeneration (0 ms)
[ RUN      ] Dilithium3Test.KeyComparison
[       OK ] Dilithium3Test.KeyComparison (2 ms)
[ RUN      ] Dilithium3Test.NewKeyFromBytes
[       OK ] Dilithium3Test.NewKeyFromBytes (0 ms)
[ RUN      ] Dilithium3Test.KeySize
[       OK ] Dilithium3Test.KeySize (1 ms)
[ RUN      ] Dilithium3Test.Encoding
[       OK ] Dilithium3Test.Encoding (1 ms)
[ RUN      ] Dilithium3Test.Decoding
[       OK ] Dilithium3Test.Decoding (0 ms)
[ RUN      ] Dilithium3Test.SIGOperations
[       OK ] Dilithium3Test.SIGOperations (5 ms)
[----------] 7 tests from Dilithium3Test (9 ms total)

[----------] Global test environment tear-down
[==========] 7 tests from 1 test suite ran. (9 ms total)
[  PASSED  ] 7 tests.

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and
the ISC license.

[WillChilds-Klein]

Ok, here are the requested changes:

• change NID name to DILITHIUM3 to DILITHIUM3_R3
• a build-time feature guard for Dilithium (covers source, test, and benchmark)
  • see updated Testing section in PR overview for how the build flag affects Dilithium testing
• add Dilithium3 test CI run to the POSIX tests to ensure we always have full coverage with and without Dilithium enabled

Here's a log of commits I've made since responding to @torben-hansen's last round of feedback (the API version bump is unrelated to this PR and has already been merged):

$ git log --author childw d88c2ee..HEAD
commit 9f662afeec19cd7cdf8a9e65d013451177bd345d (HEAD -> cleaup-pq)
Merge: df834beba c48902790
Author: Will Childs-Klein <[email protected]>
Date:   Mon May 8 19:06:29 2023 +0000

    Merge branch 'main' into cleaup-pq

commit 314c50d0054b52a71bab0227154809ea6ce5c206
Author: Will Childs-Klein <[email protected]>
Date:   Mon May 8 17:57:56 2023 +0000

    Add disablement test when ENABLE_DILITHIUM=OFF

commit 7d08364fe91c11b491ee48c59d4a3cfe8ce6edd6
Author: Will Childs-Klein <[email protected]>
Date:   Mon May 8 17:15:10 2023 +0000

    Rename DILITHIUM3 OID/NID to DILITHIUM3_R3

    This change qualifies the public DILITHIUM3 identifiers with a "round 3"
    (`_R3`) suffix. Internal function, variable, etc. are left as-is because
    they are not exposed to callers and can be updated if/when a materially
    different round 4 comes down the pipeline.

    Ideally, we'd be able to exclude this NID/OID entirely in non-dilithium
    builds, but this is not currently possible with the current
    `crypto/obj/` code. A next-best option would have been to put the
    Dilithium3 NID into an "experimental" NID namespace _well_ above the
    number of anticipated algorithms over the library's lifetime. I
    prototyped this out with an NID of 10,001 but as it turns out the
    tooling will expand NUM_NID and the `kObjects[]` in `obj_dat.h` and
    backfill all ~9000 ivervening array values with NULL/0-valued entries.
    This space tradeoff seemed unacceptable, so this implementation presents
    the `DILITHIUM3_R3` NID in all builds.

    The next commit will add a test to assert the behavior of trying to
    specify `DILITHIUM3_R3` in non-`DILITHIUM_ENABLED=ON` builds.

commit 51494fa7226e2080ebf2097960c8b64ca0a532bc
Merge: f3aa0ed9e 14daff9d3
Author: Will Childs-Klein <[email protected]>
Date:   Fri May 5 17:05:27 2023 +0000

    Merge branch 'main' into cleaup-pq

commit f3aa0ed9e7b87d36869f5e9e294dc2f495776d25
Author: Will Childs-Klein <[email protected]>
Date:   Fri May 5 17:04:10 2023 +0000

    Add Dilithium3 case to POSIX tests, enable dilithium in benchmarks

commit 8eeb737d15123fde4b6d213a82edf79690cae891
Author: Will Childs-Klein <[email protected]>
Date:   Fri May 5 16:44:06 2023 +0000

    Fix speed.cc to work with new dilithium guard

commit ce5eda46933e9eae06425c721abe817c43f50a54
Author: Will Childs-Klein <[email protected]>
Date:   Thu May 4 21:32:52 2023 +0000

    Add opt-in build feature guard for Dilithium

    Still need to:

    - change `DILITHIUM3` to `DILITHIUM3_R3` everywhere
    - move `crypto/dilithium/` to `crypto/dilithium3/r3`?
    - update CI to set this feature guard
    - perhaps move NID up to higher numerical value in an "experimental"
      namespace where it won't conflict with newer algos/NIDs?
    - #ifdef out the dilithium NID definition if possible

commit 5b88f4a09867612dc1aa040dcf2f52ee0a6fd2c8
Merge: b907f6b9c d723334d7
Author: Will Childs-Klein <[email protected]>
Date:   Thu May 4 20:50:29 2023 +0000

    Merge branch 'main' into cleaup-pq

commit b907f6b9cd648085eb9b216fe4584f295de09e3a
Merge: 5d320e117 33741f13c
Author: Will Childs-Klein <[email protected]>
Date:   Thu May 4 20:50:14 2023 +0000

    Merge branch 'main' into cleaup-pq

commit 28c85a29a45a69f37f8becb7cefe5faed96eb422
Author: Will Childs-Klein <[email protected]>
Date:   Wed Apr 5 16:30:54 2023 -0400

    Bump AWS-LC API version (#900)

commit 5d320e117d74b547c7f944f9e159e78ad4fe545f
Merge: 0d0b0b937 a962ee3f3
Author: Will Childs-Klein <[email protected]>
Date:   Tue Apr 4 19:13:05 2023 +0000

    Merge branch 'main' into cleaup-pq

As mentioned previously, once this PR has been merged there will be fast-follow PRs to:

1. Reinstate Dilithium KATs and fuzzing corpus
2. Reinstate Dilithium documentation, and adjust the example code per @dkostic's guidance

[torben-hansen]

Prefer to squash this, otherwise the commit history would be mighty polluted.

For the squash commit message. Write something that makes sense. A high-level summary of changes maybe?