More updates

Signed-off-by: Michael Lodder <redmike7@gmail.com>

Author: mikelodder7

enclave-interface/README.md

@@ -39,9 +39,10 @@ The types of hardware-backed or virtual implementations envisaged are:
 1. Simple hardware-accelerations (AES-NI, HW RNGs, FPGAs)
 2. Personal HSMs (Yubikey, Ledger, smart card. Typically locally connected, single instance, simple integrated key management,
 OS keyrings like Mac OS X Keychain, Gnome-Keyring, KWallet, Windows Credential Manager)
-3. Enterprise HSMs (Thales, Iron Core Labs, nCipher, Utimaco, Securosys. May be network connected, multi-user and redundent configurations, complex key management with roles and access policies. Logging and auditing requirements)
-4. Cloud key management (Microsoft Azure KeyValut, Amazon AWS KMS, Hashicorp Vault, Box KeySafe)
-5. Trusted Execution Environments (Intel SGX, Microsoft CoCo, ARM Trustzone, RISC-V Multivisors, Unbound Key Control)
+3. Enterprise HSMs (Thales, Iron Core Labs, nCipher, Utimaco, Securosys, Jitsuin.
+    May be network connected, multi-user and redundent configurations, complex key management with roles and access policies. Logging and auditing requirements)
+4. Cloud key management (Microsoft Azure KeyVault, Amazon AWS KMS, Hashicorp Vault, Box KeySafe)
+5. Trusted Execution Environments (Intel SGX, ARM Trustzone, RISC-V Multivisors, Unbound Key Control)
 
 Use of each different type of implementation comes with its own unique set of security questions. Superficially a user
 may simply want to know **"is my crypto code running in a secure environment or hardware?"**, but for true security
@@ -56,7 +57,7 @@ it is necessary to verify many more of the details:
 
 It is very important not to expose the details of the implementation through the API itself: it gets very messy, very quickly
 to try to accommodate all the small details of each potential implementation in a generic API. Instead, it is preferable
-to protide attestation commands that return provider-specific information which can be verified out-of-band.
+to provide attestation commands that return provider-specific information which can be verified out-of-band.
 
 ## Why can't we just invisibly use the encalve we find on our system?
 
@@ -110,13 +111,14 @@ come in one of the following forms:
 1. Networked (HTTP, ethernet, bluetooth)
 
 Therefore initial piece of the interface is the connection. Given each provider has different connection methods, 
-the connection create process takes a configuration unique to that enclave.
+the connection create process takes a configuration unique to that enclave. The goal of this API design is to minimize
+changes to it to maintain compatibility.
 
 We show all code samples written as Rust but can be adapted to other languages as desired.
 
 Most hardware implementations will not allow key material to be passed through the API, even in encrypted form, so a system of external references is required that allows keys to be referenced in a way that supports:
 1. **Consistency** - The same ID refers to the same key every time (according to the key management paradigm of the underlying hardware)
-1. **Naming schemes** - Organizations often name their keys according to some formal naming scheme - such as **legal.europe.documetencryption.May2019-1**.
+1. **Naming schemes** - Organizations often name their keys according to some formal naming scheme - such as **legal.europe.documentencryption.May2019-1**.
 1. **Key blocks** - Some HSMs not only allow but actively require keys to be passed as formatted and encrypted keyblocks.  In this case we not only need to support the simple data type of a binary key block but also (potentially) identify which KEK it's encrypted under.
 
 In keeping with the drive for Ursa to be simple and hard to mess up, the proposal is to make KeyIDs in the Ursa interface be simple UTF-8 string names, and leave the underlying provider implementation to deal with the complexities of translation, key rollover, duplication and so on.  Keyblocks will not be supported until really demanded.
