Source release 19.2.0

oemcrypto/util/README.md

@@ -0,0 +1,96 @@
+# OEMCrypto Reference Utils
+
+Small collection of OEMCrypto utilities which perform general operations
+which hold true for **any** standard implementation of OEMCrypto.
+
+The goal of the utils is to provide high-level components which can perform
+certain complex operations found in OEMCrypto, with the intention to be used
+in the testbed code and unittests.  The most important aspect of this is to
+avoid providing any implementation-specific utilities here.
+
+Practical exceptions to goal
+
+* The use of C++
+  * Techincally specific to a specific implementation
+  * Our testbed and test code both use C++, and this is intended to be
+    used by these systems
+* Raw data formats
+  * Generally, we use `std::string`, `std::vector<uint8_t>` and `uint8_t*` to
+    store and manipulate bytes of data
+* Reasonable resource limitations
+  * Theoretical algorithms to usually take into consideration computer
+    resources, but real implementations are still subjected to them
+  * Ex. max buffer size which component operate on
+* Use of Widevine's logging system
+
+Example of goal-aligned components
+
+* Standard cryptographic operations wrappers
+  * Schemes, protocols and algorithms which are publicly published
+  * Mechanically similar to other cryptographical software libraries
+* OEMCrypto-specific RSA and ECC cryptographic operations
+  * OEMCrypto has a small set of protocols based on RSA and ECC cryptography
+  * These protocols are well-defined by the OEMCrypto specification, and
+    any implementation would need to include an implementation of these exact
+    protocols
+* DRM key cryptographic operations
+  * Built upon RSA and ECC operations
+  * Only performs DRM key operations which ANY implementation would also
+    have to perform in the same way
+
+Example of hypothetical anti-goal components
+
+* DRM key wrapping algorithms
+  * The OEMCrypto specification (as of v19) does not specify exactly how
+    wrapping a DRM key is to be performed.
+  * Although many OEMs likely use the same implementaion as the reference,
+    it is still an undefined operation.
+  * Note: Standard parts of a wrapping algorithm (such as AES encryption)
+    may be provided.
+* Usage Table Header/Entry encryptors
+  * Similar to DRM key wrapping, the OEMCrypto specification (as of v19) does
+    not specify exactly how the Usage Table's header and entries are to be
+    encrypted and signed
+* Key handle to session ID serialization
+  * This is NOT defined by the OEMCrypto specification
+
+## Current Components
+
+This is a non-exhausted list of components found within this library which
+provided general OEMCrypto operations.
+
+* `EccPublicKey` and `EccPrivateKey`
+  * High-level wrappers around OEMCrypto-specific protocols of Elliptic
+    Curve Cryptography
+  * Generally aimed for how ECC-based DRM keys are used, as well as for
+    a small set of BCC operations
+* `RsaPublicKey` and `RsaPrivateKey`
+  * High-level wrappers around OEMCrypto-specific protocols of RSA Cryptography
+  * Generally aimed for how RSA-based DRM and OEM Cert keys are used, as
+    well as a small set of Cast-specific operations
+* `DrmPrivateKey`
+  * A high-level wrapper around OEMCrypto's DRM key
+  * Provides a generic DRM key interface, which internally handles the
+    different cases of using either a RSA or ECC based DRM key
+* `wvcrc32.h`
+  * Set of functions for OEMCrypto's CRC-32 algorithm
+    * CRC-32 is a general term for 32-bit Cyclic Redundancy Checks
+    * OEMCrypto has a well-defined set of parameters which all implementers
+      must use to work with Widevine's software stack
+* `hmac.h` and `cmac.h`
+  * HMAC and CMAC C++ wrappers, restricted to only the algorithm parameters
+    which are used within OEMCrypto
+* `KeyDeriver`
+  * High-level wrapper around OEMCrypto's key derivation algorithm
+  * Intended to be used only for messaging key derivation, which is
+    well-defined within the OEMCrypto standard
+  * Note: Although the testbed uses this for other types of keys, the
+    methods provided by `KeyDeriver` are only designed with messaging keys
+    in mind.
+* `CborValidator` and specialized validators
+  * High-level validator for CBOR messages found within the Provisioning 4.0
+    protocol.
+  * Note: Although the error messages provided by this library are not defined
+    the primary function of these components do follow the specification, and
+    the error messages are used to inform a human user, not another software
+    system.