Enhancement 101 for cryptography package requirements

101_cryptography_requirements.md

@@ -0,0 +1,175 @@
+# enhancement-101: Update cryptography package requirement to support RSA-PSS
+
+<!-- toc -->
+- [Release Signoff Checklist](#release-signoff-checklist)
+- [Summary](#summary)
+- [Motivation](#motivation)
+  - [Goals](#goals)
+  - [Non-Goals](#non-goals)
+- [Proposal](#proposal)
+  - [User Stories (optional)](#user-stories-optional)
+    - [Story 1](#story-1)
+    - [Story 2](#story-2)
+  - [Notes/Constraints/Caveats (optional)](#notesconstraintscaveats-optional)
+  - [Risks and Mitigations](#risks-and-mitigations)
+- [Design Details](#design-details)
+  - [Test Plan](#test-plan)
+  - [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy)
+- [Drawbacks](#drawbacks)
+- [Alternatives](#alternatives)
+- [Infrastructure Needed (optional)](#infrastructure-needed-optional)
+<!-- /toc -->
+
+## Release Signoff Checklist
+
+<!--
+**ACTION REQUIRED:** In order to merge code into a release, there must be an
+issue in [keylime/enhancements] referencing this enhancement and targeting a release**.
+
+For enhancements that make changes to code or processes/procedures in core
+Keylime i.e., [keylime/keylime], we require the following Release
+Signoff checklist to be completed.
+
+Check these off as they are completed for the Release Team to track. These
+checklist items _must_ be updated for the enhancement to be released.
+-->
+
+- [ ] Enhancement issue in release milestone, which links to pull request in [keylime/enhancements]
+- [ ] Core members have approved the issue with the label `implementable`
+- [ ] Design details are appropriately documented
+- [ ] Test plan is in place
+- [ ] User-facing documentation has been created in [keylime/keylime-docs]
+
+
+## Summary
+
+In order to support IDevID and IAK within Keylime we must enable the use of RSA-PSS [1]. In order to be able to verify RSA-PSS signatures, the salt length needs to be extracted from the signature. This should be done using the AUTO attribute for salt_length, which was added to the cryptography package in version 37.0.0 [2]
+
+[1] TPM 2.0 Keys for Device Identity and Attestation https://trustedcomputinggroup.org/wp-content/uploads/TPM-2p0-Keys-for-Device-Identity-and-Attestation_v1_r12_pub10082021.pdf
+[2] PSS signature scheme in the cyptography library https://cryptography.io/en/latest/hazmat/primitives/asymmetric/rsa/#cryptography.hazmat.primitives.asymmetric.padding.PSS
+
+## Motivation
+
+Enable RSA-PSS signature scheme verification in Keylime to enable compatibility with IAKs and IDevIDs.
+
+### Goals
+
+Require cryptogrraphy >= 37.0.0
+
+### Non-Goals
+
+<!--
+What is out of scope for this enhancement?  Listing non-goals helps to focus discussion
+and make progress.
+-->
+
+## Proposal
+
+Require cryptogrraphy >= 37.0.0
+
+### User Stories (optional)
+
+<!--
+Detail the things that people will be able to do if this enhancement is implemented.
+Include as much detail as possible so that people can understand the "how" of
+the system.  The goal here is to make this feel real for users without getting
+bogged down.
+-->
+
+#### Story 1
+
+#### Story 2
+
+### Notes/Constraints/Caveats (optional)
+
+<!--
+What are the caveats to the proposal?
+What are some important details that didn't come across above.
+Go in to as much detail as necessary here.
+This might be a good place to talk about core concepts and how they relate.
+-->
+
+### Risks and Mitigations
+
+<!--
+What are the risks of this proposal and how do we mitigate.  Think broadly.
+For example, consider both security and how this will impact the larger
+enhancement ecosystem.
+
+How will security be reviewed and by whom?
+-->
+
+## Design Details
+
+<!--
+This section should contain enough information that the specifics of your
+change are understandable.  This may include API specs (though not always
+required) or even code snippets.  If there's any ambiguity about HOW your
+proposal will be implemented, this is the place to discuss them.
+-->
+
+### Test Plan
+
+<!--
+**Note:** *Not required until targeted at a release.*
+
+Consider the following in developing a test plan for this enhancement:
+- Will there be e2e and integration tests, in addition to unit tests?
+- How will it be tested in isolation vs with other components?
+
+No need to outline all of the test cases, just the general strategy.  Anything
+that would count as tricky in the implementation and anything particularly
+challenging to test should be called out.
+
+All code is expected to have adequate tests (eventually with coverage
+expectations).
+-->
+
+### Upgrade / Downgrade Strategy
+
+<!--
+If applicable, how will the component be upgraded and downgraded? Make sure
+this is in the test plan.
+
+Consider the following in developing an upgrade/downgrade strategy for this enhancement
+-->
+
+### Dependencie requirements
+
+<!--
+If your new change requires new dependencies, please outline and demonstrate that your selected dependency 
+is well maintained and packaged in Keylime's supported Operating Systems (currently Debian Stable
+and as of time writing Fedora 32/33). 
+
+During code implementation you will also be expected to add the package to CI , the keylime ansible role and 
+keylimes main installer (`keylime/installers.sh`).
+
+If the package is not available in the supported Operated systems, the PR will not be merged into master. 
+
+Adding the package in `requirements.txt` is not sufficent for master which is where we tag releases from. 
+
+You may however be able to work within an experimental branch until a package is made available. If this is
+the case, please outline it in this enhancement.
+
+-->
+
+## Drawbacks
+
+<!--
+Why should this enhancement _not_ be implemented?
+-->
+
+## Alternatives
+
+<!--
+What other approaches did you consider and why did you rule them out?  These do
+not need to be as detailed as the proposal, but should include enough
+information to express the idea and why it was not acceptable.
+-->
+
+## Infrastructure Needed (optional)
+
+<!--
+Use this section if you need things infrastructure related specific to your enhancement.  Examples include a
+new subproject, repos requested, github webhook, changes to CI (travis).
+-->