@@ -130,7 +132,7 @@ pub trait EnclaveLike {
     /// Terminate the current session/context
     fn close(self);
     /// Get a list of capabilities supported by this enclave
-    fn capabilities(&self) -> Result<Vec<EnclaveCapabilities>, Error>;
+    fn capabilities(&self) -> Result<Vec<EnclaveOperation>, Error>;
     /// Create a new enclave key. Settings and key type and supported operations are 
     /// defined in the `EnclaveCreateKeyOptions`. 
     fn create_key(&self, options: EnclaveCreateKeyOptions) -> Result<EnclaveMessage, Error>;
@@ -174,7 +176,9 @@ pub enum EnclaveConnector {
     YubiHsm(YubiHsmConnector),
     SGX(SGXConnector),
     Trustzone(TrustzoneConnector),
-    AwsKms(AwsKmsConnector)
+    AwsKms(AwsKmsConnector),
+    AzureKeyVault(AzureKeyVaultConnector),
+    HashicorpVault(HashicorpConnector)
 }
 ```
 
@@ -222,19 +226,139 @@ pub enum YubiHsmConnector {
 }
 ```
 
-Once a `EnclaveConnector` has been defined, the connection is created. The connection enables the 
+Once a `EnclaveConnector` has been defined, the connection is created. The connection enables all other operations.
+Enclave providers must be queryable for capabilities which can then be used by the caller to determine what its allowed
+to use. Common capabilities with existing enclaves are in the following rust code. These are not mutually exclusive
+```rust
+pub enum EnclaveOperation {
+    DeriveDiffieHellman(DeriveParams),
+    GenerateAsymmetricKey(GenerateAsymmetricParams),
+    GenerateSymmetricKey(GenerateSymmetricParams),
+    GenerateRandom(RandomParams),
+    Attestation(AttestationParams),
+    Sign(SigningParams),
+    Verify(VerifyParams),
+    Encrypt(EncryptParams),
+    Decrypt(DecryptParams),
+    DeleteKey(DeleteKeyParams),
+    WrapKey(WrapParams),
+    UnwrapKey(UnwrapParams),
+    ExportWrappedKey(ExportWrappedParams),
+    ImportWrappedKey(ImportWrappedParams),
+    KeyInfo(KeyInfoParams),
+    Audit(AuditParams),
+    Log(LogParams),
+    DeviceInfo
+}
+
+pub enum DeriveParams {
+    Pkcs3(Pkcs3Params),
+    Ecdh(EcdhParams),
+    Pq(PostQuantumParams)
+}
+
+/// PKCS#3 parameters according to v1.4
+pub struct Pkcs3Params {
+    /// Prime, must be 2048, 3072, 4096, 6144, or 8192
+    p: Pkcs3DhP,
+    /// Base
+    g: BigNum,
+    /// This enclave's key id
+    id: String,
+    /// Other's public key
+    peer: BigNum
+}
+
+/// Pkcs3 diffie hellman prime
+pub struct Pkcs3DhP {
+    value: BigNum
+}
+
+/// Elliptic Curve Diffie Hellman parameters
+pub struct EcdhParams {
+    /// The curve to use
+    curve: EccCurve,
+    /// This enclave's key id
+    id: String,
+    /// Other's public key as an uncompressed point for curves that support compressed points
+    /// typically is 57, 65, 97, 129, 133, 193 bytes
+    peer: EcPoint
+}
+
+/// Valid elliptic curves see https://eprint.iacr.org/2018/193.pdf 
+/// and https://eprint.iacr.org/2005/133.pdf
+/// for information about BN and BLS curves
+pub enum EccCurve {
+    /// Curve25519
+    Curve25519,
+    /// Curve41417
+    Curve41417,
+    /// Curve448 AKA Goldilocks 
+    Curve448,
+    /// Barreto-Lynn-Scott embedding degree 12 with prime field 381 bits
+    Bls381,
+    /// Barreto-Lynn-Scott embedding degree 12 with prime field 461 bits
+    Bls461,
+    /// Barreto-Lynn-Scott embedding degree 24 with equivalent security of AES-192
+    Bls24,
+    /// Barreto-Lynn-Scott embedding degree 48 with equivalent security of AES-256 with 581 bit prime
+    /// see https://tools.ietf.org/id/draft-kato-threat-pairing-01.html#rfc.section.3
+    Bls48,
+    /// Barreto Naehrig with prime field 254 bits. About 100 bits of security
+    Bn254,
+    /// Barreto Naehrig with prime field 256 bits. See https://cryptojedi.org/papers/dclxvi-20100714.pdf
+    /// and https://moderncrypto.org/mail-archive/curves/2016/000740.html for more details
+    BnP256,
+    /// Barreto Naehrig with prime field 384 bits. See https://cryptojedi.org/papers/dclxvi-20100714.pdf
+    BnP384,
+    /// Barreto Naehrig with prime field 512 bits as specified in ISO15946-5
+    BnP512,
+    /// Barreto Naehrig with prime field 638 bits as specified in
+    /// https://fidoalliance.org/specs/fido-v2.0-rd-20180702/fido-ecdaa-algorithm-v2.0-rd-20180702.html#supported-curves-for-ecdaa
+    BnP638,
+    /// NIST P-224 (secp224r1)
+    EcP224,
+    /// NIST P-256 (secp256r1, prime256v1)
+    EcP256,
+    /// NIST P-384 (secp384r1)
+    EcP384,
+    /// NIST P-521 (secp521r1)
+    EcP521,
+    /// secp256k1
+    EcK256,
+    /// Brainpool 224
+    EcBP224,
+    /// BrainPool 256
+    EcBP256,
+    /// BrainPool 384
+    EcBP384,
+    /// BrainPool 512
+    EcBP512,
+}
+```
+
+Some capabilities offer multiple options like `DeriveDiffieHellman` which can be either PKCS#3 DHParameter structure
+or Elliptic-Curve based.
+
+This model allows the flexibility to add new operations and types without changing the APIs.
+
+Each operation will return an Enclave Message that contains the results or an error upon failure. For example, 
+Encryption will return the ciphertext and possibly an authentication tag. Signing returns the signature.
 
 # Drawbacks
 [drawbacks]: #drawbacks
 For developers intimately familiar with enclave programming, this API may be a more expensive/complicated scheme than
 using the methods they are already used to using. Care must be taken so this scheme does not change frequency with each
 enclave provider that is to be supported.
 
+Another possibility is that this approach is too flexible and requires intimate knowledge about crypto algorithms.
+To mitigate this, predefined ciphers can be created for end consumers like RSA-3072-PSS-SHA256 or
+AES-256-GCM or AES-128-CBC-HMAC-SHA256 or XCHACHA20-POLY1305. This reduces algorithmic agility that is an inherent problem
+with many cryptographic libraries. 
+
 # Rationale and alternatives
 [alternatives]: #alternatives
 
-
-
 # Prior art
 [prior-art]: #prior-art
 This provider model is extremely common in the crypto world with implementations like [PKCS11](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html)