From 380b232ec9949da6ea0189ffca783b3200437aa5 Mon Sep 17 00:00:00 2001 From: Stefan Berger Date: Thu, 8 Nov 2018 14:46:14 -0500 Subject: [PATCH] rev150: Code comment changes only Signed-off-by: Stefan Berger --- src/tpm2/AlgorithmTests.c | 9 +- src/tpm2/BnMath.c | 89 +++++++++++-------- src/tpm2/CryptSelfTest.c | 1 - src/tpm2/CryptUtil.c | 4 +- src/tpm2/Entropy.c | 4 +- src/tpm2/Implementation.h | 3 +- src/tpm2/MathOnByteBuffers.c | 3 +- src/tpm2/NVDynamic.c | 8 +- src/tpm2/NVMem.c | 8 +- src/tpm2/PCR.c | 3 +- src/tpm2/Session.c | 78 +++++++++++++--- src/tpm2/StartupCommands.c | 2 +- src/tpm2/Ticket.c | 4 +- src/tpm2/crypto/openssl/CryptDes.c | 5 +- src/tpm2/crypto/openssl/CryptEccKeyExchange.c | 5 +- src/tpm2/crypto/openssl/CryptEccMain.c | 10 +-- src/tpm2/crypto/openssl/CryptEccSignature.c | 42 +++++---- src/tpm2/crypto/openssl/CryptHash.c | 74 +++++++-------- src/tpm2/crypto/openssl/CryptHashData.c | 6 +- src/tpm2/crypto/openssl/CryptPrimeSieve.c | 4 +- src/tpm2/crypto/openssl/CryptRand.c | 15 +++- src/tpm2/crypto/openssl/CryptRsa.c | 9 +- src/tpm2/crypto/openssl/CryptSym.c | 4 +- src/tpm2/crypto/openssl/TpmToOsslMath.c | 45 +++++++--- src/tpm2/crypto/openssl/TpmToOsslSupport.c | 2 +- 25 files changed, 273 insertions(+), 164 deletions(-) diff --git a/src/tpm2/AlgorithmTests.c b/src/tpm2/AlgorithmTests.c index e9fe8d6d..f869d0c0 100644 --- a/src/tpm2/AlgorithmTests.c +++ b/src/tpm2/AlgorithmTests.c @@ -3,7 +3,7 @@ /* Code to perform the various self-test functions. */ /* Written by Ken Goldman */ /* IBM Thomas J. Watson Research Center */ -/* $Id: AlgorithmTests.c 1311 2018-08-23 21:39:29Z kgoldman $ */ +/* $Id: AlgorithmTests.c 1370 2018-11-02 19:39:07Z kgoldman $ */ /* */ /* Licenses and Notices */ /* */ @@ -215,6 +215,9 @@ TestSymmetricAlgorithm( /* 10.2.1.4.3 AllSymsAreDone() */ /* Checks if both symmetric algorithms have been tested. This is put here so that addition of a symmetric algorithm will be relatively easy to handle */ +/* Return Value Meaning */ +/* TRUE(1) all symmetric algorithms tested */ +/* FALSE(0) not all symmetric algorithms tested */ static BOOL AllSymsAreDone( ALGORITHM_VECTOR *toTest @@ -224,6 +227,9 @@ AllSymsAreDone( } /* 10.2.1.4.4 AllModesAreDone() */ /* Checks if all the modes have been tested */ +/* Return Value Meaning */ +/* TRUE(1) all modes tested */ +/* FALSE(0) all modes not tested */ static BOOL AllModesAreDone( ALGORITHM_VECTOR *toTest @@ -756,7 +762,6 @@ TestEcc( no test (i.e. no tests are actually run but the vector is cleared). */ /* NOTE: toTest will only ever have bits set for implemented algorithms but alg can be anything. */ /* Error Returns Meaning */ -/* TPM_RC_SUCCESS test complete */ /* TPM_RC_CANCELED test was canceled */ LIB_EXPORT TPM_RC diff --git a/src/tpm2/BnMath.c b/src/tpm2/BnMath.c index 4ac233ed..db685bf0 100644 --- a/src/tpm2/BnMath.c +++ b/src/tpm2/BnMath.c @@ -3,7 +3,7 @@ /* Simple Operations on Big Numbers */ /* Written by Ken Goldman */ /* IBM Thomas J. Watson Research Center */ -/* $Id: BnMath.c 1259 2018-07-10 19:11:09Z kgoldman $ */ +/* $Id: BnMath.c 1370 2018-11-02 19:39:07Z kgoldman $ */ /* */ /* Licenses and Notices */ /* */ @@ -59,13 +59,13 @@ /* */ /********************************************************************************/ -/* 10.2.4 BnMath.c */ -/* 10.2.4.2 Includes */ +/* 10.2.3 BnMath.c */ +/* 10.2.3.2 Includes */ #include "Tpm.h" /* A constant value of zero as a stand in for NULL bigNum values */ const bignum_t BnConstZero = {1, 0, {0}}; -/* 10.2.4.3 Functions */ -/* 10.2.4.3.1 AddSame() */ +/* 10.2.3.3 Functions */ +/* 10.2.3.3.1 AddSame() */ /* Adds two values that are the same size. This function allows result to be the same as either of the addends. This is a nice function to put into assembly because handling the carry for multi-precision stuff is not as easy in C (unless there is a REALLY smart compiler). It would be @@ -98,7 +98,7 @@ AddSame( } return carry; } -/* 10.2.4.3.2 CarryProp() */ +/* 10.2.3.3.2 CarryProp() */ /* Propagate a carry */ static int CarryProp( @@ -126,8 +126,8 @@ CarryResolve( } BnSetTop(result, stop); } -/* 10.2.4.3.3 BnAdd() */ -/* Function to add two bigNum values. Always returns TRUEF */ +/* 10.2.3.3.3 BnAdd() */ +/* This function adds two bigNum values. Always returns TRUE */ LIB_EXPORT BOOL BnAdd( bigNum result, @@ -153,7 +153,7 @@ BnAdd( CarryResolve(result, n1->size, carry); return TRUE; } -/* 10.2.4.3.4 BnAddWord() */ +/* 10.2.3.3.4 BnAddWord() */ /* Adds a word value to a bigNum. */ LIB_EXPORT BOOL BnAddWord( @@ -169,7 +169,7 @@ BnAddWord( CarryResolve(result, op->size, carry); return TRUE; } -/* 10.2.4.3.5 SubSame() */ +/* 10.2.3.3.5 SubSame() */ /* Subtract two values that have the same size. */ static int SubSame( @@ -191,7 +191,7 @@ SubSame( } return borrow; } -/* 10.2.4.3.6 BorrowProp() */ +/* 10.2.3.3.6 BorrowProp() */ /* This propagates a borrow. If borrow is true when the end of the array is reached, then it means that op2 was larger than op1 and we don't handle that case so an assert is generated. This design choice was made because our only bigNum computations are on large positive numbers (primes) or on @@ -208,9 +208,11 @@ BorrowProp( borrow = ((*result++ = *op++ - borrow) == MAX_CRYPT_UWORD) && borrow; return borrow; } -/* 10.2.4.3.7 BnSub() */ -/* Function to do subtraction of result = op1 - op2 when op1 is greater than op2. If it isn't then a - fault is generated. */ +/* 10.2.3.3.7 BnSub() */ +/* This function does subtraction of two bigNum values and returns result = op1 - op2 when op1 is + greater than op2. If op2 is greater than op1, then a fault is generated. This function always + returns TRUE. */ + LIB_EXPORT BOOL BnSub( bigNum result, @@ -231,8 +233,8 @@ BnSub( BnSetTop(result, op1->size); return TRUE; } -/* 10.2.4.3.8 BnSubWord() */ -/* Subtract a word value from a bigNum. */ +/* 10.2.3.3.8 BnSubWord() */ +/* This function subtracts a word value from a bigNum. This function always returns TRUE. */ LIB_EXPORT BOOL BnSubWord( bigNum result, @@ -250,7 +252,7 @@ BnSubWord( BnSetTop(result, op->size); return TRUE; } -/* 10.2.4.3.9 BnUnsignedCmp() */ +/* 10.2.3.3.9 BnUnsignedCmp() */ /* This function performs a comparison of op1 to op2. The compare is approximately constant time if the size of the values used in the compare is consistent across calls (from the same line in the calling code). */ @@ -282,9 +284,12 @@ BnUnsignedCmp( retVal = (retVal < 0) ? -1 : 1; return retVal; } -/* 10.2.4.3.10 BnUnsignedCmpWord() */ -/* Compare a bigNum to a crypt_uword_t. -1 op1 is less that word 0 op1 is equal to word 1 op1 is - greater than word */ +/* 10.2.3.3.10 BnUnsignedCmpWord() */ +/* Compare a bigNum to a crypt_uword_t. */ +/* Return Value Meaning */ +/* -1 op1 is less that word */ +/* 0 op1 is equal to word */ +/* 1 op1 is greater than word */ LIB_EXPORT int BnUnsignedCmpWord( bigConst op1, @@ -299,8 +304,8 @@ BnUnsignedCmpWord( // equal if word is zero return (word == 0) ? 0 : -1; } -/* 10.2.4.3.11 BnModWord() */ -/* Find the modulus of a big number when the modulus is a word value */ +/* 10.2.3.3.11 BnModWord() */ +/* This function does modular division of a big number when the modulus is a word value. */ LIB_EXPORT crypt_word_t BnModWord( bigConst numerator, @@ -315,7 +320,7 @@ BnModWord( BnDiv(NULL, remainder, numerator, mod); return remainder->d[0]; } -/* 10.2.4.3.12 Msb() */ +/* 10.2.3.3.12 Msb() */ /* Returns the bit number of the most significant bit of a crypt_uword_t. The number for the least significant bit of any bigNum value is 0. The maximum return value is RADIX_BITS - 1, */ /* Return Values Meaning */ @@ -338,8 +343,12 @@ Msb( if(word & 0x00000002) { retVal += 1; word >>= 1; } return retVal + (int)word; } -/* 10.2.4.3.13 BnMsb() */ -/* Returns the number of the MSb(). Returns a negative number if the value is zero or bn is NULL. */ +/* 10.2.3.3.13 BnMsb() */ +/* This function returns the number of the MSb() of a bigNum value. */ +/* Return Value Meaning */ +/* -1 the word was zero or bn was NULL */ +/* n the bit number of the most significant bit in the word */ + LIB_EXPORT int BnMsb( bigConst bn @@ -355,8 +364,8 @@ BnMsb( else return -1; } -/* 10.2.4.3.14 BnSizeInBits() */ -/* Returns the number of bits required to hold a number. */ +/* 10.2.3.3.14 BnSizeInBits() */ +/* Returns the number of bits required to hold a number. It is one greater than the Msb. */ LIB_EXPORT unsigned BnSizeInBits( bigConst n @@ -366,7 +375,7 @@ BnSizeInBits( // return bits < 0 ? 0 : (unsigned)bits; } -/* 10.2.4.3.15 BnSetWord() */ +/* 10.2.3.3.15 BnSetWord() */ /* Change the value of a bignum_t to a word value. */ LIB_EXPORT bigNum BnSetWord( @@ -382,7 +391,7 @@ BnSetWord( } return n; } -/* 10.2.4.3.16 BnSetBit() */ +/* 10.2.3.3.16 BnSetBit() */ /* SET a bit in a bigNum. Bit 0 is the least-significant bit in the 0th digit_t. The function always return TRUE */ LIB_EXPORT BOOL @@ -399,9 +408,8 @@ BnSetBit( bn->d[offset] |= (1 << RADIX_MOD(bitNum)); return TRUE; } -/* 10.2.4.3.17 BnTestBit() */ -/* Check to see if a bit is SET in a bignum_t. The 0th bit is the LSb() of d[0] If a bit is outside - the range of the number, it returns FALSE */ +/* 10.2.3.3.17 BnTestBit() */ +/* Check to see if a bit is SET in a bignum_t. The 0th bit is the LSb() of d[0]. */ /* Return Values Meaning */ /* TRUE the bit is set */ /* FALSE the bit is not set or the number is out of range */ @@ -418,7 +426,7 @@ BnTestBit( else return FALSE; } -/* 10.2.4.3.18 BnMaskBits() */ +/* 10.2.3.3.18 BnMaskBits() */ /* Function to mask off high order bits of a big number. The returned value will have no more than maskBit bits set. */ /* NOTE: There is a requirement that unused words of a bignum_t are set to zero. */ @@ -444,8 +452,9 @@ BnMaskBits( BnSetTop(bn, finalSize); return retVal; } -/* 10.2.4.3.19 BnShiftRight() */ -/* Function will shift a bigNum to the right by the shiftAmount */ +/* 10.2.3.3.19 BnShiftRight() */ +/* Function will shift a bigNum to the right by the shiftAmount. This function always returns + TRUE. */ LIB_EXPORT BOOL BnShiftRight( bigNum result, @@ -483,7 +492,10 @@ BnShiftRight( BnSetTop(result, finalSize); return TRUE; } -/* 10.2.4.3.20 BnGetRandomBits() */ +/* 10.2.3.3.20 BnGetRandomBits() */ +/* Return Value Meaning */ +/* TRUE(1) success */ +/* FALSE(0) failure */ LIB_EXPORT BOOL BnGetRandomBits( bigNum n, @@ -507,7 +519,7 @@ BnGetRandomBits( } return FALSE; } -/* 10.2.4.3.21 BnGenerateRandomInRange() */ +/* 10.2.3.3.21 BnGenerateRandomInRange() */ /* Function to generate a random number r in the range 1 <= r < limit. The function gets a random number of bits that is the size of limit. There is some some probability that the returned number is going to be greater than or equal to the limit. If it is, try again. There is no more than 50% @@ -515,6 +527,9 @@ BnGetRandomBits( that meets the criteria. Since limit is very often a number with a LOT of high order ones, this rarely would need a second try. */ LIB_EXPORT BOOL +/* Return Value Meaning */ +/* TRUE(1) success */ +/* FALSE(0) failure */ BnGenerateRandomInRange( bigNum dest, bigConst limit, diff --git a/src/tpm2/CryptSelfTest.c b/src/tpm2/CryptSelfTest.c index 5848d13e..e6d6b506 100644 --- a/src/tpm2/CryptSelfTest.c +++ b/src/tpm2/CryptSelfTest.c @@ -196,7 +196,6 @@ CryptInitializeToTest( which it has no test. This allows the knowledge about which algorithms have test to be accessed through the interface that provides the test. */ /* Error Returns Meaning */ -/* TPM_RC_SUCCESS test complete */ /* TPM_RC_CANCELED test was canceled */ LIB_EXPORT TPM_RC diff --git a/src/tpm2/CryptUtil.c b/src/tpm2/CryptUtil.c index 8da2c64d..729bc805 100644 --- a/src/tpm2/CryptUtil.c +++ b/src/tpm2/CryptUtil.c @@ -3,7 +3,7 @@ /* Interfaces to the CryptoEngine() */ /* Written by Ken Goldman */ /* IBM Thomas J. Watson Research Center */ -/* $Id: CryptUtil.c 1262 2018-07-11 21:03:43Z kgoldman $ */ +/* $Id: CryptUtil.c 1370 2018-11-02 19:39:07Z kgoldman $ */ /* */ /* Licenses and Notices */ /* */ @@ -1199,10 +1199,10 @@ CryptIsAsymDecryptScheme( scheme algorithm, if the schemes are compatible, the input scheme will be chosen. */ /* This function should not be called if 'signObject->publicArea.type' == TPM_ALG_SYMCIPHER. */ /* Return Values Meaning */ +/* TRUE scheme selected */ /* FALSE both scheme and key's default scheme are empty; or scheme is empty while key's default scheme requires explicit input scheme (split signing); or non-empty default key scheme differs from scheme */ -/* TRUE scheme selected */ BOOL CryptSelectSignScheme( OBJECT *signObject, // IN: signing key diff --git a/src/tpm2/Entropy.c b/src/tpm2/Entropy.c index 7b8d9320..03797134 100644 --- a/src/tpm2/Entropy.c +++ b/src/tpm2/Entropy.c @@ -3,7 +3,7 @@ /* Entropy */ /* Written by Ken Goldman */ /* IBM Thomas J. Watson Research Center */ -/* $Id: Entropy.c 1311 2018-08-23 21:39:29Z kgoldman $ */ +/* $Id: Entropy.c 1370 2018-11-02 19:39:07Z kgoldman $ */ /* */ /* Licenses and Notices */ /* */ @@ -142,7 +142,7 @@ _plat__GetEntropy( // NOTE 1: The following command does not provide proper cryptographic entropy. // Its primary purpose to make sure that different instances of the simulator, // possibly started by a script on the same machine, are seeded differently. - // But vendors of the actual TPMs need to ensure availability of proper entropy + // Vendors of the actual TPMs need to ensure availability of proper entropy // using their platform specific means. // // NOTE 2: In debug builds by default the reference implementation will seed diff --git a/src/tpm2/Implementation.h b/src/tpm2/Implementation.h index e67c97f6..6f194dd4 100644 --- a/src/tpm2/Implementation.h +++ b/src/tpm2/Implementation.h @@ -3,7 +3,7 @@ /* Constants Reflecting a Particular TPM Implementation (e.g. PC Client) */ /* Written by Ken Goldman */ /* IBM Thomas J. Watson Research Center */ -/* $Id: Implementation.h 1311 2018-08-23 21:39:29Z kgoldman $ */ +/* $Id: Implementation.h 1370 2018-11-02 19:39:07Z kgoldman $ */ /* */ /* Licenses and Notices */ /* */ @@ -1169,6 +1169,7 @@ TPM2B_TYPE(MAX_HASH_BLOCK, MAX_HASH_BLOCK_SIZE); /* Following typedef is for some old code */ typedef TPM2B_MAX_HASH_BLOCK TPM2B_HASH_BLOCK; +/* Additional symmetric constants */ #ifndef ALG_AES # define ALG_AES NO diff --git a/src/tpm2/MathOnByteBuffers.c b/src/tpm2/MathOnByteBuffers.c index 5b71b2d0..b53b0ee3 100644 --- a/src/tpm2/MathOnByteBuffers.c +++ b/src/tpm2/MathOnByteBuffers.c @@ -3,7 +3,7 @@ /* Math functions performed with canonical integers in byte buffers */ /* Written by Ken Goldman */ /* IBM Thomas J. Watson Research Center */ -/* $Id: MathOnByteBuffers.c 1259 2018-07-10 19:11:09Z kgoldman $ */ +/* $Id: MathOnByteBuffers.c 1370 2018-11-02 19:39:07Z kgoldman $ */ /* */ /* Licenses and Notices */ /* */ @@ -178,7 +178,6 @@ ModExpB( /* Divide an integer (n) by an integer (d) producing a quotient (q) and a remainder (r). If q or r is not needed, then the pointer to them may be set to NULL. */ /* Error Returns Meaning */ -/* TPM_RC_SUCCESS operation complete */ /* TPM_RC_NO_RESULT q or r is too small to receive the result */ LIB_EXPORT TPM_RC DivideB( diff --git a/src/tpm2/NVDynamic.c b/src/tpm2/NVDynamic.c index e90b903f..1ebc23fc 100644 --- a/src/tpm2/NVDynamic.c +++ b/src/tpm2/NVDynamic.c @@ -3,7 +3,7 @@ /* Dynamic space for user defined NV */ /* Written by Ken Goldman */ /* IBM Thomas J. Watson Research Center */ -/* $Id: NVDynamic.c 1259 2018-07-10 19:11:09Z kgoldman $ */ +/* $Id: NVDynamic.c 1370 2018-11-02 19:39:07Z kgoldman $ */ /* */ /* Licenses and Notices */ /* */ @@ -617,9 +617,9 @@ NvWriteRamIndexAttributes( /* This function indicates if a handle references a persistent object in the range belonging to the platform. */ /* Return Values Meaning */ -/* TRUE handle references a platform persistent object */ -/* FALSE handle does not reference platform persistent object and may reference an owner persistent - object either */ +/* TRUE handle references a platform persistent object and may reference an owner persistent object + either*/ +/* FALSE handle does not reference platform persistent object */ BOOL NvIsPlatformPersistentHandle( TPM_HANDLE handle // IN: handle diff --git a/src/tpm2/NVMem.c b/src/tpm2/NVMem.c index d21ab675..20255aac 100644 --- a/src/tpm2/NVMem.c +++ b/src/tpm2/NVMem.c @@ -3,7 +3,7 @@ /* NV read and write access methods */ /* Written by Ken Goldman */ /* IBM Thomas J. Watson Research Center */ -/* $Id: NVMem.c 1313 2018-08-27 16:43:31Z kgoldman $ */ +/* $Id: NVMem.c 1370 2018-11-02 19:39:07Z kgoldman $ */ /* */ /* Licenses and Notices */ /* */ @@ -84,7 +84,7 @@ FILE *s_NvFile = NULL; /* C.6.3. Functions */ /* C.6.3.1. NvFileOpen() */ -/* Function to open the NV file */ +/* This function opens the file used to hold the NV image. */ #if FILE_BACKED_NV /* Return Value Meaning */ /* 0 success */ @@ -106,8 +106,8 @@ NvFileOpen( /* C.6.3.2. NvFileCommit() */ /* Write all of the contents of the NV image to a file. */ /* Return Value Meaning */ -/* 0 failure */ -/* 1 success */ +/* TRUE success */ +/* FALSE failure */ static int NvFileCommit( ) diff --git a/src/tpm2/PCR.c b/src/tpm2/PCR.c index d88e48d2..d49cd332 100644 --- a/src/tpm2/PCR.c +++ b/src/tpm2/PCR.c @@ -3,7 +3,7 @@ /* PCR access and manipulation */ /* Written by Ken Goldman */ /* IBM Thomas J. Watson Research Center */ -/* $Id: PCR.c 1311 2018-08-23 21:39:29Z kgoldman $ */ +/* $Id: PCR.c 1370 2018-11-02 19:39:07Z kgoldman $ */ /* */ /* Licenses and Notices */ /* */ @@ -847,7 +847,6 @@ PcrWrite( /* 8.7.3.25 PCRAllocate() */ /* This function is used to change the PCR allocation. */ /* Error Returns Meaning */ -/* TPM_RC_SUCCESS allocate success */ /* TPM_RC_NO_RESULT allocate failed */ /* TPM_RC_PCR improper allocation */ TPM_RC diff --git a/src/tpm2/Session.c b/src/tpm2/Session.c index b079ff56..ebfc41bc 100644 --- a/src/tpm2/Session.c +++ b/src/tpm2/Session.c @@ -3,7 +3,7 @@ /* Manage the session context counter */ /* Written by Ken Goldman */ /* IBM Thomas J. Watson Research Center */ -/* $Id: Session.c 1311 2018-08-23 21:39:29Z kgoldman $ */ +/* $Id: Session.c 1370 2018-11-02 19:39:07Z kgoldman $ */ /* */ /* Licenses and Notices */ /* */ @@ -59,20 +59,74 @@ /* */ /********************************************************************************/ +/* The code in this file is used to manage the session context counter. The scheme implemented here + is a "truncated counter". This scheme allows the TPM to not need TPM_SU_CLEAR for a very long + period of time and still not have the context count for a session repeated. */ +/* The counter (contextCounter)in this implementation is a UINT64 but can be smaller. The "tracking + array" (contextArray) only has 16-bits per context. The tracking array is the data that needs to + be saved and restored across TPM_SU_STATE so that sessions are not lost when the system enters + the sleep state. Also, when the TPM is active, the tracking array is kept in RAM making it + important that the number of bytes for each entry be kept as small as possible. */ +/* The TPM prevents collisions of these truncated values by not allowing a contextID to be assigned + if it would be the same as an existing value. Since the array holds 16 bits, after a context has + been saved, an additional 2^16-1 contexts may be saved before the count would again match. The + normal expectation is that the context will be flushed before its count value is needed again but + it is always possible to have long-lived sessions. */ +/* The contextID is assigned when the context is saved (TPM2_ContextSave()). At that time, the TPM + will compare the low-order 16 bits of contextCounter to the existing values in contextArray and + if one matches, the TPM will return TPM_RC_CONTEXT_GAP (by construction, the entry that contains + the matching value is the oldest context). */ +/* The expected remediation by the TRM is to load the oldest saved session context (the one found by + the TPM), and save it. Since loading the oldest session also eliminates its contextID value from + contextArray, there TPM will always be able to load and save the oldest existing context. */ +/* In the worst case, software may have to load and save several contexts in order to save an + additional one. This should happen very infrequently. */ +/* When the TPM searches contextArray and finds that none of the contextIDs match the low-order + 16-bits of contextCount, the TPM can copy the low bits to the contextArray associated with the + session, and increment contextCount. */ +/* There is one entry in contextArray for each of the active sessions allowed by the TPM + implementation. This array contains either a context count, an index, or a value indicating the + slot is available (0). */ +/* e index into the contextArray is the handle for the session with the region selector byte of the + session set to zero. If an entry in contextArray contains 0, then the corresponding handle may + be assigned to a session. If the entry contains a value that is less than or equal to the number + of loaded sessions for the TPM, then the array entry is the slot in which the context is + loaded. */ +/* EXAMPLE: If the TPM allows 8 loaded sessions, then the slot numbers would be 1-8 and a + contextArrary value in that range would represent the loaded session. */ +/* NOTE: When the TPM firmware determines that the array entry is for a loaded session, it will + subtract 1 to create the zero-based slot number. */ +/* There is one significant corner case in this scheme. When the contextCount is equal to a value + in the contextArray, the oldest session needs to be recycled or flushed. In order to recycle the + session, it must be loaded. To be loaded, there must be an available slot. Rather than require + that a spare slot be available all the time, the TPM will check to see if the contextCount is + equal to some value in the contextArray when a session is created. This prevents the last + session slot from being used when it is likely that a session will need to be recycled. */ +/* If a TPM with both 1.2 and 2.0 functionality uses this scheme for both 1.2 and 2.0 sessions, and + the list of active contexts is read with TPM_GetCapabiltiy(), the TPM will create 32-bit + representations of the list that contains 16-bit values (the TPM2_GetCapability() returns a list + of handles for active sessions rather than a list of contextID). The full contextID has + high-order bits that are either the same as the current contextCount or one less. It is one less + if the 16-bits of the contextArray has a value that is larger than the low-order 16 bits of + contextCount. */ + /* 8.9.2 Includes, Defines, and Local Variables */ #define SESSION_C #include "Tpm.h" -/* 8.9.3 File Scope Function -- ContextIdSetOldest() */ + +/* 8.9.3 File Scope Function -- ContextIdSetOldest() */ /* This function is called when the oldest contextID is being loaded or deleted. Once a saved - context becomes the oldest, it stays the oldest until it is deleted. Finding the oldest is a bit - tricky. It is not just the numeric comparison of values but is dependent on the value of - contextCounter. Assume we have a small contextArray with 8, 4-bit values with values 1 and 2 used - to indicate the loaded context slot number. Also assume that the array contains hex values of (0 - 0 1 0 3 0 9 F) and that the contextCounter is an 8-bit counter with a value of 0x37. Since the - low nibble is 7, that means that values above 7 are older than values below it and, in this - example, 9 is the oldest value. Note if we subtract the counter value, from each slot that - contains a saved contextID we get (- - - - B - 2 - 8) and the oldest entry is now easy to - find. */ + context becomes the oldest, it stays the oldest until it is deleted. */ +/* Finding the oldest is a bit tricky. It is not just the numeric comparison of values but is + dependent on the value of contextCounter. */ +/* Assume we have a small contextArray with 8, 4-bit values with values 1 and 2 used to indicate the + loaded context slot number. Also assume that the array contains hex values of (0 0 1 0 3 0 9 F) + and that the contextCounter is an 8-bit counter with a value of 0x37. Since the low nibble is 7, + that means that values above 7 are older than values below it and, in this example, 9 is the + oldest value. */ +/* Note if we subtract the counter value, from each slot that contains a saved contextID we get (- - + - - B - 2 - 8) and the oldest entry is now easy to find. */ + static void ContextIdSetOldest( void @@ -267,8 +321,6 @@ SessionGet( prevent a context from being saved. If so it will return TPM_RC_CONTEXT_GAP. Otherwise, it will try to find an open slot in contextArray, set contextArray to the slot. This routine requires that the caller has determined the session array index for the session. */ -/* return type TPM_RC */ -/* TPM_RC_SUCCESS context ID was assigned */ /* TPM_RC_CONTEXT_GAP can't assign a new contextID until the oldest saved session context is recycled */ /* TPM_RC_SESSION_HANDLE there is no slot available in the context array for tracking of this diff --git a/src/tpm2/StartupCommands.c b/src/tpm2/StartupCommands.c index 47fba861..94d72872 100644 --- a/src/tpm2/StartupCommands.c +++ b/src/tpm2/StartupCommands.c @@ -3,7 +3,7 @@ /* Startup Commands */ /* Written by Ken Goldman */ /* IBM Thomas J. Watson Research Center */ -/* $Id: StartupCommands.c 1259 2018-07-10 19:11:09Z kgoldman $ */ +/* $Id: StartupCommands.c 1370 2018-11-02 19:39:07Z kgoldman $ */ /* */ /* Licenses and Notices */ /* */ diff --git a/src/tpm2/Ticket.c b/src/tpm2/Ticket.c index 043caccc..767ac4b6 100644 --- a/src/tpm2/Ticket.c +++ b/src/tpm2/Ticket.c @@ -3,7 +3,7 @@ /* Functions used for ticket computations. */ /* Written by Ken Goldman */ /* IBM Thomas J. Watson Research Center */ -/* $Id: Ticket.c 1047 2017-07-20 18:27:34Z kgoldman $ */ +/* $Id: Ticket.c 1370 2018-11-02 19:39:07Z kgoldman $ */ /* */ /* Licenses and Notices */ /* */ @@ -55,7 +55,7 @@ /* arising in any way out of use or reliance upon this specification or any */ /* information herein. */ /* */ -/* (c) Copyright IBM Corp. and others, 2016, 2017 */ +/* (c) Copyright IBM Corp. and others, 2016 - 2018 */ /* */ /********************************************************************************/ diff --git a/src/tpm2/crypto/openssl/CryptDes.c b/src/tpm2/crypto/openssl/CryptDes.c index 02d69295..8ee5789d 100644 --- a/src/tpm2/crypto/openssl/CryptDes.c +++ b/src/tpm2/crypto/openssl/CryptDes.c @@ -3,7 +3,7 @@ /* Functions Required for TDES */ /* Written by Ken Goldman */ /* IBM Thomas J. Watson Research Center */ -/* $Id: CryptDes.c 1262 2018-07-11 21:03:43Z kgoldman $ */ +/* $Id: CryptDes.c 1370 2018-11-02 19:39:07Z kgoldman $ */ /* */ /* Licenses and Notices */ /* */ @@ -106,6 +106,9 @@ CryptSetOddByteParity( } /* 10.2.9.2.2 CryptDesIsWeakKey() */ /* Check to see if a DES key is on the list of weak, semi-weak, or possibly weak keys. */ +/* Return Value Meaning */ +/* TRUE(1) DES key is weak */ +/* FALSE(0) DES key is not weak */ static BOOL CryptDesIsWeakKey( UINT64 k diff --git a/src/tpm2/crypto/openssl/CryptEccKeyExchange.c b/src/tpm2/crypto/openssl/CryptEccKeyExchange.c index 3648e70c..41921030 100644 --- a/src/tpm2/crypto/openssl/CryptEccKeyExchange.c +++ b/src/tpm2/crypto/openssl/CryptEccKeyExchange.c @@ -3,7 +3,7 @@ /* Functions that are used for the two-phase, ECC, key-exchange protocols */ /* Written by Ken Goldman */ /* IBM Thomas J. Watson Research Center */ -/* $Id: CryptEccKeyExchange.c 1311 2018-08-23 21:39:29Z kgoldman $ */ +/* $Id: CryptEccKeyExchange.c 1370 2018-11-02 19:39:07Z kgoldman $ */ /* */ /* Licenses and Notices */ /* */ @@ -80,6 +80,7 @@ SM2KeyExchange( /* a) Convert xQ to an integer xqi using the convention specified in Appendix C.3. */ /* b) Calculate xqm = xqi mod 2^ceil(f/2) (where f = ceil(log2(n)). */ /* c) Calculate the associate value function avf(Q) = xqm + 2ceil(f / 2) */ +/* Always returns TRUE(1). */ static BOOL avf1( bigNum bnX, // IN/OUT: the reduced value @@ -102,7 +103,6 @@ avf1( /* Points QsB() and QeB() are required to be on the curve of inQsA. The function will fail, possibly catastrophically, if this is not the case. */ /* Error Returns Meaning */ -/* TPM_RC_SUCCESS results is valid */ /* TPM_RC_NO_RESULT the value for dsA does not give a valid point on the curve */ static TPM_RC C_2_2_MQV( @@ -305,7 +305,6 @@ avfSm2( private key. All points are required to be on the curve of inQsA. The function will fail catastrophically if this is not the case */ /* Error Returns Meaning */ -/* TPM_RC_SUCCESS results is valid */ /* TPM_RC_NO_RESULT the value for dsA does not give a valid point on the curve */ LIB_EXPORT TPM_RC SM2KeyExchange( diff --git a/src/tpm2/crypto/openssl/CryptEccMain.c b/src/tpm2/crypto/openssl/CryptEccMain.c index 2cacb228..e78a6e62 100644 --- a/src/tpm2/crypto/openssl/CryptEccMain.c +++ b/src/tpm2/crypto/openssl/CryptEccMain.c @@ -3,7 +3,7 @@ /* */ /* Written by Ken Goldman */ /* IBM Thomas J. Watson Research Center */ -/* $Id: CryptEccMain.c 1311 2018-08-23 21:39:29Z kgoldman $ */ +/* $Id: CryptEccMain.c 1370 2018-11-02 19:39:07Z kgoldman $ */ /* */ /* Licenses and Notices */ /* */ @@ -115,7 +115,7 @@ ClearPoint2B( curveId. If there is no curve with the indicated ID, the function returns NULL. This function is in this module so that it can be called by GetCurve() data. */ /* Return Values Meaning */ -/* NULL curve with the indicated TPM_ECC_CURVE value is not implemented */ +/* NULL curve with the indicated TPM_ECC_CURVE is not implemented */ /* non-NULL pointer to the curve data */ LIB_EXPORT const ECC_CURVE * CryptEccGetParametersByCurveId( @@ -380,8 +380,8 @@ CryptEndCommit( /* 10.2.12.2.14 CryptEccGetParameters() */ /* This function returns the ECC parameter details of the given curve */ /* Return Values Meaning */ -/* TRUE Get parameters success */ -/* FALSE Unsupported ECC curve ID */ +/* TRUE success */ +/* FALSE unsupported ECC curve ID */ BOOL CryptEccGetParameters( TPM_ECC_CURVE curveId, // IN: ECC curve ID @@ -541,7 +541,7 @@ BnPointMult( (mod (q - 1)) and incremented by 1 (q is the order of the curve. This produces a value (d) such that 1 <= d < q. This is the method of FIPS 186-4 Section B.4.1 'Key Pair Generation Using Extra Random Value Meaning */ -/* TRUE value generated */ +/* TRUE success */ /* FALSE failure generating private key */ BOOL BnEccGetPrivate( diff --git a/src/tpm2/crypto/openssl/CryptEccSignature.c b/src/tpm2/crypto/openssl/CryptEccSignature.c index 55f23843..5bdb4aee 100644 --- a/src/tpm2/crypto/openssl/CryptEccSignature.c +++ b/src/tpm2/crypto/openssl/CryptEccSignature.c @@ -3,7 +3,7 @@ /* ECC Signatures */ /* Written by Ken Goldman */ /* IBM Thomas J. Watson Research Center */ -/* $Id: CryptEccSignature.c 1319 2018-08-30 13:35:27Z kgoldman $ */ +/* $Id: CryptEccSignature.c 1370 2018-11-02 19:39:07Z kgoldman $ */ /* */ /* Licenses and Notices */ /* */ @@ -59,13 +59,13 @@ /* */ /********************************************************************************/ -/* 10.2.13 CryptEccSignature.c */ -/* 10.2.13.1 Includes and Defines */ +/* 10.2.12 CryptEccSignature.c */ +/* 10.2.12.1 Includes and Defines */ #include "Tpm.h" #include "CryptEccSignature_fp.h" #if ALG_ECC -/* 10.2.13.2 Utility Functions */ -/* 10.2.13.2.1 EcdsaDigest() */ +/* 10.2.12.2 Utility Functions */ +/* 10.2.12.2.1 EcdsaDigest() */ /* Function to adjust the digest so that it is no larger than the order of the curve. This is used for ECDSA sign and verification. */ static bigNum @@ -91,7 +91,7 @@ EcdsaDigest( } return bnD; } -/* 10.2.13.2.2 BnSchnorrSign() */ +/* 10.2.12.2.2 BnSchnorrSign() */ /* This contains the Schnorr signature computation. It is used by both ECDSA and Schnorr signing. The result is computed as: [s = k + r * d (mod n)] where */ /* a) s is the signature */ @@ -127,8 +127,8 @@ BnSchnorrSign( BnDiv(NULL, bnS, bnT1, bnN); return (BnEqualZero(bnS)) ? TPM_RC_NO_RESULT : TPM_RC_SUCCESS; } -/* 10.2.13.3 Signing Functions */ -/* 10.2.13.3.1 BnSignEcdsa() */ +/* 10.2.12.3 Signing Functions */ +/* 10.2.12.3.1 BnSignEcdsa() */ /* This function implements the ECDSA signing algorithm. The method is described in the comments below. This version works with internal numbers. */ TPM_RC @@ -204,7 +204,7 @@ BnSignEcdsa( return retVal; } #if ALG_ECDAA -/* 10.2.13.3.2 BnSignEcdaa() */ +/* 10.2.12.3.2 BnSignEcdaa() */ /* This function performs s = r + T * d mod q where */ /* a) 'r is a random, or pseudo-random value created in the commit phase */ /* b) nonceK is a TPM-generated, random value 0 < nonceK < n */ @@ -285,7 +285,7 @@ BnSignEcdaa( } #endif // ALG_ECDAA #if ALG_ECSCHNORR -/* 10.2.13.3.3 SchnorrReduce() */ +/* 10.2.12.3.3 SchnorrReduce() */ /* Function to reduce a hash result if it's magnitude is to large. The size of number is set so that it has no more bytes of significance than the reference value. If the resulting number can have more bits of significance than the reference. */ @@ -299,7 +299,7 @@ SchnorrReduce( if(number->size > maxBytes) number->size = maxBytes; } -/* 10.2.13.3.4 SchnorrEcc() */ +/* 10.2.12.3.4 SchnorrEcc() */ /* This function is used to perform a modified Schnorr signature. */ /* This function will generate a random value k and compute */ /* a) (xR, yR) = [k]G */ @@ -373,6 +373,11 @@ BnSignEcSchnorr( #endif // ALG_ECSCHNORR #if ALG_SM2 #ifdef _SM2_SIGN_DEBUG +/* 10.2.12.3.5 BnHexEqual() */ +/* This function compares a bignum value to a hex string. */ +/* Return Value Meaning */ +/* TRUE(1) values equal */ +/* FALSE(0) values not equal */ static BOOL BnHexEqual( bigNum bn, //IN: big number value @@ -384,7 +389,7 @@ BnHexEqual( return (BnUnsignedCmp(bn, bnC) == 0); } #endif // _SM2_SIGN_DEBUG -/* 10.2.13.3.5 BnSignEcSm2() */ +/* 10.2.12.3.5 BnSignEcSm2() */ /* This function signs a digest using the method defined in SM2 Part 2. The method in the standard will add a header to the message to be signed that is a hash of the values that define the key. This then hashed with the message to produce a digest (e) that is signed. This function @@ -479,7 +484,7 @@ BnSignEcSm2( return TPM_RC_SUCCESS; } #endif // ALG_SM2 -/* 10.2.13.3.6 CryptEccSign() */ +/* 10.2.12.3.6 CryptEccSign() */ /* This function is the dispatch function for the various ECC-based signing schemes. There is a bit of ugliness to the parameter passing. In order to test this, we sometime would like to use a deterministic RNG so that we can get the same signatures during testing. The easiest way to do @@ -557,7 +562,7 @@ CryptEccSign( return retVal; } #if ALG_ECDSA -/* 10.2.13.3.7 BnValidateSignatureEcdsa() */ +/* 10.2.12.3.7 BnValidateSignatureEcdsa() */ /* This function validates an ECDSA signature. rIn and sIn should have been checked to make sure that they are in the range 0 < v < n */ /* Error Returns Meaning */ @@ -613,7 +618,7 @@ BnValidateSignatureEcdsa( } #endif // ALG_ECDSA #if ALG_SM2 -/* 10.2.13.3.8 BnValidateSignatureEcSm2() */ +/* 10.2.12.3.8 BnValidateSignatureEcSm2() */ /* This function is used to validate an SM2 signature. */ /* Error Returns Meaning */ /* TPM_RC_SIGNATURE signature not valid */ @@ -676,7 +681,7 @@ BnValidateSignatureEcSm2( } #endif // ALG_SM2 #if ALG_ECSCHNORR -/* 10.2.13.3.9 BnValidateSignatureEcSchnorr() */ +/* 10.2.12.3.9 BnValidateSignatureEcSchnorr() */ /* This function is used to validate an EC Schnorr signature. */ /* Error Returns Meaning */ /* TPM_RC_SIGNATURE signature not valid */ @@ -728,7 +733,7 @@ BnValidateSignatureEcSchnorr( return (OK) ? TPM_RC_SUCCESS : TPM_RC_SIGNATURE; } #endif // ALG_ECSCHNORR -/* 10.2.13.3.10 CryptEccValidateSignature() */ +/* 10.2.12.3.10 CryptEccValidateSignature() */ /* This function validates an EcDsa() or EcSchnorr() signature. The point Qin needs to have been validated to be on the curve of curveId. */ /* Error Returns Meaning */ @@ -799,14 +804,13 @@ CryptEccValidateSignature( CURVE_FREE(E); return retVal; } -/* 10.2.13.3.11 CryptEccCommitCompute() */ +/* 10.2.12.3.11 CryptEccCommitCompute() */ /* This function performs the point multiply operations required by TPM2_Commit(). */ /* If B or M is provided, they must be on the curve defined by curveId. This routine does not check that they are on the curve and results are unpredictable if they are not. */ /* It is a fatal error if r is NULL. If B is not NULL, then it is a fatal error if d is NULL or if K and L are both NULL. If M is not NULL, then it is a fatal error if E is NULL. */ /* Error Returns Meaning */ -/* TPM_RC_SUCCESS computations completed normally */ /* TPM_RC_NO_RESULT if K, L or E was computed to be the point at infinity */ /* TPM_RC_CANCELED a cancel indication was asserted during this function */ LIB_EXPORT TPM_RC diff --git a/src/tpm2/crypto/openssl/CryptHash.c b/src/tpm2/crypto/openssl/CryptHash.c index 4d8bf1c6..c8ae532b 100644 --- a/src/tpm2/crypto/openssl/CryptHash.c +++ b/src/tpm2/crypto/openssl/CryptHash.c @@ -3,7 +3,7 @@ /* Implementation of cryptographic functions for hashing. */ /* Written by Ken Goldman */ /* IBM Thomas J. Watson Research Center */ -/* $Id: CryptHash.c 1311 2018-08-23 21:39:29Z kgoldman $ */ +/* $Id: CryptHash.c 1370 2018-11-02 19:39:07Z kgoldman $ */ /* */ /* Licenses and Notices */ /* */ @@ -59,10 +59,10 @@ /* */ /********************************************************************************/ -/* 10.2.14 CryptHash.c */ -/* 10.2.14.1 Description */ +/* 10.2.13 CryptHash.c */ +/* 10.2.13.1 Description */ /* This file contains implementation of cryptographic functions for hashing. */ -/* 10.2.14.2 Includes, Defines, and Types */ +/* 10.2.13.2 Includes, Defines, and Types */ #define _CRYPT_HASH_C_ #include "Tpm.h" #define HASH_TABLE_SIZE (HASH_COUNT + 1) @@ -80,7 +80,7 @@ HASH_DEF_TEMPLATE(SHA384); HASH_DEF_TEMPLATE(SHA512); #endif HASH_DEF nullDef = {{0}}; -/* 10.2.14.3 Obligatory Initialization Functions */ +/* 10.2.13.3 Obligatory Initialization Functions */ /* This function is called by _TPM_Init() do perform the initialization operations for the library. */ BOOL @@ -101,10 +101,10 @@ CryptHashStartup( { return TRUE; } -/* 10.2.14.4 Hash Information Access Functions */ -/* 10.2.14.4.1 Introduction */ +/* 10.2.13.4 Hash Information Access Functions */ +/* 10.2.13.4.1 Introduction */ /* These functions provide access to the hash algorithm description information. */ -/* 10.2.14.4.2 CryptGetHashDef() */ +/* 10.2.13.4.2 CryptGetHashDef() */ /* This function accesses the hash descriptor associated with a hash a algorithm. The function returns NULL for TPM_ALG_NULL and fails if hashAlg is not a hash algorithm. */ PHASH_DEF @@ -146,7 +146,7 @@ CryptGetHashDef( TPM_ALG_NULL is a valid hash. */ /* Return Value Meaning */ /* TRUE hashAlg is a valid, implemented hash on this TPM. */ -/* FALSE not valid */ +/* FALSE hashAlg is not valid for this TPM */ BOOL CryptHashIsValidAlg( TPM_ALG_ID hashAlg, @@ -180,7 +180,7 @@ CryptHashIsValidAlg( } return FALSE; } -/* 10.2.14.4.4 GetHashInfoPointer() */ +/* 10.2.13.4.4 GetHashInfoPointer() */ /* This function returns a pointer to the hash info for the algorithm. If the algorithm is not supported, function returns a pointer to the data block associated with TPM_ALG_NULL. */ /* NOTE: The data structure must have a digest size of 0 for TPM_ALG_NULL. */ @@ -202,7 +202,7 @@ GetHashInfoPointer( // in either case return a pointer to the TPM_ALG_NULL "hash" descriptor return &g_hashData[HASH_COUNT]; } -/* 10.2.14.4.5 CryptHashGetAlgByIndex() */ +/* 10.2.13.4.5 CryptHashGetAlgByIndex() */ /* This function is used to iterate through the hashes. TPM_ALG_NULL is returned for all indexes that are not valid hashes. If the TPM implements 3 hashes, then an index value of 0 will return the first implemented hash and an index of 2 will return the last. All other index values will @@ -219,7 +219,7 @@ CryptHashGetAlgByIndex( return TPM_ALG_NULL; return g_hashData[index].alg; } -/* 10.2.14.4.6 CryptHashGetDigestSize() */ +/* 10.2.13.4.6 CryptHashGetDigestSize() */ /* This function returns the size of the digest produced by the hash. If hashAlg is not a hash algorithm, the TPM will FAIL. */ /* Return Values Meaning */ @@ -232,7 +232,7 @@ CryptHashGetDigestSize( { return CryptGetHashDef(hashAlg)->digestSize; } -/* 10.2.14.4.7 CryptHashGetBlockSize() */ +/* 10.2.13.4.7 CryptHashGetBlockSize() */ /* Returns the size of the block used by the hash. If hashAlg is not a hash algorithm, the TPM will FAIL. */ /* Return Values Meaning */ @@ -245,7 +245,7 @@ CryptHashGetBlockSize( { return CryptGetHashDef(hashAlg)->blockSize; } -/* 10.2.14.4.8 CryptHashGetDer */ +/* 10.2.13.4.8 CryptHashGetDer */ /* This function returns a pointer to the DER string for the algorithm and indicates its size. */ LIB_EXPORT UINT16 CryptHashGetDer( @@ -258,7 +258,7 @@ CryptHashGetDer( *p = &q->der[0]; return q->derSize; } -/* 10.2.14.4.9 CryptHashGetContextAlg() */ +/* 10.2.13.4.9 CryptHashGetContextAlg() */ /* This function returns the hash algorithm associated with a hash context. */ TPM_ALG_ID CryptHashGetContextAlg( @@ -267,8 +267,8 @@ CryptHashGetContextAlg( { return state->hashAlg; } -/* 10.2.14.5 State Import and Export */ -/* 10.2.14.5.1 CryptHashCopyState */ +/* 10.2.13.5 State Import and Export */ +/* 10.2.13.5.1 CryptHashCopyState */ /* This function is used to clone a HASH_STATE. */ LIB_EXPORT void CryptHashCopyState( @@ -294,7 +294,7 @@ CryptHashCopyState( } return; } -/* 10.2.14.5.2 CryptHashExportState() */ +/* 10.2.13.5.2 CryptHashExportState() */ /* This function is used to export a hash or HMAC hash state. This function would be called when preparing to context save a sequence object. */ void @@ -331,7 +331,7 @@ CryptHashExportState( if(internalFmt->hashAlg != TPM_ALG_NULL) HASH_STATE_EXPORT(externalFmt, internalFmt); } -/* 10.2.14.5.3 CryptHashImportState() */ +/* 10.2.13.5.3 CryptHashImportState() */ /* This function is used to import the hash state. This function would be called to import a hash state when the context of a sequence object was being loaded. */ void @@ -369,8 +369,8 @@ CryptHashImportState( } } } -/* 10.2.14.6 State Modification Functions */ -/* 10.2.14.6.1 HashEnd() */ +/* 10.2.13.6 State Modification Functions */ +/* 10.2.13.6.1 HashEnd() */ /* Local function to complete a hash that uses the hashDef instead of an algorithm ID. This function is used to complete the hash and only return a partial digest. The return value is the size of the data copied. */ @@ -400,7 +400,7 @@ HashEnd( hashState->type = HASH_STATE_EMPTY; return (UINT16)dOutSize; } -/* 10.2.14.6.2 CryptHashStart() */ +/* 10.2.13.6.2 CryptHashStart() */ /* Functions starts a hash stack Start a hash stack and returns the digest size. As a side effect, the value of stateSize in hashState is updated to indicate the number of bytes of state that were saved. This function calls GetHashServer() and that function will put the TPM into failure mode @@ -436,7 +436,7 @@ CryptHashStart( return retVal; } -/* 10.2.14.6.3 CryptDigestUpdate() */ +/* 10.2.13.6.3 CryptDigestUpdate() */ /* Add data to a hash or HMAC, SMAC stack. */ void CryptDigestUpdate( @@ -461,7 +461,7 @@ CryptDigestUpdate( return; } -/* 10.2.14.6.4 CryptHashEnd() */ +/* 10.2.13.6.4 CryptHashEnd() */ /* Complete a hash or HMAC computation. This function will place the smaller of digestSize or the size of the digest in dOut. The number of bytes in the placed in the buffer is returned. If there is a failure, the returned value is <= 0. */ @@ -478,7 +478,7 @@ CryptHashEnd( pAssert(hashState->type == HASH_STATE_HASH); return HashEnd(hashState, dOutSize, dOut); } -/* 10.2.14.6.5 CryptHashBlock() */ +/* 10.2.13.6.5 CryptHashBlock() */ /* Start a hash, hash a single block, update digest and return the size of the results. */ /* The digestSize parameter can be smaller than the digest. If so, only the more significant bytes are returned. */ @@ -498,7 +498,7 @@ CryptHashBlock( CryptDigestUpdate(&state, dataSize, data); return HashEnd(&state, dOutSize, dOut); } -/* 10.2.14.6.6 CryptDigestUpdate2B() */ +/* 10.2.13.6.6 CryptDigestUpdate2B() */ /* This function updates a digest (hash or HMAC) with a TPM2B. */ /* This function can be used for both HMAC and hash functions so the digestState is void so that either state type can be passed. */ @@ -516,7 +516,7 @@ CryptDigestUpdate2B( CryptDigestUpdate(state, bIn->size, bIn->buffer); return; } -/* 10.2.14.6.7 CryptHashEnd2B() */ +/* 10.2.13.6.7 CryptHashEnd2B() */ /* This function is the same as CryptCompleteHash() but the digest is placed in a TPM2B. This is the most common use and this is provided for specification clarity. 'digest.size' should be set to indicate the number of bytes to place in the buffer */ @@ -531,7 +531,7 @@ CryptHashEnd2B( { return CryptHashEnd(state, digest->size, digest->buffer); } -/* 10.2.14.6.8 CryptDigestUpdateInt() */ +/* 10.2.13.6.8 CryptDigestUpdateInt() */ /* This function is used to include an integer value to a hash stack. The function marshals the integer into its canonical form before calling CryptDigestUpdate(). */ LIB_EXPORT void @@ -546,8 +546,8 @@ CryptDigestUpdateInt( #endif CryptDigestUpdate(state, intSize, &((BYTE *)&intValue)[8 - intSize]); } -/* 10.2.14.7 HMAC Functions */ -/* 10.2.14.7.1 CryptHmacStart */ +/* 10.2.13.7 HMAC Functions */ +/* 10.2.13.7.1 CryptHmacStart */ /* This function is used to start an HMAC using a temp hash context. The function does the initialization of the hash with the HMAC key XOR iPad and updates the HMAC key XOR oPad. */ /* The function returns the number of bytes in a digest produced by hashAlg. */ @@ -606,7 +606,7 @@ CryptHmacStart( state->hashState.type = HASH_STATE_HMAC; return hashDef->digestSize; } -/* 10.2.14.7.2 CryptHmacEnd() */ +/* 10.2.13.7.2 CryptHmacEnd() */ /* This function is called to complete an HMAC. It will finish the current digest, and start a new digest. It will then add the oPadKey and the completed digest and return the results in dOut. It will not return more than dOutSize bytes. */ @@ -645,7 +645,7 @@ CryptHmacEnd( } return HashEnd(hState, dOutSize, dOut); } -/* 10.2.14.7.3 CryptHmacStart2B() */ +/* 10.2.13.7.3 CryptHmacStart2B() */ /* This function starts an HMAC and returns the size of the digest that will be produced. */ /* This function is provided to support the most common use of starting an HMAC with a TPM2B key. */ /* The caller must provide a block of memory in which the hash sequence state is kept. The caller @@ -664,7 +664,7 @@ CryptHmacStart2B( { return CryptHmacStart(hmacState, hashAlg, key->size, key->buffer); } -/* 10.2.14.7.4 CryptHmacEnd2B() */ +/* 10.2.13.7.4 CryptHmacEnd2B() */ /* This function is the same as CryptHmacEnd() but the HMAC result is returned in a TPM2B which is the most common use. */ /* Return Values Meaning */ @@ -677,8 +677,8 @@ CryptHmacEnd2B( { return CryptHmacEnd(hmacState, digest->size, digest->buffer); } -/* 10.2.14.8 Mask and Key Generation Functions */ -/* 10.2.14.8.1 _crypi_MGF1() */ +/* 10.2.13.8 Mask and Key Generation Functions */ +/* 10.2.13.8.1 CryptMGF1() */ /* This function performs MGF1 using the selected hash. MGF1 is T(n) = T(n-1) || H(seed || counter). This function returns the length of the mask produced which could be zero if the digest algorithm is not supported */ @@ -722,7 +722,7 @@ CryptMGF1( } return (UINT16)mSize; } -/* 10.2.14.8.2 CryptKDFa() */ +/* 10.2.13.8.2 CryptKDFa() */ /* This function performs the key generation according to Part 1 of the TPM specification. */ /* This function returns the number of bytes generated which may be zero. */ /* The key and keyStream pointers are not allowed to be NULL. The other pointer values may be @@ -813,7 +813,7 @@ CryptKDFa( *counterInOut = counter; return generated; } -/* 10.2.14.8.3 CryptKDFe() */ +/* 10.2.13.8.3 CryptKDFe() */ /* KDFe() as defined in TPM specification part 1. */ /* This function returns the number of bytes generated which may be zero. */ /* The Z and keyStream pointers are not allowed to be NULL. The other pointer values may be diff --git a/src/tpm2/crypto/openssl/CryptHashData.c b/src/tpm2/crypto/openssl/CryptHashData.c index 09452ed9..9a8c7192 100644 --- a/src/tpm2/crypto/openssl/CryptHashData.c +++ b/src/tpm2/crypto/openssl/CryptHashData.c @@ -1,9 +1,9 @@ /********************************************************************************/ /* */ -/* */ +/* Hash ALgorithm Constants */ /* Written by Ken Goldman */ /* IBM Thomas J. Watson Research Center */ -/* $Id: CryptHashData.c 1262 2018-07-11 21:03:43Z kgoldman $ */ +/* $Id: CryptHashData.c 1370 2018-11-02 19:39:07Z kgoldman $ */ /* */ /* Licenses and Notices */ /* */ @@ -55,7 +55,7 @@ /* arising in any way out of use or reliance upon this specification or any */ /* information herein. */ /* */ -/* (c) Copyright IBM Corp. and others, 2016 */ +/* (c) Copyright IBM Corp. and others, 2018 */ /* */ /********************************************************************************/ diff --git a/src/tpm2/crypto/openssl/CryptPrimeSieve.c b/src/tpm2/crypto/openssl/CryptPrimeSieve.c index 57b4500e..4a77de10 100644 --- a/src/tpm2/crypto/openssl/CryptPrimeSieve.c +++ b/src/tpm2/crypto/openssl/CryptPrimeSieve.c @@ -3,7 +3,7 @@ /* CryptPrimeSieve */ /* Written by Ken Goldman */ /* IBM Thomas J. Watson Research Center */ -/* $Id: CryptPrimeSieve.c 1259 2018-07-10 19:11:09Z kgoldman $ */ +/* $Id: CryptPrimeSieve.c 1370 2018-11-02 19:39:07Z kgoldman $ */ /* */ /* Licenses and Notices */ /* */ @@ -370,7 +370,7 @@ SetFieldSize( prime, the function returns FALSE and a new random value needs to be chosen. */ /* Error Returns Meaning */ /* TPM_RC_SUCCESS candidate is probably prime */ -/* TPM_RC_NO_RESULT candidate is not prime and couldn't find and alternative in in the field */ +/* TPM_RC_NO_RESULT candidate is not prime and couldn't find and alternative in the field */ LIB_EXPORT TPM_RC PrimeSelectWithSieve( bigNum candidate, // IN/OUT: The candidate to filter diff --git a/src/tpm2/crypto/openssl/CryptRand.c b/src/tpm2/crypto/openssl/CryptRand.c index 1128421a..d973f3b1 100644 --- a/src/tpm2/crypto/openssl/CryptRand.c +++ b/src/tpm2/crypto/openssl/CryptRand.c @@ -3,7 +3,7 @@ /* DRBG with a behavior according to SP800-90A */ /* Written by Ken Goldman */ /* IBM Thomas J. Watson Research Center */ -/* $Id: CryptRand.c 1311 2018-08-23 21:39:29Z kgoldman $ */ +/* $Id: CryptRand.c 1370 2018-11-02 19:39:07Z kgoldman $ */ /* */ /* Licenses and Notices */ /* */ @@ -538,7 +538,8 @@ CryptRandomGenerate( return DRBG_Generate((RAND_STATE *)&drbgDefault, buffer, (UINT16)randomSize); } /* 10.2.18.4.4 DRBG_InstantiateSeededKdf() */ -/* Function used to instantiate a KDF-based RNG. This is used for derivations */ +/* Function used to instantiate a KDF-based RNG. This is used for derivations. This function always + returns TRUE. */ LIB_EXPORT BOOL DRBG_InstantiateSeededKdf( KDF_STATE *state, // OUT: buffer to hold the state @@ -580,7 +581,8 @@ DRBG_AdditionalData( } /* 10.2.18.4.6 DRBG_InstantiateSeeded() */ /* This function is used to instantiate a random number generator from seed values. The nominal use - of this generator is to create sequences of pseudo-random numbers from a seed value. */ + of this generator is to create sequences of pseudo-random numbers from a seed value. This + function always returns TRUE. */ LIB_EXPORT BOOL DRBG_InstantiateSeeded( DRBG_STATE *drbgState, // IN/OUT: buffer to hold the state @@ -620,7 +622,7 @@ DRBG_InstantiateSeeded( return TRUE; } /* 10.2.18.4.7 CryptRandStartup() */ -/* This function is called when TPM_Startup() is executed. */ +/* This function is called when TPM_Startup() is executed. This function always returns TRUE. */ LIB_EXPORT BOOL CryptRandStartup( void @@ -657,6 +659,9 @@ CryptRandInit( the function returns TRUE without generating any bits or updating the reseed counter. This function returns 0 if a reseed is required. Otherwise, it returns the number of bytes produced which could be less than the number requested if the request is too large. */ +/* Return Value Meaning */ +/* TRUE(1) success */ +/* FALSE(0) failure */ LIB_EXPORT UINT16 DRBG_Generate( RAND_STATE *state, @@ -813,6 +818,8 @@ DRBG_Instantiate( } /* 10.2.18.7 DRBG_Uninstantiate() */ /* This is Uninstantiate_function() from [SP 800-90A 9.4]. */ +/* Error Returns Meaning */ +/* TPM_RC_VALUE not a valid */ LIB_EXPORT TPM_RC DRBG_Uninstantiate( DRBG_STATE *drbgState // IN/OUT: working state to erase diff --git a/src/tpm2/crypto/openssl/CryptRsa.c b/src/tpm2/crypto/openssl/CryptRsa.c index 23a449ba..2e499efa 100644 --- a/src/tpm2/crypto/openssl/CryptRsa.c +++ b/src/tpm2/crypto/openssl/CryptRsa.c @@ -3,7 +3,7 @@ /* Implementation of cryptographic primitives for RSA */ /* Written by Ken Goldman */ /* IBM Thomas J. Watson Research Center */ -/* $Id: CryptRsa.c 1262 2018-07-11 21:03:43Z kgoldman $ */ +/* $Id: CryptRsa.c 1370 2018-11-02 19:39:07Z kgoldman $ */ /* */ /* Licenses and Notices */ /* */ @@ -103,6 +103,10 @@ RsaInitializeExponent( #endif } /* 10.2.19.4.1 ComputePrivateExponent() */ +/* This function computes the private exponent from the primes. */ +/* Return Value Meaning */ +/* TRUE(1) success */ +/* FALSE(0) failure */ static BOOL ComputePrivateExponent( bigNum P, // IN: first prime (size is 1/2 of bnN) @@ -159,6 +163,9 @@ ComputePrivateExponent( /* 10.2.19.4.2 RsaPrivateKeyOp() */ /* This function is called to do the exponentiation with the private key. Compile options allow use of the simple (but slow) private exponent, or the more complex but faster CRT method. */ +/* Return Value Meaning */ +/* TRUE(1) success */ +/* FALSE(0) failure */ static BOOL RsaPrivateKeyOp( bigNum inOut, // IN/OUT: number to be exponentiated diff --git a/src/tpm2/crypto/openssl/CryptSym.c b/src/tpm2/crypto/openssl/CryptSym.c index 58dbf685..091f5507 100644 --- a/src/tpm2/crypto/openssl/CryptSym.c +++ b/src/tpm2/crypto/openssl/CryptSym.c @@ -3,7 +3,7 @@ /* Symmetric block cipher modes */ /* Written by Ken Goldman */ /* IBM Thomas J. Watson Research Center */ -/* $Id: CryptSym.c 1311 2018-08-23 21:39:29Z kgoldman $ */ +/* $Id: CryptSym.c 1370 2018-11-02 19:39:07Z kgoldman $ */ /* */ /* Licenses and Notices */ /* */ @@ -158,7 +158,6 @@ CryptGetSymmetricBlockSize( /* 10.2.20.5 Symmetric Encryption */ /* This function performs symmetric encryption based on the mode. */ /* Error Returns Meaning */ -/* TPM_RC_SUCCESS if success */ /* TPM_RC_SIZE dSize is not a multiple of the block size for an algorithm that requires it */ /* TPM_RC_FAILURE Fatal error */ LIB_EXPORT TPM_RC @@ -302,7 +301,6 @@ CryptSymmetricEncrypt( /* This function performs symmetric decryption based on the mode. */ /* Error Returns Meaning */ /* TPM_RC_FAILURE A fatal error */ -/* TPM_RC_SUCCESS if success */ /* TPM_RCS_SIZE dSize is not a multiple of the block size for an algorithm that requires it */ LIB_EXPORT TPM_RC CryptSymmetricDecrypt( diff --git a/src/tpm2/crypto/openssl/TpmToOsslMath.c b/src/tpm2/crypto/openssl/TpmToOsslMath.c index b1a6a904..95f7867f 100644 --- a/src/tpm2/crypto/openssl/TpmToOsslMath.c +++ b/src/tpm2/crypto/openssl/TpmToOsslMath.c @@ -3,7 +3,7 @@ /* TPM to OpenSSL BigNum Shim Layer */ /* Written by Ken Goldman */ /* IBM Thomas J. Watson Research Center */ -/* $Id: TpmToOsslMath.c 1314 2018-08-28 14:25:12Z kgoldman $ */ +/* $Id: TpmToOsslMath.c 1370 2018-11-02 19:39:07Z kgoldman $ */ /* */ /* Licenses and Notices */ /* */ @@ -185,8 +185,11 @@ MathLibraryCompatibilityCheck( OSSL_LEAVE(); } #endif -/* B.2.3.2.3.2. BnModMult() */ +/* B.2.3.2.3.3. BnModMult() */ /* Does multiply and divide returning the remainder of the divide. */ +/* Return Value Meaning */ +/* TRUE(1) success */ +/* FALSE(0) failure in operation */ LIB_EXPORT BOOL BnModMult( bigNum result, @@ -219,8 +222,11 @@ BnModMult( OSSL_LEAVE(); return OK; } -/* B.2.3.2.3.3. BnMult() */ +/* B.2.3.2.3.4. BnMult() */ /* Multiplies two numbers */ +/* Return Value Meaning */ +/* TRUE(1) success */ +/* FALSE(0) failure in operation */ LIB_EXPORT BOOL BnMult( bigNum result, @@ -249,9 +255,12 @@ BnMult( OSSL_LEAVE(); return OK; } -/* B.2.3.2.3.4. BnDiv() */ +/* B.2.3.2.3.5. BnDiv() */ /* This function divides two bigNum values. The function returns FALSE if there is an error in the operation. */ +/* Return Value Meaning */ +/* TRUE(1) success */ +/* FALSE(0) failure in operation */ LIB_EXPORT BOOL BnDiv( bigNum quotient, @@ -303,8 +312,11 @@ BnDiv( } #if ALG_RSA -/* B.2.3.2.3.5. BnGcd() */ +/* B.2.3.2.3.6. BnGcd() */ /* Get the greatest common divisor of two numbers */ +/* Return Value Meaning */ +/* TRUE(1) success */ +/* FALSE(0) failure in operation */ LIB_EXPORT BOOL BnGcd( bigNum gcd, // OUT: the common divisor @@ -330,9 +342,12 @@ BnGcd( OSSL_LEAVE(); return OK; } -/* B.2.3.2.3.6. BnModExp() */ +/* B.2.3.2.3.7. BnModExp() */ /* Do modular exponentiation using bigNum values. The conversion from a bignum_t to a bigNum is trivial as they are based on the same structure */ +/* Return Value Meaning */ +/* TRUE(1) success */ +/* FALSE(0) failure in operation */ LIB_EXPORT BOOL BnModExp( bigNum result, // OUT: the result @@ -360,8 +375,11 @@ BnModExp( OSSL_LEAVE(); return OK; } -/* B.2.3.2.3.7. BnModInverse() */ +/* B.2.3.2.3.8. BnModInverse() */ /* Modular multiplicative inverse */ +/* Return Value Meaning */ +/* TRUE(1) success */ +/* FALSE(0) failure in operation */ LIB_EXPORT BOOL BnModInverse( bigNum result, @@ -388,8 +406,11 @@ BnModInverse( #endif // TPM_ALG_RSA #if ALG_ECC -/* B.2.3.2.3.8. PointFromOssl() */ +/* B.2.3.2.3.9. PointFromOssl() */ /* Function to copy the point result from an OSSL function to a bigNum */ +/* Return Value Meaning */ +/* TRUE(1) success */ +/* FALSE(0) failure in operation */ static BOOL PointFromOssl( bigPoint pOut, // OUT: resulting point @@ -419,7 +440,7 @@ PointFromOssl( BN_CTX_end(E->CTX); return OK; } -/* B.2.3.2.3.9. EcPointInitialized() */ +/* B.2.3.2.3.10. EcPointInitialized() */ /* Allocate and initialize a point. */ static EC_POINT * EcPointInitialized( @@ -438,7 +459,7 @@ EcPointInitialized( BN_free(bnX); return P; } -/* B.2.3.2.3.10. BnCurveInitialize() */ +/* B.2.3.2.3.11. BnCurveInitialize() */ /* This function initializes the OpenSSL() group definition */ /* It is a fatal error if groupContext is not provided. */ /* Return Values Meaning */ @@ -501,7 +522,7 @@ BnCurveInitialize( return OK ? E : NULL; } /* B.2.3.2.3.11. BnEccModMult() */ -/* This function does a point multiply of the form R = [d]S */ +/* This functi2n does a point multiply of the form R = [d]S */ /* Return Values Meaning */ /* FALSE failure in operation; treat as result being point at infinity */ LIB_EXPORT BOOL @@ -525,7 +546,7 @@ BnEccModMult( BN_free(bnD); return !BnEqualZero(R->z); } -/* B.2.3.2.3.12. BnEccModMult2() */ +/* B.2.3.2.3.13. BnEccModMult2() */ /* This function does a point multiply of the form R = [d]G + [u]Q */ /* FALSE failure in operation; treat as result being point at infinity */ LIB_EXPORT BOOL diff --git a/src/tpm2/crypto/openssl/TpmToOsslSupport.c b/src/tpm2/crypto/openssl/TpmToOsslSupport.c index 4706e06f..8b63f3ed 100644 --- a/src/tpm2/crypto/openssl/TpmToOsslSupport.c +++ b/src/tpm2/crypto/openssl/TpmToOsslSupport.c @@ -3,7 +3,7 @@ /* */ /* Written by Ken Goldman */ /* IBM Thomas J. Watson Research Center */ -/* $Id: TpmToOsslSupport.c 809 2016-11-16 18:31:54Z kgoldman $ */ +/* $Id: TpmToOsslSupport.c 1314 2018-08-28 14:25:12Z kgoldman $ */ /* */ /* Licenses and Notices */ /* */