From eeff3dc77b02eccedc98123bfed51ff4a77ee8b2 Mon Sep 17 00:00:00 2001 From: Anthony Hu Date: Wed, 27 Jul 2022 12:15:31 -0400 Subject: [PATCH 1/2] API documentation for the CSharp wrappers. --- wrapper/CSharp/wolfTPM.cs | 229 +++++++++++++++++++++++++++++++++++++- 1 file changed, 226 insertions(+), 3 deletions(-) diff --git a/wrapper/CSharp/wolfTPM.cs b/wrapper/CSharp/wolfTPM.cs index 5adf7f3..e53280e 100644 --- a/wrapper/CSharp/wolfTPM.cs +++ b/wrapper/CSharp/wolfTPM.cs @@ -717,6 +717,15 @@ namespace wolfTPM int outFormat, byte[] output, int outputSz); + /// + /// Helper for Certificate Signing Request (CSR) generation using a TPM based key. + /// Uses a provided WOLFTPM2_CSR structure with subject and key usage already set. + /// + /// Reference to Device class reference + /// Reference to KeyBlob class + /// X509_Format.PEM or X509_Format.DER + /// byte array for output + /// Success: Positive integer (size of the output) public int MakeAndSign(Device device, KeyBlob keyBlob, X509_Format outputFormat, @@ -831,6 +840,10 @@ namespace wolfTPM [DllImport(DLLNAME, EntryPoint = "wolfTPM2_SelfTest")] private static extern int wolfTPM2_SelfTest(IntPtr dev); + /// + /// Asks the TPM to perform its self test. + /// + /// 0: Success; TPM_RC_FAILURE: check TPM IO and TPM return code. public int SelfTest() { int rc = wolfTPM2_SelfTest(device); @@ -845,6 +858,12 @@ namespace wolfTPM private static extern int wolfTPM2_GetRandom(IntPtr dev, byte[] buf, int len); + /// + /// Get a set of random number, generated with the TPM RNG or wolfcrypt RNG. + /// Define WOLFTPM2_USE_HW_RNG to use the TPM RNG source + /// + /// Buffer used to store the generated random numbers. + /// 0: Success; BAD_FUNC_ARG: check provided arguments; TPM_RC_FAILURE: check TPM IO and TPM return code. public int GetRandom(byte[] buf) { int rc = wolfTPM2_GetRandom(device, buf, buf.Length); @@ -861,6 +880,13 @@ namespace wolfTPM uint alg, string auth, int authSz); + /// + /// Generates a new TPM Primary Key that will be used as a Storage Key for other TPM keys. + /// + /// Empty key, to store information about the new EK. + /// TPM_ALG_RSA or TPM_ALG_ECC. + /// String constant specifying the password authorization for the TPM 2.0 Key. + /// 0: Success; BAD_FUNC_ARG: check provided arguments; TPM_RC_FAILURE: check TPM IO and TPM return code. public int CreateSRK(Key srkKey, TPM2_Alg alg, string auth) @@ -884,6 +910,16 @@ namespace wolfTPM IntPtr bind, byte sesType, int encDecAlg); + /// + /// Create a TPM session, Policy, HMAC or Trial. This wrapper can also be used to start TPM + /// session for parameter encryption; see wolfTPM nvram or keygen example. + /// + /// An empty session object. + /// A key that will be used as a salt for the session. + /// A handle that will be used to make the session bounded. + /// The session type (HMAC, Policy or Trial). + /// Integer specifying the algorithm in case of parameter encryption. + /// 0: Success; BAD_FUNC_ARG: check provided arguments. public int StartSession(Session tpmSession, Key tmpKey, IntPtr bind, @@ -908,6 +944,15 @@ namespace wolfTPM int index, IntPtr tpmSession, byte sessionAttributes); + /// + /// Sets a TPM Authorization slot using the provided TPM session handle, index and session + /// attributes. This wrapper is useful for configuring TPM sessions, e.g. session for + /// parameter encryption. + /// + /// A session object. + /// Integer value, specifying the TPM Authorization slot (0, 1, 2, or 3). + /// Integer value from TPMA_SESSION selecting one or more attributes for the Session. + /// 0: Success; BAD_FUNC_ARG: check provided arguments. public int SetAuthSession(Session tpmSession, int index, byte sessionAttributes) @@ -926,6 +971,12 @@ namespace wolfTPM return rc; } + /// + /// Clears a TPM Authorization slot using the provided TPM session handle and index. + /// + /// A session object. + /// Integer value, specifying the TPM Authorization slot (0, 1, 2, or 3). + /// 0: Success; BAD_FUNC_ARG: check provided arguments. public int ClearAuthSession(Session tpmSession, int index) { @@ -940,11 +991,18 @@ namespace wolfTPM return rc; } - [DllImport(DLLNAME, EntryPoint = "wolfTPM2_ReadPublicKey")] private static extern int wolfTPM2_ReadPublicKey(IntPtr dev, IntPtr key, ulong handle); + + /// + /// Helper function to receive the public part of a loaded TPM object using its handle. The + /// public part of a TPM symmetric keys contains just TPM meta data. + /// + /// An empty key object. + /// Integer value specifying handle of a loaded TPM object. + /// 0: Success; BAD_FUNC_ARG: check provided arguments; TPM_RC_FAILURE: check TPM IO and TPM return code. public int ReadPublicKey(Key key, ulong handle) { int rc = wolfTPM2_ReadPublicKey(device, key.key, handle); @@ -956,6 +1014,14 @@ namespace wolfTPM } return rc; } + + /// + /// Helper function to receive the public part of a loaded TPM object using its handle. The + /// public part of a TPM symmetric keys contains just TPM meta data. + /// + /// An empty KeyBlob object. + /// Integer value specifying handle of a loaded TPM object. + /// 0: Success; BAD_FUNC_ARG: check provided arguments; TPM_RC_FAILURE: check TPM IO and TPM return code. public int ReadPublicKey(KeyBlob keyBlob, ulong handle) { int rc = wolfTPM2_ReadPublicKey(device, keyBlob.keyblob, handle); @@ -968,7 +1034,6 @@ namespace wolfTPM return rc; } - [DllImport(DLLNAME, EntryPoint = "wolfTPM2_CreateKey")] private static extern int wolfTPM2_CreateKey( IntPtr dev, @@ -977,6 +1042,15 @@ namespace wolfTPM IntPtr publicTemplate, string auth, int authSz); + /// + /// Single function to prepare and create a TPM 2.0 Key. This function only creates the key + /// material and stores it into the keyblob argument. To load the key use wolfTPM2_LoadKey. + /// + /// An empty KeyBlob object. + /// A handle specifying the a 2.0 Primary Key to be used as the parent(Storage Key). + /// A template populated manually or using one of the GetKeyTemplate_...() wrappers. + /// A string specifying the password authorization for the TPM 2.0 Key. + /// 0: Success; BAD_FUNC_ARG: check provided arguments; TPM_RC_FAILURE: check TPM IO and TPM return code. public int CreateKey(KeyBlob keyBlob, Key parent, Template publicTemplate, @@ -1000,6 +1074,14 @@ namespace wolfTPM IntPtr dev, IntPtr keyBlob, IntPtr parent); + /// + /// Single function to load a TPM 2.0 key. To load a TPM 2.0 key its parent(Primary Key) + /// should also be loaded prior to this operation. Primary Keys are loaded when they are + /// created. + /// + /// An empty KeyBlob object. + /// A handle specifying the a 2.0 Primary Key to be used as the parent(Storage Key) + /// 0: Success; BAD_FUNC_ARG: check provided arguments; TPM_RC_FAILURE: check TPM IO and TPM return code. public int LoadKey(KeyBlob keyBlob, Key parent) { @@ -1015,6 +1097,14 @@ namespace wolfTPM [DllImport(DLLNAME, EntryPoint = "wolfTPM2_NVStoreKey")] private static extern int wolfTPM2_NVStoreKey(IntPtr dev, ulong primaryHandle, IntPtr key, ulong persistentHandle); + + /// + /// Helper function to store a TPM 2.0 Key into the TPM's NVRAM. + /// + /// The TPM 2.0 key to be stored. + /// Integer value, specifying a TPM 2.0 Hierarchy. Typically TPM_RH_OWNER. + /// Integer value, specifying an existing nvIndex. + /// 0: Success; BAD_FUNC_ARG: check provided arguments; TPM_RC_FAILURE: check TPM IO and TPM return code. public int StoreKey(Key key, ulong primaryHandle, ulong persistentHandle) { int rc = wolfTPM2_NVStoreKey(device, primaryHandle, key.key, @@ -1026,6 +1116,14 @@ namespace wolfTPM } return rc; } + + /// + /// Helper function to store a TPM 2.0 Key into the TPM's NVRAM. + /// + /// The TPM 2.0 keyBlob to be stored. + /// Integer value, specifying a TPM 2.0 Hierarchy. Typically TPM_RH_OWNER. + /// Integer value, specifying an existing nvIndex. + /// 0: Success; BAD_FUNC_ARG: check provided arguments; TPM_RC_FAILURE: check TPM IO and TPM return code. public int StoreKey(KeyBlob keyBlob, ulong primaryHandle, ulong persistentHandle) { int rc = wolfTPM2_NVStoreKey(device, primaryHandle, keyBlob.keyblob, @@ -1041,6 +1139,13 @@ namespace wolfTPM [DllImport(DLLNAME, EntryPoint = "wolfTPM2_NVDeleteKey")] private static extern int wolfTPM2_NVDeleteKey(IntPtr dev, ulong primaryHandle, IntPtr key); + + /// + /// Helper function to delete a TPM 2.0 Key from the TPM's NVRAM. + /// + /// The TPM 2.0 key to be stored. + /// Integer value, specifying a TPM 2.0 Hierarchy. Typically TPM_RH_OWNER. + /// 0: Success; BAD_FUNC_ARG: check provided arguments; TPM_RC_FAILURE: check TPM IO and TPM return code. public int DeleteKey(Key key, ulong primaryHandle) { int rc = wolfTPM2_NVDeleteKey(device, primaryHandle, key.key); @@ -1050,6 +1155,13 @@ namespace wolfTPM } return rc; } + + /// + /// Helper function to delete a TPM 2.0 Key from the TPM's NVRAM. + /// + /// The TPM 2.0 keyBlob to be stored. + /// Integer value, specifying a TPM 2.0 Hierarchy. Typically TPM_RH_OWNER. + /// 0: Success; BAD_FUNC_ARG: check provided arguments; TPM_RC_FAILURE: check TPM IO and TPM return code. public int DeleteKey(KeyBlob keyBlob, ulong primaryHandle) { int rc = wolfTPM2_NVDeleteKey(device, primaryHandle, keyBlob.keyblob); @@ -1073,6 +1185,17 @@ namespace wolfTPM uint scheme, uint hashAlg); + /// + /// Import an external RSA private key. + /// + /// The parent key. Can be NULL for external keys and the key will be imported under the OWNER hierarchy. + /// An empty keyBlob. + /// Buffer containing the public part of the RSA key. + /// Integer value specifying the RSA exponent. + /// Buffer containing the private material of the RSA key. + /// Value from TPM2_Alg specifying the RSA scheme. + /// Value from TPM2_Alg specifying a supported TPM 2.0 hash algorithm. + /// 0: Success; BAD_FUNC_ARG: check provided arguments; TPM_RC_FAILURE: check TPM IO and TPM return code; BUFFER_E: arguments size is larger than what the TPM buffers allow. public int ImportRsaPrivateKey( Key parentKey, KeyBlob keyBlob, @@ -1106,6 +1229,15 @@ namespace wolfTPM byte[] rsaPub, int rsaPubSz, int exponent); + + /// + /// Helper function to import the public part of an external RSA key. Recommended for use, + /// because it does not require TPM format of the public part. + /// + /// An empty key. + /// Buffer containing the public part of the RSA key. + /// Integer value specifying the RSA exponent. + /// 0: Success; BAD_FUNC_ARG: check provided arguments; TPM_RC_FAILURE: check TPM IO and TPM return code. public int LoadRsaPublicKey(Key key, byte[] rsaPub, int exponent) @@ -1132,6 +1264,16 @@ namespace wolfTPM int exponent, byte[] rsaPriv, int rsaPrivSz); + + /// + /// Helper function to import and load an external RSA private key in one step. + /// + /// The parent key. Can be NULL for external keys and the key will be imported under the OWNER hierarchy. + /// An empty key. + /// Buffer containing the public part of the RSA key. + /// Integer value specifying the RSA exponent. + /// Buffer containing the private material of the RSA key. + /// 0: Success; BAD_FUNC_ARG: check provided arguments; TPM_RC_FAILURE: check TPM IO and TPM return code. public int LoadRsaPrivateKey( Key parentKey, Key key, @@ -1163,6 +1305,19 @@ namespace wolfTPM IntPtr publicTemplate, string auth, int authSz); + + /// + /// Single function to prepare and create a TPM 2.0 Primary Key. TPM 2.0 allows only + /// asymmetric RSA or ECC primary keys. Afterwards, both symmetric and asymmetric keys can + /// be created under a TPM 2.0 Primary Key. Typically, Primary Keys are used to create + /// Hierarchies of TPM 2.0 Keys. The TPM uses a Primary Key to wrap the other keys, signing + /// or decrypting. + /// + /// An empty key. + /// Integer value specifying one of four TPM 2.0 Primary Seeds: TPM_RH_OWNER, TPM_RH_ENDORSEMENT, TPM_RH_PLATFORM or TPM_RH_NULL. + /// A template populated manually or using one of the GetKeyTemplate_...() wrappers. + /// A string specifying the password authorization for the Primary Key. + /// 0: Success; BAD_FUNC_ARG: check provided arguments; TPM_RC_FAILURE: check TPM IO and TPM return code. public int CreatePrimaryKey( Key key, TPM_RH primaryHandle, @@ -1275,6 +1430,15 @@ namespace wolfTPM private static extern int wolfTPM2_RsaEncrypt( IntPtr dev, IntPtr key, uint padScheme, byte[] plain, int plainSz, byte[] enc, ref int encSz); + + /// + /// Perform RSA encryption using a TPM 2.0 key + /// + /// A key blob holding TPM key material. + /// Buffer containing the arbitrary data for encryption. + /// Buffer where the encrypted data will be stored. + /// Integer from TPM_ALG_ID, specifying the padding scheme. + /// 0: Success; BAD_FUNC_ARG: check provided arguments; TPM_RC_FAILURE: check TPM IO and TPM return code. public int RsaEncrypt(KeyBlob keyBlob, byte[] plain, byte[] enc, TPM2_Alg padScheme) { @@ -1295,6 +1459,15 @@ namespace wolfTPM private static extern int wolfTPM2_RsaDecrypt( IntPtr dev, IntPtr key, uint padScheme, byte[] enc, int encSz, byte[] plain, ref int plainSz); + + /// + /// Perform RSA decryption using a TPM 2.0 key + /// + /// A key blob holding TPM key material. + /// Buffer containing the encrypted data. + /// Buffer containing the decrypted data. + /// Integer from TPM_ALG_ID, specifying the padding scheme. + /// 0: Success; BAD_FUNC_ARG: check provided arguments; TPM_RC_FAILURE: check TPM IO and TPM return code. public int RsaDecrypt(KeyBlob keyBlob, byte[] enc, byte[] plain, TPM2_Alg padScheme) { @@ -1315,6 +1488,16 @@ namespace wolfTPM private static extern int wolfTPM2_SignHashScheme( IntPtr dev, IntPtr key, byte[] digest, int digestSz, byte[] sig, ref int sigSz, uint sigAlg, uint hashAlg); + + /// + /// Advanced helper function to sign arbitrary data using a TPM key, and specify the signature scheme and hashing algorithm + /// + /// A key blob holding TPM key material. + /// Buffer containing arbitrary data. + /// Buffer containing the generated signature. + /// Integer from TPMI_ALG_SIG_SCHEME, specifying a supported TPM 2.0 signature scheme. + /// Integer from TPMI_ALG_HASH, specifying a supported TPM 2.0 hash algorithm. + /// 0: Success; BAD_FUNC_ARG: check provided arguments; TPM_RC_FAILURE: check TPM IO and TPM return code. public int SignHashScheme(KeyBlob keyBlob, byte[] digest, byte[] sig, TPM2_Alg sigAlg, TPM2_Alg hashAlg) { @@ -1336,6 +1519,16 @@ namespace wolfTPM private static extern int wolfTPM2_VerifyHashScheme( IntPtr dev, IntPtr key, byte[] sig, int sigSz, byte[] digest, int digestSz, uint sigAlg, uint hashAlg); + + /// + /// Advanced helper function to verify a TPM generated signature + /// + /// A key blob holding a TPM 2.0 key material. + /// Buffer containing the generated signature. + /// Buffer containing the signed data. + /// Integer from TPMI_ALG_SIG_SCHEME, specifying a supported TPM 2.0 signature scheme. + /// Integer from TPMI_ALG_HASH, specifying a supported TPM 2.0 hash algorithm. + /// 0: Success; BAD_FUNC_ARG: check provided arguments; TPM_RC_FAILURE: check TPM IO and TPM return code. public int VerifyHashScheme(KeyBlob keyBlob, byte[] sig, byte[] digest, TPM2_Alg sigAlg, TPM2_Alg hashAlg) { @@ -1352,14 +1545,32 @@ namespace wolfTPM [DllImport(DLLNAME, EntryPoint = "wolfTPM2_UnloadHandle")] private static extern int wolfTPM2_UnloadHandle(IntPtr dev, IntPtr handle); + + /// + /// Use to discard any TPM loaded object + /// + /// The key. + /// 0: Success; BAD_FUNC_ARG: check provided arguments; TPM_RC_FAILURE: check TPM IO and TPM return code. public int UnloadHandle(Key key) { return wolfTPM2_UnloadHandle(device, key.GetHandle()); } + + /// + /// Use to discard any TPM loaded object + /// + /// The keyBlob. + /// 0: Success; BAD_FUNC_ARG: check provided arguments; TPM_RC_FAILURE: check TPM IO and TPM return code. public int UnloadHandle(KeyBlob keyBlob) { return wolfTPM2_UnloadHandle(device, keyBlob.GetHandle()); } + + /// + /// Use to discard any TPM loaded object + /// + /// The TPM session. + /// 0: Success; BAD_FUNC_ARG: check provided arguments; TPM_RC_FAILURE: check TPM IO and TPM return code. public int UnloadHandle(Session tpmSession) { return wolfTPM2_UnloadHandle(device, tpmSession.GetHandle()); @@ -1367,12 +1578,18 @@ namespace wolfTPM [DllImport(DLLNAME, EntryPoint = "wolfTPM2_GetHandleValue")] private static extern uint wolfTPM2_GetHandleValue(IntPtr handle); + + /// + /// Get the 32-bit handle value from the WOLFTPM2_HANDLE + /// + /// pointer to WOLFTPM2_HANDLE structure + /// + /// TPM_HANDLE value from TPM public uint GetHandleValue(IntPtr handle) { return wolfTPM2_GetHandleValue(handle); } - [DllImport(DLLNAME, EntryPoint = "TPM2_GetRCString")] private static extern IntPtr TPM2_GetRCString(int rc); public string GetErrorString(int rc) @@ -1380,6 +1597,12 @@ namespace wolfTPM IntPtr err = TPM2_GetRCString(rc); return Marshal.PtrToStringAnsi(err); } + + /// + /// Get a human readable string for any TPM 2.0 return code. + /// + /// Integer value representing a TPM return code. + /// Pointer to a string constant. public string GetErrorString(Status rc) { return GetErrorString((int)rc); From 54a53c03b6cc5a79e50930f5f1f2b3576bc5b99c Mon Sep 17 00:00:00 2001 From: David Garske Date: Wed, 27 Jul 2022 09:56:04 -0700 Subject: [PATCH 2/2] Added more CSharp wrapper inline documentation. Fixed doxy error on `wolfTPM2_GetKeyBlobAsBuffer`. --- wolftpm/tpm2_wrap.h | 2 +- wrapper/CSharp/wolfTPM.cs | 109 ++++++++++++++++++++++++++++++++++---- 2 files changed, 100 insertions(+), 11 deletions(-) diff --git a/wolftpm/tpm2_wrap.h b/wolftpm/tpm2_wrap.h index 001d866..d2d402c 100644 --- a/wolftpm/tpm2_wrap.h +++ b/wolftpm/tpm2_wrap.h @@ -2765,7 +2765,7 @@ WOLFTPM_API int wolfTPM2_SetKeyAuthPassword(WOLFTPM2_KEY *key, const byte* auth, stored to disk for loading in a separate process or after power cycling. - \return TPM_RC_SUCCESS: successful + \return Positive integer (size of the output) \return BUFFER_E: insufficient space in provided buffer \return BAD_FUNC_ARG: check the provided arguments diff --git a/wrapper/CSharp/wolfTPM.cs b/wrapper/CSharp/wolfTPM.cs index e53280e..58aa974 100644 --- a/wrapper/CSharp/wolfTPM.cs +++ b/wrapper/CSharp/wolfTPM.cs @@ -239,7 +239,13 @@ namespace wolfTPM } } - + /// + /// Marshal data from this KeyBlob class to a binary buffer. This can be + /// stored to disk for loading in a separate process or after power + /// cycling. + /// + /// buffer in which to store marshaled keyblob + /// Success: Positive integer (size of the output) public int GetKeyBlobAsBuffer(byte[] buffer) { int rc = wolfTPM2_GetKeyBlobAsBuffer(buffer, buffer.Length, @@ -252,6 +258,12 @@ namespace wolfTPM return rc; } + /// + /// Unmarshal data into a this KeyBlob class. Used to load a keyblob + /// buffer that was previously marshaled by GetKeyBlobAsBuffer + /// + /// buffer containing marshalled keyblob to load from + /// 0: Success public int SetKeyBlobFromBuffer(byte[] buffer) { int rc = wolfTPM2_SetKeyBlobFromBuffer(keyblob, @@ -263,6 +275,9 @@ namespace wolfTPM return rc; } + /// + /// Retrieve the WOLFTPM2_HANDLE pointer from a this KeyBlob. + /// public IntPtr GetHandle() { return wolfTPM2_GetHandleRefFromKeyBlob(keyblob); @@ -316,17 +331,28 @@ namespace wolfTPM } + /// + /// Retrieve the WOLFTPM2_HANDLE pointer from a this Key. + /// public IntPtr GetHandle() { return wolfTPM2_GetHandleRefFromKey(key); } - /* kept for backwards compatibility, use GetHandle */ + /// + /// kept for backwards compatibility, use GetHandle + /// + [Obsolete("kept for backwards compatibility, use GetHandle")] public IntPtr GetHandleRefFromKey() { return wolfTPM2_GetHandleRefFromKey(key); } + /// + /// Set the authentication data for a key + /// + /// pointer to auth data + /// Success: 0 public int SetKeyAuthPassword(string auth) { int rc = wolfTPM2_SetKeyAuthPassword(key, @@ -377,6 +403,12 @@ namespace wolfTPM [DllImport(DLLNAME, EntryPoint = "wolfTPM2_GetKeyTemplate_RSA")] private static extern int wolfTPM2_GetKeyTemplate_RSA(IntPtr publicTemplate, ulong objectAttributes); + /// + /// Prepares a TPM public template for new RSA key based on user + /// selected object attributes + /// + /// Bit mask of TPM2_Object values to define the Key object attributes. + /// Success: 0 public int GetKeyTemplate_RSA(ulong objectAttributes) { int rc = wolfTPM2_GetKeyTemplate_RSA(template, @@ -393,6 +425,12 @@ namespace wolfTPM ulong objectAttributes, uint curve, uint sigScheme); + /// + /// Prepares a TPM public template for new ECC key based on user + /// selected object attributes + /// + /// Bit mask of TPM2_Object values to define the Key object attributes. + /// Success: 0 public int GetKeyTemplate_ECC(ulong objectAttributes, TPM2_ECC curve, TPM2_Alg sigScheme) { @@ -411,6 +449,12 @@ namespace wolfTPM private static extern int wolfTPM2_GetKeyTemplate_Symmetric( IntPtr publicTemplate, int keyBits, uint algMode, int isSign, int isDecrypt); + /// + /// Prepares a TPM public template for new symmetric key based on user + /// selected object attributes + /// + /// Bit mask of TPM2_Object values to define the Key object attributes. + /// Success: 0 public int GetKeyTemplate_Symmetric(int keyBits, TPM2_Alg algMode, bool isSign, @@ -430,6 +474,10 @@ namespace wolfTPM [DllImport(DLLNAME, EntryPoint = "wolfTPM2_GetKeyTemplate_RSA_EK")] private static extern int wolfTPM2_GetKeyTemplate_RSA_EK(IntPtr publicTemplate); + /// + /// Prepares a TPM public template for generating the TPM Endorsement Key of RSA type + /// + /// Success: 0 public int GetKeyTemplate_RSA_EK() { int rc = wolfTPM2_GetKeyTemplate_RSA_EK(template); @@ -442,6 +490,10 @@ namespace wolfTPM [DllImport(DLLNAME, EntryPoint = "wolfTPM2_GetKeyTemplate_ECC_EK")] private static extern int wolfTPM2_GetKeyTemplate_ECC_EK(IntPtr publicTemplate); + /// + /// Prepares a TPM public template for generating the TPM Endorsement Key of ECC type + /// + /// Success: 0 public int GetKeyTemplate_ECC_EK() { int rc = wolfTPM2_GetKeyTemplate_ECC_EK(template); @@ -454,6 +506,10 @@ namespace wolfTPM [DllImport(DLLNAME, EntryPoint = "wolfTPM2_GetKeyTemplate_RSA_SRK")] private static extern int wolfTPM2_GetKeyTemplate_RSA_SRK(IntPtr publicTemplate); + /// + /// Prepares a TPM public template for generating a new TPM Storage Key of RSA type + /// + /// Success: 0 public int GetKeyTemplate_RSA_SRK() { int rc = wolfTPM2_GetKeyTemplate_RSA_SRK(template); @@ -466,6 +522,10 @@ namespace wolfTPM [DllImport(DLLNAME, EntryPoint = "wolfTPM2_GetKeyTemplate_ECC_SRK")] private static extern int wolfTPM2_GetKeyTemplate_ECC_SRK(IntPtr publicTemplate); + /// + /// Prepares a TPM public template for generating a new TPM Storage Key of ECC type + /// + /// Success: 0 public int GetKeyTemplate_ECC_SRK() { int rc = wolfTPM2_GetKeyTemplate_ECC_SRK(template); @@ -478,6 +538,10 @@ namespace wolfTPM [DllImport(DLLNAME, EntryPoint = "wolfTPM2_GetKeyTemplate_RSA_AIK")] private static extern int wolfTPM2_GetKeyTemplate_RSA_AIK(IntPtr publicTemplate); + /// + /// Prepares a TPM public template for generating a new TPM Attestation Key of RSA type + /// + /// Success: 0 public int GetKeyTemplate_RSA_AIK() { int rc = wolfTPM2_GetKeyTemplate_RSA_AIK(template); @@ -490,6 +554,10 @@ namespace wolfTPM [DllImport(DLLNAME, EntryPoint = "wolfTPM2_GetKeyTemplate_ECC_AIK")] private static extern int wolfTPM2_GetKeyTemplate_ECC_AIK(IntPtr publicTemplate); + /// + /// Prepares a TPM public template for generating a new TPM Attestation Key of ECC type + /// + /// Success: 0 public int GetKeyTemplate_ECC_AIK() { int rc = wolfTPM2_GetKeyTemplate_ECC_AIK(template); @@ -502,6 +570,12 @@ namespace wolfTPM [DllImport(DLLNAME, EntryPoint = "wolfTPM2_SetKeyTemplate_Unique")] private static extern int wolfTPM2_SetKeyTemplate_Unique(IntPtr publicTemplate, string unique, int uniqueSz); + + /// + /// Sets the unique area of a public template used by Create or CreatePrimary. + /// + /// optional pointer to buffer to populate unique area of public template. If NULL, the buffer will be zeroized. + /// Success: 0 public int SetKeyTemplate_Unique(string unique) { int rc = wolfTPM2_SetKeyTemplate_Unique(template, @@ -557,27 +631,38 @@ namespace wolfTPM } } + /// + /// Retrieve the WOLFTPM2_HANDLE pointer from a this Session. + /// public IntPtr GetHandle() { return wolfTPM2_GetHandleRefFromSession(session); } - public int StartAuth(Device device, Key parentKey, TPM2_Alg algMode) + /// + /// Start an authenticated session (salted / unbound) with parameter + /// encryption and set session for authorization of the primary key. + /// + /// Reference to Device class reference + /// + /// The algorithm for parameter encryption (TPM2_Alg.NULL or TPM2_Alg.CFB or TPM2_Alg.XOR) + /// Success: 0 + public int StartAuth(Device device, Key parentKey, TPM2_Alg encDecAlg) { int rc; /* Algorithm modes: With parameter encryption use CFB or XOR. * For HMAC only (no parameter encryption) use NULL. */ - if (algMode != TPM2_Alg.NULL && - algMode != TPM2_Alg.CFB && - algMode != TPM2_Alg.XOR) { + if (encDecAlg != TPM2_Alg.NULL && + encDecAlg != TPM2_Alg.CFB && + encDecAlg != TPM2_Alg.XOR) { return (int)Status.BAD_FUNC_ARG; } /* Start an authenticated session (salted / unbound) with * parameter encryption */ rc = device.StartSession(this, parentKey, IntPtr.Zero, - (byte)SE.HMAC, (int)algMode); + (byte)SE.HMAC, (int)encDecAlg); if (rc == (int)Status.TPM_RC_SUCCESS) { /* Set session for authorization of the primary key */ rc = device.SetAuthSession(this, this.sessionIdx, @@ -591,6 +676,11 @@ namespace wolfTPM return rc; } + /// + /// Stop an authenticated session + /// + /// Reference to Device class reference + /// Success: 0 public int StopAuth(Device device) { /* Clear the auth index, since the auth session is ending */ @@ -634,7 +724,6 @@ namespace wolfTPM } } - [DllImport(DLLNAME, EntryPoint = "wolfTPM2_CSR_SetCustomExt")] private static extern int wolfTPM2_CSR_SetCustomExt(IntPtr dev, IntPtr csr, @@ -884,7 +973,7 @@ namespace wolfTPM /// Generates a new TPM Primary Key that will be used as a Storage Key for other TPM keys. /// /// Empty key, to store information about the new EK. - /// TPM_ALG_RSA or TPM_ALG_ECC. + /// TPM2_Alg.RSA or TPM2_Alg.ECC /// String constant specifying the password authorization for the TPM 2.0 Key. /// 0: Success; BAD_FUNC_ARG: check provided arguments; TPM_RC_FAILURE: check TPM IO and TPM return code. public int CreateSRK(Key srkKey, @@ -918,7 +1007,7 @@ namespace wolfTPM /// A key that will be used as a salt for the session. /// A handle that will be used to make the session bounded. /// The session type (HMAC, Policy or Trial). - /// Integer specifying the algorithm in case of parameter encryption. + /// The algorithm for parameter encryption (TPM2_Alg.NULL or TPM2_Alg.CFB or TPM2_Alg.XOR) /// 0: Success; BAD_FUNC_ARG: check provided arguments. public int StartSession(Session tpmSession, Key tmpKey,