Upload
others
View
17
Download
0
Embed Size (px)
Citation preview
Ethemba Trusted Host Environment Mainly Based on Attestationa framework and demonstrator for TPM applications
Andreas [email protected]
Andreas [email protected]
March 1, 2009
This work was supported byDr. Andreas U. Schmidt (CREATE-NET)
Nicolai Kuntze (Fraunhofer-SIT)
Contents
1 apps 7
1.1 ClearOwnership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.1.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.1.2 PUBLIC main . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.2 TakeOwnership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91.2.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91.2.2 PUBLIC main . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.3 CreateServerKeyPair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101.3.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101.3.2 PUBLIC main . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.4 ManageKnownHashesList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.4.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.4.2 PUBLIC main . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.5 PCAclient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131.6 PCAserver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161.7 RAclient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171.8 RAserver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2 jTPMtools 21
2.1 AikUtil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.2 Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.3 PrivacyCa . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
3 modules 25
3.1 client.CertDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263.1.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263.1.2 PUBLIC getCert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263.1.3 PUBLIC putCert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263.1.4 PUBLIC removeCert . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263.1.5 PUBLIC exportCert . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.2 client.CertifyKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283.2.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283.2.2 CONSTRUCTOR CertifyKey . . . . . . . . . . . . . . . . . . . . . . . . 283.2.3 PUBLIC run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293.2.4 PUBLIC serializeResult . . . . . . . . . . . . . . . . . . . . . . . . . . 293.2.5 PUBLIC deserializeResult . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.3 client.CreateKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3
4 Contents
3.3.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313.3.2 CONSTRUCTOR CreateKey . . . . . . . . . . . . . . . . . . . . . . . . 313.3.3 PUBLIC run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.4 client.DataBinding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323.4.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323.4.2 CONSTRUCTOR DataBinding . . . . . . . . . . . . . . . . . . . . . . . 323.4.3 PUBLIC run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.5 client.DataUnbinding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333.5.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333.5.2 CONSTRUCTOR DataUnbinding . . . . . . . . . . . . . . . . . . . . . 333.5.3 PUBLIC run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3.6 client.QuoteRetrieval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343.6.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343.6.2 CONSTRUCTOR QuoteRetrieval . . . . . . . . . . . . . . . . . . . . . 343.6.3 PUBLIC run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
3.7 client.TpmKeyDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363.7.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363.7.2 PUBLIC getUUID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363.7.3 PUBLIC putUUID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363.7.4 PUBLIC removeUUID . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.8 server.CertifyKeyValidaton . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383.8.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383.8.2 CONSTRUCTOR CertifyKeyValidaton . . . . . . . . . . . . . . . . . . 383.8.4 PUBLIC run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
3.9 server.ExternalDataBinding . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403.9.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403.9.2 CONSTRUCTOR ExternalDataBinding . . . . . . . . . . . . . . . . . . 403.9.3 PUBLIC run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
3.10 server.KeyStorage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413.10.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413.10.5 PUBLIC getPublicKeyFile . . . . . . . . . . . . . . . . . . . . . . . . . 423.10.6 PUBLIC getPrivateKeyFile . . . . . . . . . . . . . . . . . . . . . . . . 423.10.7 PUBLIC getPublicKey . . . . . . . . . . . . . . . . . . . . . . . . . . . 423.10.8 PUBLIC getPrivateKey . . . . . . . . . . . . . . . . . . . . . . . . . . . 433.10.9 PUBLIC put . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433.10.10PUBLIC putPublicKey . . . . . . . . . . . . . . . . . . . . . . . . . . . 433.10.11PUBLIC putPrivateKey . . . . . . . . . . . . . . . . . . . . . . . . . . 44
3.11 server.QuoteValidation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453.11.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453.11.2 CONSTRUCTOR QuoteValidation . . . . . . . . . . . . . . . . . . . . . 453.11.5 PUBLIC run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
4 net 49
4.1 NetEntity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Contents 5
4.1.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504.1.2 CONSTRUCTOR NetEntity . . . . . . . . . . . . . . . . . . . . . . . . . 504.1.3 PUBLIC init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504.1.4 PUBLIC close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504.1.5 PUBLIC sendACK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514.1.6 PUBLIC sendNACK . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514.1.7 PUBLIC sendCommand . . . . . . . . . . . . . . . . . . . . . . . . . . 514.1.8 PUBLIC sendObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524.1.9 PUBLIC receiveACK . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524.1.10 PUBLIC receiveCommand . . . . . . . . . . . . . . . . . . . . . . . . 524.1.11 PUBLIC receiveObject . . . . . . . . . . . . . . . . . . . . . . . . . . . 534.1.12 PUBLIC getRemoteIP . . . . . . . . . . . . . . . . . . . . . . . . . . . 534.1.13 PUBLIC getRemoteHostname . . . . . . . . . . . . . . . . . . . . . . 53
4.2 NetCommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554.2.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
5 types 57
5.1 MeasurementList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585.1.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585.1.2 CONSTRUCTOR MeasurementList . . . . . . . . . . . . . . . . . . . . 585.1.3 PUBLIC getMeasurementList . . . . . . . . . . . . . . . . . . . . . . 585.1.4 PUBLIC getMeasurementListForPCR . . . . . . . . . . . . . . . . . . 585.1.5 PUBLIC loadFromFile . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.2 KnownHashesList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605.2.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605.2.2 CONSTRUCTOR KnownHashesList . . . . . . . . . . . . . . . . . . . . 605.2.3 PUBLIC put . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605.2.4 PUBLIC get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605.2.5 PUBLIC containsTag . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615.2.6 PUBLIC containsSha1Hash . . . . . . . . . . . . . . . . . . . . . . . . 615.2.7 PUBLIC contains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615.2.8 PUBLIC saveToFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625.2.9 PUBLIC loadFromFile . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
6 utils 63
6.1 AES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646.1.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646.1.2 CONSTRUCTOR AES . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646.1.3 PUBLIC encryptObject . . . . . . . . . . . . . . . . . . . . . . . . . . 646.1.4 PUBLIC encrypt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646.1.5 PUBLIC decryptObject . . . . . . . . . . . . . . . . . . . . . . . . . . 656.1.6 PUBLIC decrypt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656.1.8 PUBLIC generateKey . . . . . . . . . . . . . . . . . . . . . . . . . . . 666.1.9 PUBLIC generateKey . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
6 Contents
6.1.10 PUBLIC generateIV . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676.2 Helpers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
6.2.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 686.2.2 PUBLIC byteToHexString . . . . . . . . . . . . . . . . . . . . . . . . . 686.2.3 PUBLIC hexStringToByteArray . . . . . . . . . . . . . . . . . . . . . . 686.2.4 PUBLIC leadingZeroes . . . . . . . . . . . . . . . . . . . . . . . . . . 686.2.5 PUBLIC saveObjectToFile . . . . . . . . . . . . . . . . . . . . . . . . . 696.2.6 PUBLIC saveBytesToFile . . . . . . . . . . . . . . . . . . . . . . . . . 696.2.7 PUBLIC loadObjectFromFile . . . . . . . . . . . . . . . . . . . . . . . 696.2.8 PUBLIC loadBytesFromFile . . . . . . . . . . . . . . . . . . . . . . . 706.2.9 PUBLIC Object2Bytes . . . . . . . . . . . . . . . . . . . . . . . . . . . 706.2.10 PUBLIC Bytes2Object . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
6.3 SHA1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726.3.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726.3.2 PUBLIC main . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726.3.3 PUBLIC hashByteToByte . . . . . . . . . . . . . . . . . . . . . . . . . 726.3.4 PUBLIC hashHex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726.3.5 PUBLIC hash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 736.3.6 PUBLIC randomHash . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
7 Demonstrators 75
7.1 demogood.sh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757.2 demoevil.sh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
8 Settings 77
References 81
1 apps
DE.FRAUNHOFER.SIT.TC.ETHEMBA.APPS
This package contains applications for TPM maintenance on the one hand and client-and server-applications that implement AIK-Certification and Remote-Attestation onthe other hand.
• TakeOwnership and ClearOwnership permit TPM activation capabilities
• ManageKnownHashesList helps managing hash lists, that define trusted applica-tions used in Remote-Attestation on the server-side
• PCAserver and PCAclient implement AIK-Certification
• RAserver and RAclient implement Remote-Attestation
7
8 1 apps
1.1 ClearOwnership
1.1.1 Description
ClearOwnership clears the ownership of the TPM. The code is mainly based on the orig-inal jTpmtools (see References) application. It can be used in the process of resetting theTPM to its initial state. A reboot might be required for changes to take effect. The currentowner password is supplied as command-line parameter.
For convenience and tests, the switch /f provides a fixed mode, reading the globally setowner password.
Note: In our test scenario, routing the TPM-Emulator into a virtualized sub-system, wewere able to clear the ownership without supplying the correct owner password. It is stillto be clarified, if this is an issue with the emulated environment or the implementationin jTSS.
1.1.2 PUBLIC main
DescriptionCalled when used in command-line.
SettingsOwnerPwd
ParametersSTRING[] args [1] owner password or globally set owner password
when used in fixed mode (’/f’).
OutputIf no command line parameters are given, a usage information is displayed.
1.2 TakeOwnership 9
1.2 TakeOwnership
1.2.1 Description
TakeOwnership allows taking ownership of the TPM. The owner password is set, a newSRK is generated inside the TPM and the SRK password is set. The code is mainly basedon the original jTpmtools (see References) application.
The owner and SRK passwords are supplied as command-line parameters. For conve-nience and tests, the switch ’/f’ provides a fixed mode, reading the globally set ownerand SRK passwords.
1.2.2 PUBLIC main
DescriptionCalled when used in command-line.
SettingsOwnerPwd, SRKPwd
ParametersSTRING[] args [1] owner password or ’/f’ for fixed mode
[2] srk password
OutputIf no command line parameters are given, a usage information is displayed.
10 1 apps
1.3 CreateServerKeyPair
1.3.1 Description
CreateServerKeypair is used to create a keypair for usage in server applications. Thekeys are stored in server.KeyStorage. The keysize and the algorithm are taken from Set-tings.
1.3.2 PUBLIC main
DescriptionCreates the a public/private keypair and stores it in the server.KeyStorage. The keypaircan later be accessed via the given label
SettingsServerKeyAlgorithm, ServerKeySize
ParametersSTRING[] args [0] label to use for the key
1.4 ManageKnownHashesList 11
1.4 ManageKnownHashesList
1.4.1 Description
ManageKnownHashesList takes an IMA-formatted file as input and converts it to a Known-HashesList. This application can be used to create and maintain a database of knownhashes. Used in append-mode (command line parameter /a), the contents of the inputwill be appended to the database. Used in overwrite-mode (command line parameter/o), the contents of the input will overwrite an existing database. If no command lineparameter is given, a management console is presented to the user, allowing for view,search and remove entries of the database.
1.4.2 PUBLIC main
DescriptionCalled when used in command-line.
SettingsRAServer_KnownHashesList
ParametersSTRING[] args [1] /a or /o to enable append- or overwrite-mode
(optional)[2] filename of IMA-Measurement-File to be usedwhen [1] is set
OutputIf no command line parameters are given, a management console providing view, searchand remove functions is presented to the user. Otherwise the new or updated databaseof known hashes is stored in RAServer_KnownHashesList.
1.4.3 PRIVATE append
Descriptionappends contents of given IMA-Measurement-File to existing database.
SettingsRAServer_KnownHashesList
ParametersSTRING file IMA-Measurement-File
12 1 apps
1.4.4 PRIVATE overwrite
Descriptionoverwrites existing database with contents of given IMA-Measurement-File.
SettingsRAServer_KnownHashesList
ParametersSTRING file IMA-Measurement-File
1.4.5 PRIVATE view
Descriptiondisplays the entries contained in the KnownHashesList pagewise (blocks of 10 entries)
Settingsnone
Parametersnone
1.4.6 PRIVATE search
Descriptiondisplays the entries contained in the KnownHashesList matching the given search string
Settingsnone
ParametersSTRING s search string to be used
1.4.7 PRIVATE remove
Descriptionremoves entries contained in the KnownHashesList matching the given search string
Settingsnone
ParametersSTRING s search string to be used
1.5 PCAclient 13
1.5 PCAclient
The PCAclient can be used to create and certify an AIK. The client creates a new AIK usingthe TPM_CollateIdentityRequest. The public part of it is sent to a PCAserver, includingthe Endorsement Certificate. They are encrypted using the PCAserver’s public key. Uponreceipt, the PCAserver can decrypt the contents and verify the Endorsement Certificate.The PCAserver then creates a random nonce and wraps it for the client. The responsecontains two parts:
1. a symmetric session key and the hash of the AIK public key, both encrypted withthe EK public key
2. the nonce, encrypted with the session key
for details see PrivacyCa state3_sub.
Using the TPM_ActivateIdentity command, the TPM can decrypt the answer and thenonce is revealed to the client. Only the client with the TPM used for creation of theAIK is able to decrypt the nonce. The client then sends the decrypted nonce back to thePCAserver.
Upon receipt and verification, the PCAserver will create a certificate for the AIK. It isthen encrypted using an AES key. The AES key is wrapped for the client using the samescheme as for the nonce, thus the response consists of three parts:
1. a symmetric session key and the hash of the AIK public key, both encrypted withthe EK public key
2. the AES key encrypted with the session key
3. the AIK-Certificate, encrypted with the AES key
for details see PrivacyCa state5_sub.
The AIK is activated by the client via a TPM_ActivateIdentity call. The AES key is de-crypted and can be used to decrypt the AIK-Certificate.
The client then assigns a UUID to the AIK and stores it in the System Persistent Storageof jTSS. For later access, the key is registered in the client.TpmKeyDB using the providedAIK-label. As final step the AIK-Certificate is stored in the client.CertDB.
The client is separated into different methods representing each state of the protocol.The methods are called subsequently.
14 1 apps
Figure 1.1: protocol diagram for AIK-Certification
1.5 PCAclient 15
Parametersowner password needed to load the EK certificate / EK public keySRK password needed to store the new AIKAIK password will be needed when the AIK is accessed later onAIK label a label providing identification of the AIK. This
label can later be used to load the AIK fromclient.TpmKeyDB and will also be included in the cer-tificate.
PCA server IP address IP address of the PCA serverPCA server port port of the PCA server, see Settings for default value
All required parameters can be set from the command-line, a fixed mode is provided viathe switch ’/f’. The required parameters will then be read from Settings.
16 1 apps
1.6 PCAserver
The server is separated into different methods representing each state of the AIK-Certificationprotocol. The methods are called subsequently.
→ see PCAclient for a detailed description of the AIK-Certification protocol
1.7 RAclient 17
1.7 RAclient
The RAclient can be used to perform a Remote-Attestation. Integrated MeasurementArchitecture (IMA) is used to provide runtime analysis of the client’s system state. PCR-10 is constantly being extended with hashes of newly run programs. A client is beingattested by a Remote-Attestation-Server by sending an AIK-signed quote of PCR-10 alto-gether with the corresponding AIK-Certificate and a MeasurementList to the server.
The quote is protected from replay-attacks by including a nonce, the Remote-Attestation-Server challenged the client with. By letting the TPM quote PCR-10 internally, integrityof PCR-10 is ensured.
Upon receipt, the Remote-Attestation-Server performs several checks to attests the client’ssystem state. First of all the AIK-Certificate is checked for validity (timestamp, signatureand trusted issuer). Then the submitted MeasurementList is validated by checking eachrun application for known and trusted hashes. This results in a re-calculated PCR-10. Atlast the submitted quote is being validated by checking its signature, the included nonce(for anti-replay!) and equality of the included PCR-10 and the re-calculated one.
This equality check is highly required to ensure an attacker did not trick the Remote-Attestation-Server by submitting a fake MeasurementList.
After verification the client will receive a certificate from RAserver certifying platformintegrity. Note that this certificate has to be invalid after a short period of time, as theclient’s state might change very quickly.
The RAclient stores the Attestation-Certificate in the client.CertDB using a new UUID.The UUID for the Attestation-Certificate is based on the UUID of the AIK used in the pro-tocol. It can be accessed for later use via the UUID00000009-0008-0007-0605-aikUuid.getNode().
The client is separated into different methods representing each state of the protocol.The methods are called subsequently.
ParametersSRK password needed to load the AIKAIK password needed to load the AIKAIK label the label the to be used AIK is stored underRA server IP address IP address of the RA serverRA server port port of the RA server, see Settings for default value
All required parameters can be set from the command-line, a fixed mode is provided viathe switch ’/f’. The required parameters will then be read from Settings.
18 1 apps
Figure 1.2: protocol diagram for Remote Attestation
1.8 RAserver 19
1.8 RAserver
The server is separated into different methods representing each state of the Remote-Attestation protocol. The methods are called subsequently.
→ see RAclient for a detailed description of the Remote-Attestation protocol
2 jTPMtools
DE.FRAUNHOFER.SIT.TC.ETHEMBA.JTPMTOOLS
This package contains modified source-code taken from jTPMtools.
21
22 2 jTPMtools
2.1 AikUtil
This class was copied and modified from IAIK.TC.APPS.JTT.AIK.AIKUTIL.
It is used within PCAclient to create EK-Certificates on-the-fly (which are passed to thePCAserver). Additionally it is indirectly used within PCAserver and directly used withinPrivacyCa to create AIK-Certificates (which are passed to the PCAclient).
Modifications applied:
• changed AIK-Certificate creation to use ethemba’s global settings for certificateattributes
• changed CA-Certificate creation to use ethemba’s global settings for certificate at-tributes
• changed EK-Certificate creation to use ethemba’s global settings for certificate at-tributes
• changed PE-Certificate creation to use ethemba’s global settings for certificate at-tributes
2.2 Client 23
2.2 Client
This class was copied and slightly modified from IAIK.TC.APPS.JTT.AIK.CLIENT.
It is used within PCAclient in state3 to run a TPM_CollateIdentityRequest command andin state4 and state6 to run a TPM_ActivateIdentity command.
Modifications applied:
• changed visibility of activateIdentity from protected to public to have outer access
• changed visibility of collateIdentityReq from protected to public to have outer ac-cess
• changed visibility of overrideEkCertificate from protected to public to have outeraccess
24 2 jTPMtools
2.3 PrivacyCa
This class was copied and modified from IAIK.TC.APPS.JTT.AIK.PRIVACYCA.
It is used within PCAserver to process the collateIdentity request blob received from thePCAclient and wrapping a server-generated nonce inside a TPM blob that can only beaccessed by the TPM itself.
In another state of the AIK-Certification protocol (see PCAclient) the second collateI-dentity request blob received from the PCAclient is being processed and the resultingAIK-Certificate is again wrapped inside a TPM blob that can only be accessed by theTPM itself.
See PCAclient for detailed information on the AIK-Certification protocol.
Modifications applied: Two new methods were added to implement a handshake in theAIK-Certification protocol. The state3_sub method provides the wrapping of the server-generated nonce for the client instead of transmitting the certificate in the first step. Instate3_sub the EK certificate is already validated.
In this design, clients without a valid EK certificate will be rejected at an early stage in theprotocol. A later verification of the EK certificate might be advantageous as it decreasesthe burden on the PCA in case the protocol stops during nonce verification. The AIK-Certificate is not issued in this stage.
The method state5_sub provides a secure wrapping for the AIK-Certificate. First the AIK-Certificate is generated. A new one-time symmetric AES key is being generated and usedto encrypt the certificate. The response consists of three parts:
1. a symmetric session key and the hash of the AIK public key, both encrypted asym-metrically with the public EK of the client. Via this indirection, only the client isable to decrypt the session key.
2. the symmetric (AES) key previously used to encrypt the AIK-Certificate, encryptedwith the session key
3. the AIK-Certificate, encrypted with the AES key
The client can then decrypt the session key using the TPM_ActivateIdentity function ofthe TPM. This reveals the AES key, which can then in turn be used to decrypt the AIK-Certificate.
3 modules
DE.FRAUNHOFER.SIT.TC.ETHEMBA.MODULES
This package contains modules providing storage/mapping methods for keys and cer-tificates on the one hand and modules providing convenient TPM method handling (e.g.quote, bind, certify etc.) on the other hand.
25
26 3 modules
3.1 client.CertDB
3.1.1 Description
CertDB saves X509-Certificates in a database mapping it to given UUIDs.
3.1.2 PUBLIC getCert
Descriptionreturns the corresponding certificate for the given UUID
SettingsCertDBfile
ParametersTCTSSUUID uuid UUID of the certificate
OutputX509CERTIFICATE corresponding certificate
3.1.3 PUBLIC putCert
Descriptionputs a given certificate into the CertDB using the given UUID
SettingsCertDBfile
ParametersTCTSSUUID uuid UUID of the certificateX509CERTIFICATE cert certificate to be put into the CertDB
3.1.4 PUBLIC removeCert
Descriptionremoves a certificate from the CertDB
SettingsCertDBfile
ParametersTCTSSUUID uuid UUID of the certificate
3.1 client.CertDB 27
3.1.5 PUBLIC exportCert
Descriptionexports a certificate to the disk
SettingsCertDBfile
ParametersTCTSSUUID uuid UUID of the certificateSTRING outputFile location of the exported certificate
3.1.6 PRIVATE loadDB
Descriptionloads the CertDB from the globally defined location
SettingsCertDBfile
Parametersnone
OutputHASHTABLE<STRING, BYTE[]> loaded database
3.1.7 PRIVATE saveDB
Descriptionsaves a given CertDB to the globally defined location
SettingsCertDBfile
ParametersHASHTABLE<STRING,BYTE[]> db
database to be saved
28 3 modules
3.2 client.CertifyKey
3.2.1 Description
This client module can be used to create and certify a TPM key for binding or sealing.The created key is signed by a given AIK.
Figure 3.1: Creation of a CSK (Certified Signing Key) using a certified AIK
3.2.2 CONSTRUCTOR CertifyKey
Descriptiontakes the given input values and stores them internally for later passing it to the TPM viathe run method
Settingsnone
ParametersBOOLEAN isBindingKey create a binding key (TRUE ) or sealing key (FALSE )BOOLEAN isVolatile volatile or non-volatile keySTRING srkPwd SRK-PasswordSTRING keyPwd Key-PasswordSTRING keyLabel Label to store created key underINT[] pcrSelection array to define, to which PCRs the key shall be bound
to (optional)BYTE[] nonce nonce to be included in certification (anti-replay!)STRING aikPwd AIK-PasswordSTRING aikLabel Label of AIK to be used for signing
3.2 client.CertifyKey 29
3.2.3 PUBLIC run
DescriptionImplements the necessary steps to create and certify a TPM key using the TPM. First theSRK (to store the key under) and AIK (to sign the key) are loaded and key attributes for thenewly created key are being assigned. Then a composite object is created holding the se-lected PCRs given via the constructor. This data is passed to the TPM using the certifyKeymethod provided by jTSS (see References). After creating/certifying the key, it is stored inthe persistent storage and labeled with the given keyLabel. An OBJECT[] is returned con-taining everything needed in server.CertifyKeyValidaton:
• TCBLOBDATA public key
• TCTSSVALIDATION keyCertification
• X509CERTIFICATE AIK-Certificate
SettingspwdEncoding, TPM_KeySize
Parametersnone
OutputOBJECT[] containing [1] TCBLOBDATA public key, [2] TCTSSVALIDATION keyCertifica-tion, [3] X509CERTIFICATE AIK-Certificate
3.2.4 PUBLIC serializeResult
Descriptionserializes a certifyKeyResult
Settings
ParametersOBJECT[] certifyKeyRe-sult
certifyKeyResult to be serialized
OutputSTRING[] containing the serialized certifyKeyResult
30 3 modules
3.2.5 PUBLIC deserializeResult
Descriptiondeserializes a once serialized certifyKeyResult
Settings
ParametersSTRING[] certifyKeyRe-sult
serialized certifyKeyResult to be deserialized
OutputOBJECT[] containing the deserialized certifyKeyResult
3.3 client.CreateKey 31
3.3 client.CreateKey
3.3.1 Description
This client module can be used to create a TPM key for binding or sealing.
3.3.2 CONSTRUCTOR CreateKey
Descriptiontakes the given input values and stores them internally for later passing it to the TPM viathe run method
Settingsnone
ParametersBOOLEAN isBindingKey create a binding key (TRUE ) or sealing key (FALSE )BOOLEAN isVolatile volatile or non-volatile keyBOOLEAN isMigratable migratable or non-migratable keySTRING srkPwd SRK-PasswordSTRING keyPwd Key-PasswordSTRING keyLabel Label to store created key underINT[] pcrSelection array to define, to which PCRs the key shall be bound
to (optional)
3.3.3 PUBLIC run
DescriptionImplements the necessary steps to create a TPM key using the TPM. First the SRK (tostore the key under) is loaded and key attributes for the newly created key are beingassigned. Then a composite object is created holding the selected PCRs given via theconstructor. This data is passed to the TPM using the createKey method provided byjTSS (see References). After creating the key, it is stored in the persistent storage and la-beled with the given keyLabel.
SettingspwdEncoding, TPM_KeySize
Parametersnone
OutputTCBLOBDATA public part of created keypair
32 3 modules
3.4 client.DataBinding
3.4.1 Description
This client module can be used to bind (i.e. encrypt) data to the TPM. The bound datacan only be unbound (i.e. decrypted) inside this TPM.
3.4.2 CONSTRUCTOR DataBinding
Descriptiontakes the given input values and stores them internally for later processing in the runmethod
Settingsnone
ParametersBYTE[] data data to be bound/encryptedSTRING srkPwd SRK-PasswordSTRING keyPwd Key-PasswordSTRING keyLabel Label of the key to be used to bind the data
3.4.3 PUBLIC run
DescriptionImplements the necessary steps to bind the given data using the public key belongingto the given keyLabel. First the key is loaded using the SRK. Then data is separated intochunks matching the keysize and passed to the bind method provided by jTSS (see Ref-erences).
SettingspwdEncoding, TPM_KeySize
Parametersnone
OutputBYTE[] bound/encrypted data
3.5 client.DataUnbinding 33
3.5 client.DataUnbinding
3.5.1 Description
This client module can be used to unbind (i.e. decrypt) once bound data.
3.5.2 CONSTRUCTOR DataUnbinding
Descriptiontakes the given input values and stores them internally for later processing in the runmethod
Settingsnone
ParametersBYTE[] data data to be bound/encryptedSTRING srkPwd SRK-PasswordSTRING keyPwd Key-PasswordSTRING keyLabel Label of the key to be used to unbind the data
3.5.3 PUBLIC run
DescriptionImplements the necessary steps to unbind the given data using the public key belongingto the given keyLabel. First the key is loaded using the SRK. Then data is separated intochunks matching the keysize and passed to the unbind method provided by jTSS (seeReferences).
SettingspwdEncoding
Parametersnone
OutputBYTE[] unbound/decrypted data
34 3 modules
3.6 client.QuoteRetrieval
3.6.1 Description
This client module can be used to request and retrieve a quote from the TPM. The quoteincludes the signed hash value of the desired PCRs and a signed nonce, as replay pro-tection. The client must provide a valid certificate for the key used to sign the quote.Normally an AIK is used to sign the quote, so a previously acquired AIK certificate fromPCAclient/PCAserver can be used to verify the quote.
3.6.2 CONSTRUCTOR QuoteRetrieval
Descriptiontakes the given input values and stores them internally for later retrieval of the quote viathe run method
Settingsnone
ParametersINT[] pcrSelection array to define which PCRs shall be included in the
quoteBYTE[] nonce nonce to be included in quote (→ replay protection)STRING srkPwd SRK password, needed to load the AIKSTRING aikPwd AIK password, needed to load the AIKSTRING aikLabel label that has been assigned to the AIK in a PCA pro-
cess
3.6.3 PUBLIC run
DescriptionImplements the necessary steps to retrieve the quote from the TPM. First the AIK isloaded using the SRK. Then a composite object is created holding the selected PCRsgiven via the constructor. This data altogether with the nonce is passed to the TPM us-ing the quote method provided by jTSS (see References). After retrieving the quote, theAIK is unloaded from the TPM and the quote is returned to the calling method.
SettingspwdEncoding
Parametersnone
3.6 client.QuoteRetrieval 35
OutputTCTSSVALIDATION the quote that was retrieved from the TPM
36 3 modules
3.7 client.TpmKeyDB
3.7.1 Description
TpmKeyDB maps labels to UUIDs. This is used to allow convenient access to keys gen-erated by the TPM. Those keys are separated by TPM generated UUIDs which are ratherdifficult to remember. TpmKeyDB allows to assign labels to those UUIDs and to accessthem in an easy way.
3.7.2 PUBLIC getUUID
Descriptionreturns the corresponding UUID for the given label
SettingsTpmKeyDBfile
ParametersSTRING label label to get the UUID for
OutputTCTSSUUID corresponding UUID for the given label
3.7.3 PUBLIC putUUID
Descriptionputs a label ⇔ UUID mapping to the TpmKeyDB
SettingsTpmKeyDBfile
ParametersSTRING label label to be usedTCTSSUUID uuid UUID to be used
3.7.4 PUBLIC removeUUID
Descriptionremoves a label ⇔ UUID mapping from the TpmKeyDB
SettingsTpmKeyDBfile
3.7 client.TpmKeyDB 37
ParametersSTRING label label whose mapping is to be removed
3.7.5 PRIVATE loadDB
Descriptionloads the TpmKeyDB from the globally defined location
SettingsTpmKeyDBfile
Parametersnone
OutputHASHTABLE<STRING, STRING> loaded database
3.7.6 PRIVATE saveDB
Descriptionsaves a given TpmKeyDB to the globally defined location
SettingsTpmKeyDBfile
ParametersHASHTABLE<STRING,STRING> db
database to be saved
38 3 modules
3.8 server.CertifyKeyValidaton
3.8.1 Description
This server module can be used to validate a given output of a client.CertifyKey com-mand. The included keyCertification is equipped with a signature and contains a nonce(→ replay protection). First the signature is checked for validity, then the nonce is matchedagainst the challenged one (see client.CertifyKey). At last the digests of the included pub-lic key and the one contained in the output of client.CertifyKey are checked for identical-ness.
Note: CertifyKeyValidation only checks the result of a client.CertifyKey command for va-lidity. One should verify the included AIK-Certificate for trustability after successful val-idation. The included public key may then be used in further steps.
3.8.2 CONSTRUCTOR CertifyKeyValidaton
Descriptiontakes the given input values and stores them internally for later validation of the certifi-cation via the run method
Settingsnone
ParametersOBJECT[] certifyKeyRe-sult
result of the client.CertifyKey command, containspublic key, keyCertification and AIK-Certificate
BYTE[] nonce nonce that was challenged and to validate the certi-fication against
3.8.3 PRIVATE createDigestInfoDER
Descriptioncode from jTPM-Tools. It is used to return the digestInfo properly out of the certification.
Settingsnone
ParametersTCBLOBDATA digest digest to be properly encoded
OutputTCBLOBDATA digestInfo used during verification of the certification signature
3.8 server.CertifyKeyValidaton 39
3.8.4 PUBLIC run
DescriptionImplements the necessary steps to validate the given output of a previous client.CertifyKeycommand.
First the signature of the keyCertification is validated against the AIK-Certificate includedin client.CertifyKey’s output. Then the nonce is checked against the given one. Finally thepublic key included in the output is checked against the one signed in the keyCertifica-tion.
Note: Please be aware that this method only validates the output without verifying thetrustability of the contained AIK-Certificate. This should be done after a successful vali-dation.
Settingsnone
Parametersnone
OutputBOOLEAN TRUE if certification is valid, else FALSE
40 3 modules
3.9 server.ExternalDataBinding
3.9.1 Description
This server module can be used to bind (i.e. encrypt) data to an external TPM using apublic key of a TPM keypair resident inside the TPM. Bound data can only be unbound(i.e. decrypted) inside the TPM it was bound to.
3.9.2 CONSTRUCTOR ExternalDataBinding
Descriptiontakes the given input values and stores them internally for later processing in the runmethod
Settingsnone
ParametersBYTE[] data data to be bound/encryptedTCBLOBDATA key public key to be used to bind data
3.9.3 PUBLIC run
DescriptionImplements the necessary steps to bind the given data using the given public key. Datais separated into chunks matching the keysize and passed to the bind method providedby jTSS (see References).
SettingsTPM_KeySize
Parametersnone
OutputBYTE[] bound/encrypted data to be passed to the corresponding TPM
3.10 server.KeyStorage 41
3.10 server.KeyStorage
3.10.1 Description
The server module server.KeyStorage provides easy access to save and load functions forserver keys. It can be used to store public/private keypairs and provides an interfaceto retrieve the keys via tags. It is used by PCAserver and RAserver to store their signingkeys. If a keypair with the specified tag already exists, the older one will be overwrit-ten.
3.10.2 PRIVATE loadFromFile
Descriptionloads the mapping file from the predefined filesystem-location.
SettingsKeyStorageBaseDir, KeyStorageDB
Parametersnone
3.10.3 PRIVATE saveToFile
Descriptionsaves the mapping to the predefined filesystem-location
SettingsKeyStorageBaseDir, KeyStorageDB
Parametersnone
3.10.4 PRIVATE getMapping
Descriptionreturns the filename mapped to the given tag
Settingsnone
ParametersSTRING tag tag to be searched for
42 3 modules
OutputSTRING[] filenames of key files mapped to the tag
[0] public keyfile [1] private keyfile
3.10.5 PUBLIC getPublicKeyFile
Descriptionreturns the filename of the public key
SettingsKeyStorageBaseDir
ParametersSTRING tag keypair tag
OutputSTRING the filename of the public key to the given tag
3.10.6 PUBLIC getPrivateKeyFile
Descriptionreturns the filename of the private key
SettingsKeyStorageBaseDir
ParametersSTRING tag keypair tag
OutputSTRING the filename of the private key to the given tag
3.10.7 PUBLIC getPublicKey
Descriptionget the public key as PUBLICKEY for the given tag
Settingsnone
ParametersSTRING tag keypair tag
3.10 server.KeyStorage 43
OutputPUBLICKEY stored under the given tag
3.10.8 PUBLIC getPrivateKey
Descriptionget the private key as PRIVATEKEY for the given tag
Settingsnone
ParametersSTRING tag keypair tag
OutputPRIVATEKEY stored under the given tag
3.10.9 PUBLIC put
Descriptionput stores the given keypair in the files specified by the user. The user must provide a tagby which the keys can be accessed later. The keys will be stored in Settings.KeyStorageBaseDir,the mapping of tags to keys is stored in Settings.KeyStorageDB.
SettingsKeyStorageBaseDir
ParametersSTRING tag the user provided tag for the storage of the keypairSTRING publicKeyFile the filename of the public key filePUBLICKEY publicKey the public key to be storedSTRING privateKeyFile the filename of the private key filePRIVATEKEY privateKey the private key to be stored
OutputSTRING[] of replaced entries, if tag already existed in server.KeyStorage
3.10.10 PUBLIC putPublicKey
Descriptionstores the given public key in the file specified by the user. The user must provide a tag bywhich the key can be accessed later. The key will be stored in Settings.KeyStorageBaseDir,
44 3 modules
the mapping of tags to keys is stored in Settings.KeyStorageDB.
SettingsKeyStorageBaseDir
ParametersSTRING tag the user provided tag for the storage of the keypairSTRING publicKeyFile the filename of the public key filePUBLICKEY publicKey the public key to be stored
OutputSTRING[] of replaced entries, if tag already existed in server.KeyStorage
3.10.11 PUBLIC putPrivateKey
Descriptionstores the given private key in the file specified by the user. The user must provide a tagby which the key can be accessed later. The key will be stored in Settings.KeyStorageBaseDir,the mapping of tags to keys is stored in Settings.KeyStorageDB.
SettingsKeyStorageBaseDir
ParametersSTRING tag the user provided tag for the storage of the keypairSTRING privateKeyFile the filename of the public key filePRIVATEKEY privateKey the private key to be stored
OutputSTRING[] of replaced entries, if tag already existed in server.KeyStorage
3.11 server.QuoteValidation 45
3.11 server.QuoteValidation
3.11.1 Description
The server module server.QuoteValidation can be used to validate a given quote from aTPM. The quote includes the signed hash value of the desired PCRs and a signed nonce(→ replay protection). The client must provide a valid certificate for the key used to signthe quote. Normally an AIK is used to sign the quote, so a previously acquired AIK certifi-cate from PCAclient/PCAserver can be used to verify the quote.
The validation of the quote consists of two major parts:
1. Verification of the signature: the public key used for signing is used to verify thegiven signature on the nonce and the PCR data.
2. Verification of quote contents: it is verified that the original nonce, supplied bythe server, is included in the client’s quote. Furthermore, the quote contains thehash value of all quoted PCRs. A pre-calculated PCR value can be supplied toserver.QuoteValidation, so that validation will only succeed if the pre-calculatedvalue matches the quoted PCR value.
3.11.2 CONSTRUCTOR QuoteValidation
Descriptiontakes the given input values and stores them internally for later validation of the quotevia the run method
Settingsnone
ParametersINT[] pcrSelection array to define which PCRs have been included in the
given quoteTCTSSVALIDATION quote quote as received from the attesting clientX509CERTIFICATE aikCert certificate belonging to the key used for signing. It is
provided by the client to retrieve the public key andverify the quote’s signature.
BYTE[][] vPCRs pre-calculated vPCR values are provided as BYTE[].Multiple vPCRs can be provided.
BYTE[] nonce the anti-replay nonce the server previously providedfor the client to be included in the quote
46 3 modules
3.11.3 PRIVATE selectPCR
Descriptionthe method is used to return a TCBLOBDATA structure with a BYTE[] representation of aselected PCR. The bit at the given index i is set to 1, all other bits are 0.
Settingsnone
ParametersLONG index index of PCR to select
OutputTCBLOBDATA containing the BYTE[] representation of the selected PCR
3.11.4 PRIVATE createDigestInfoDER
Descriptioncode from jTPM-Tools. It is used to return the digestInfo properly out of the quote.
Settingsnone
ParametersTCBLOBDATA digest digest to be properly encoded
OutputTCBLOBDATA digestInfo used during verification of the quote signature
3.11.5 PUBLIC run
DescriptionImplements the necessary steps to validate the given quote. First the public key is ex-tracted from the supplied certificate. It is used to verify the quote’s signature. A com-posite object with the given pre-calculated PCR values is created and its hash value iscalculated. The hash is checked against the hash value provided by the quote. Finallythe quote’s nonce is checked. Only if all steps of the validation succeed, the quote willvalidate. Protection is provided against different attacks. If quote contents are changedafter signing, the validation of the signature will fail. If a malicious client provides a mod-ified measurement list, pretending to run only trusted software, the calculated vPCR willnot match the quoted and signed PCR value. Anti-replay attack protection is given bythe usage of the rolling nonce.
3.11 server.QuoteValidation 47
Settingsnone
Parametersnone
OutputBOOLEAN TRUE if quote is valid, else FALSE
4 net
DE.FRAUNHOFER.SIT.TC.ETHEMBA.NET
This package contains networking classes for sending and receiving data via TCP/IP.
49
50 4 net
4.1 NetEntity
4.1.1 Description
NetEntity provides an implementation of a networked client-server infrastructure. Ne-tEntity can be initialized as server or as client. Once initialized, it can be used to transfercontrols (NetCommand) or Objects.
4.1.2 CONSTRUCTOR NetEntity
DescriptionSets up a NetEntity as either server or client. If invoking with serverHostname andserverPort, a client version is instantiated. If only serverPort is given, a server is instan-tiated
Settingsnone
ParametersSTRING serverHostname hostname of server the client will connect to (client
only)INT serverPort port the client will connect to / the server will listen
on
4.1.3 PUBLIC init
DescriptionInitializes the connection. A socket is created and bound to the specified port. If in-stance is a server, the socket will start to listen and accept connections.
Settingsnone
Parametersnone
4.1.4 PUBLIC close
Descriptioncloses the socket. Returns TRUE , if socket closed successfully, else FALSE .
4.1 NetEntity 51
Settingsnone
Parametersnone
4.1.5 PUBLIC sendACK
Descriptionsends a NetCommand.ACK
Settingsnone
Parametersnone
OutputTRUE , if sent successfully, else FALSE
4.1.6 PUBLIC sendNACK
Descriptionsends a NetCommand.NACK
Settingsnone
Parametersnone
OutputTRUE , if sent successfully, else FALSE
4.1.7 PUBLIC sendCommand
Descriptionsends the given NetCommand
Settingsnone
52 4 net
ParametersNetCommand netCom-mand
the NETCOMMAND to be sent
OutputTRUE , if sent successfully, else FALSE
4.1.8 PUBLIC sendObject
Descriptionsends the given object over the connection.
Settingsnone
ParametersOBJECT o object to send
OutputTRUE if sent successfully, else FALSE
4.1.9 PUBLIC receiveACK
Descriptiontry to receive a NetCommand.ACK
Settingsnone
Parametersnone
OutputTRUE if ACK received, else FALSE
4.1.10 PUBLIC receiveCommand
Descriptionreceive a NetCommand
Settingsnone
4.1 NetEntity 53
Parametersnone
Outputreturns the received NetCommand, if received object is an integer. Else NetCommand.UNKNOWNis returned
4.1.11 PUBLIC receiveObject
Descriptionwaits to receive an Object of the given class.
Settingsnone
ParametersCLASS c class of the object to be received
OutputIf received object is of specified type, the object is returned, else NULL.
4.1.12 PUBLIC getRemoteIP
Descriptionreturns the IP address of the client, when issued on the server
Settingsnone
Parametersnone
OutputSTRING IP address of client
4.1.13 PUBLIC getRemoteHostname
Descriptionreturns the hostname of the client, when issued on the server
Settingsnone
54 4 net
Parametersnone
OutputSTRING hostname of client
4.2 NetCommand 55
4.2 NetCommand
4.2.1 Description
NetCommand provides a mapping between symbolic names and command codes (INT)for convenient use of NetEntity objects.
• UNKNOWN
• ACK
• NACK
• INIT
• CLOSE
• KNOWNHASHES
• STRING
• RA_REQUEST
• RA_RESPONSE
• PCA_REQUEST
• PCA_RESPONSE
5 types
DE.FRAUNHOFER.SIT.TC.ETHEMBA.TYPES
This package contains data types for convenient access to IMA measurements and hashlists.
57
58 5 types
5.1 MeasurementList
5.1.1 Description
MeasurementList is a data type for convenient conversion and access to IMA measure-ment data.
5.1.2 CONSTRUCTOR MeasurementList
Descriptioninitializes the MeasurementList with a STRING[][][]
Settingsnone
ParametersSTRING[][][] measure-mentList
[1] PCR number[2] hash[3] application
5.1.3 PUBLIC getMeasurementList
Descriptionreturns the MeasurementList as string array representation
Settingsnone
Parametersnone
OutputSTRING[][][] string array representation of the MeasurementList
5.1.4 PUBLIC getMeasurementListForPCR
Descriptionreturns the MeasurementList for a given PCR number as string array representation
Settingsnone
5.1 MeasurementList 59
ParametersINT pcr to be filtered PCR number
OutputSTRING[][] string array representation of the MeasurementList for the given PCR num-ber
5.1.5 PUBLIC loadFromFile
Descriptionloads MeasurementList from a file in IMA-Measurement-Format
Settingsnone
ParametersSTRING filename file to load MeasurementList from
OutputMEASUREMENTLIST loaded MeasurementList
60 5 types
5.2 KnownHashesList
5.2.1 Description
KnownHashesList is a data type providing basic database abilities for storing knownhash ⇔ application mappings.
5.2.2 CONSTRUCTOR KnownHashesList
Descriptioninitializes the KnownHashesList
Settingsnone
Parametersnone
5.2.3 PUBLIC put
Descriptionmaps the given hash to the given tag
Settingsnone
ParametersSTRING sha1hash hash of a applicationSTRING tag path and name of the application that was hashed
OutputSTRING tag/application that was associated to the given tag before, else NULL
5.2.4 PUBLIC get
Descriptionreturns the tag to which the specified hash is mapped to
Settingsnone
ParametersSTRING sha1hash hash to be searched for
5.2 KnownHashesList 61
OutputSTRING tag/application that hash is associated to, else NULL
5.2.5 PUBLIC containsTag
Descriptiontests if the given tag/application is mapped to one ore more hashes
Settingsnone
ParametersSTRING tag tag/application to be searched for
OutputTRUE if given tag/application is associated with one or hashes, else FALSE
5.2.6 PUBLIC containsSha1Hash
Descriptiontests if the given hash is mapped to a tag/application
Settingsnone
ParametersSTRING sha1hash hash to be searched for
OutputTRUE if given hash is associated with a tag/application, else FALSE
5.2.7 PUBLIC contains
Descriptiontests if a given hash is mapped to a given tag/application
Settingsnone
ParametersSTRING sha1hash hash to be searched forSTRING tag tag/application to be associated with
62 5 types
OutputTRUE if given hash is associated with the given tag/application, else FALSE
5.2.8 PUBLIC saveToFile
Descriptionsaves KnownHashesList to a given file
Settingsnone
ParametersSTRING filename file to save KnownHashesList in
5.2.9 PUBLIC loadFromFile
Descriptionloads a KnownHashesList from the disk
Settingsnone
ParametersSTRING filename file to load KnownHashesList from
OutputKNOWNHASHESLIST loaded KnownHashesList or NULL if KnownHashesList could notbe loaded
6 utils
DE.FRAUNHOFER.SIT.TC.ETHEMBA.UTILS
This package contains classes and methods for data conversion and standardized al-gorithms, that may be accessed in a convenient way.
63
64 6 utils
6.1 AES
6.1.1 Description
AES provides access to various AES calculations (encryption/decryption). Each methodmay also be accessed in a static way. Be aware to pass enough data to the static methods(i.e. AES-Key and IV).
Additionally random and pseudo-random AES-Keys and IVs may be generated using thisclass.
6.1.2 CONSTRUCTOR AES
Descriptionconstructs an AES object with the given key and initialization vector (IV)
Settingsnone
ParametersSECRETKEY k AES keyBYTE[] IV initialization vector (IV)
6.1.3 PUBLIC encryptObject
Descriptionencrypts a given OBJECT
Settingsnone
ParametersOBJECT m object to be encrypted
OutputBYTE[] encrypted data
6.1.4 PUBLIC encrypt
Descriptionencrypts a given BYTE[]
6.1 AES 65
Settingsnone
ParametersBYTE[] m data to be encrypted
OutputBYTE[] encrypted data
6.1.5 PUBLIC decryptObject
Descriptiondecrypts a given BYTE[] back into an OBJECT
Settingsnone
ParametersBYTE[] c data to be decrypted
OutputOBJECT decrypted object
6.1.6 PUBLIC decrypt
Descriptiondecrypts a given BYTE[]
Settingsnone
ParametersBYTE[] c data to be decrypted
OutputBYTE[] decrypted data
6.1.7 PRIVATE crypt
Descriptionen- or decrypts given BYTE[] with given AES-Key and IV
66 6 utils
SettingsaesCipherMode, aesKeySize
ParametersINT optMode operation mode: Cipher.DECRYPT_MODE or Ci-
pher.ENCRYPT_MODESECRETKEY k AES-Key to be usedBYTE[] IV IV to be usedBYTE[] input data to be en- or decrypted
OutputBYTE[] en- or decrypted data
6.1.8 PUBLIC generateKey
Descriptiongenerates a random AES-Key
Settingsnone
Parametersnone
OutputSECRETKEY generated key
6.1.9 PUBLIC generateKey
Descriptiongenerates a pseudo-random AES-Key by using an initial seed
Settingsnone
ParametersBYTE[] seed initial seed for PRNG
OutputSECRETKEY generated key
6.1 AES 67
6.1.10 PUBLIC generateIV
Descriptiongenerates a pseudo-random IV by using an initial seed
Settingsnone
ParametersBYTE[] seed initial seed for PRNG
OutputBYTE[] generated IV
68 6 utils
6.2 Helpers
6.2.1 Description
Helpers provides some useful methods for data conversion and serialization.
6.2.2 PUBLIC byteToHexString
Descriptionconverts a given BYTE[] into a Hex-String
Settingsnone
ParametersBYTE[] data data to be converted
OutputSTRING Hex-String representation of given data
6.2.3 PUBLIC hexStringToByteArray
Descriptionconverts a given Hex-String into a BYTE[]
Settingsnone
ParametersSTRING hexstring string to be converted
OutputBYTE[] converted data
6.2.4 PUBLIC leadingZeroes
Descriptionadds leading zeroes to a given number
Settingsnone
6.2 Helpers 69
ParametersINT num number to be padded with zeroesINT length length of result
OutputSTRING string representation of given number with padded zeroes to match the givenlength
6.2.5 PUBLIC saveObjectToFile
Descriptionsaves a given object (needs to be serializable) to the disk
Settingsnone
ParametersOBJECT o object to be savedSTRING filename location of saved object
6.2.6 PUBLIC saveBytesToFile
Descriptionsaves bytes to a file
Settingsnone
ParametersBYTE[] b bytes to be savedSTRING filename file to be saved to
6.2.7 PUBLIC loadObjectFromFile
Descriptionloads an object from a given file
Settingsnone
ParametersSTRING filename file to load object from
70 6 utils
OutputOBJECT loaded from given file
6.2.8 PUBLIC loadBytesFromFile
Descriptionloads a file byte-wise
Settingsnone
ParametersSTRING filename file to be loaded from
OutputBYTE[] loaded bytes
6.2.9 PUBLIC Object2Bytes
Descriptionconverts an object to bytes
Settingsnone
ParametersOBJECT o object to be converted
OutputBYTE[] converted bytes
6.2.10 PUBLIC Bytes2Object
Descriptionconverts a bytes back to an object
Settingsnone
ParametersBYTE[] b bytes to be converted
6.2 Helpers 71
OutputOBJECT converted object
72 6 utils
6.3 SHA1
6.3.1 Description
SHA1 provides access to various SHA1 calculations.
6.3.2 PUBLIC main
Descriptiongenerates SHA1-Hash of given string/hex-string
Settingsnone
ParametersSTRING[] args [0] String to be hashed
[1] if ’-h’ the given String is assumed to be a hex rep-resentation
OutputSHA1-Hash of given data
6.3.3 PUBLIC hashByteToByte
Descriptioncalculates SHA1-Hash of given BYTE[]
Settingsnone
ParametersBYTE[] input data to be hashed
OutputBYTE[] SHA1-Hash of given data
6.3.4 PUBLIC hashHex
Descriptioncalculate SHA1-Hash for given Hex-String
Settingsnone
6.3 SHA1 73
ParametersSTRING input data to be hashed (Hex-String)
OutputSTRING SHA1-Hash of given data
6.3.5 PUBLIC hash
Descriptioncalculate SHA1-Hash for given String
Settingsnone
ParametersSTRING input data to be hashed
OutputSTRING SHA1-Hash of given data
6.3.6 PUBLIC randomHash
Descriptionreturns SHA1-Hash of a random generated number
Settingsnone
Parametersnone
OutputBYTE[] of SHA1-Hash
7 Demonstrators
For demonstration purposes we provide two simple yet useful demonstrators. Thesedemonstrators will prove that the Remote Attestation Protocol developed and imple-mented in ethemba serves as reliable attestation method.
To prove reliability the following demonstrators inject bad code into an application thatwas added to the RAserver’s KnownHashesList. This KnownHashesList acts as a white-listrepresenting SHA1 hashes for well-known and valid applications. If an application wasrun on the attesting system that either is not included in the KnownHashesList or whoseSHA1 hash does not match the one inside the KnownHashesList, Remote Attestationfails.
To prove this we provide a demonstrator that will compile a C-program out of two sources.The demonstrators can be found in the subfolder demo and contain the following files:
• demoevil.sh
• demogood.sh
• helloworldevil.c
• helloworldgood.c
7.1 demogood.sh
This demonstrator will compile the code contained in helloworldgood.c to the binaryhelloworld.
1 #include <stdio . h>2
3 int main ( )4 {5 p r i n t f ( "sawubona ! \ n" ) ;6 p r i n t f ( "means ’ hel lo ’ in zulu \n" ) ;7 return 0 ;8 }
Listing 7.1: helloworldgood.c
75
76 7 Demonstrators
We assume this code to be “good” and therefore included its SHA hash into the RAserver’sKnownHashesList. Executing this program will not break a successful Remote Attes-tion.
7.2 demoevil.sh
This demonstrator will compile the code contained in helloworldevil.c to the binaryhelloworld.
1 #include <stdio . h>2
3 int main ( )4 {5 p r i n t f ( "hamba kahle ! \ n" ) ;6 p r i n t f ( "means ’ goodbye ’ in zulu \n" ) ;7 return 0 ;8 }
Listing 7.2: helloworldevil.c
This can be seen as an attack pretending execution of a well-known program. As its SHA1hash now differs from the one included in the RAserver’s KnownHashesList, Remote At-testion now has to fail.
8 Settings
Global settings, parameters and constants of ethemba framework. These variables maybe used to customize ethemba’s behaviour to individual needs.
Note: some variables have inner dependencies.Note: filesystem related variables must fit OS’s naming conventions.
aesCipherMode . . . . . . . . . . . . . . . . . . . AES-Cipher-Mode (used in AES)
aesKeySize . . . . . . . . . . . . . . . . . . . . . . . . key-size for AES-Keys (used in AES)
AIKPwd . . . . . . . . . . . . . . . . . . . . . . . . . . . default AIK password (used in fixed-mode of PCA-client and RAclient)
CertDBfile . . . . . . . . . . . . . . . . . . . . . . . . . location of Certificate-DB
CertExportBaseDir . . . . . . . . . . . . . . . location of exported certificates
ethembaDir . . . . . . . . . . . . . . . . . . . . . . . root directory for ethemba
IMAruntimeFile . . . . . . . . . . . . . . . . . . location of IMA-Measurement-Log in filesystem
KeyStorageBaseDir . . . . . . . . . . . . . . . location of Server-Key-Storage
KeyStorageDB . . . . . . . . . . . . . . . . . . . . location of Server-Key-Storage-DB
OwnerPwd . . . . . . . . . . . . . . . . . . . . . . . . default TPM-Owner password (used in fixed-modeof PCAclient and RAclient)
PCAcertCommonName . . . . . . . . . . PCA-Certificate Attribute: CommonName
PCAcertCountry . . . . . . . . . . . . . . . . . . PCA-Certificate Attribute: Country
PCAcertOrganization . . . . . . . . . . . . . PCA-Certificate Attribute: Organization
PCAcertOU . . . . . . . . . . . . . . . . . . . . . . . . PCA-Certificate Attribute: OU
PCAcertPolicyOID . . . . . . . . . . . . . . . . PCA-Certificate Attribute: PolidyOID
PCAcertPolicyURL . . . . . . . . . . . . . . . . PCA-Certificate Attribute: PolicyURL
PCAcertPrivateKeySize . . . . . . . . . . . PCA-Certificate Attribute: PrivateKeySize
PCAcertSerialNumber . . . . . . . . . . . . PCA-Certificate Attribute: SerialNumber
PCAdefault_AIKtag . . . . . . . . . . . . . . . default label for AIK-Creation/-Storage (used in fixed-mode of PCAclient)
PCAServer_KeyTag . . . . . . . . . . . . . . . default label for Server-Key-Storage
PCAServerIP . . . . . . . . . . . . . . . . . . . . . . PCA-Server’s IP-Address (used in fixed-mode of PCA-client)
PCAServerPort . . . . . . . . . . . . . . . . . . . . PCA-Server’s Port
pwdEncoding . . . . . . . . . . . . . . . . . . . . . password encoding used for TPM-Key passwords
77
78 Settings
RAcert_Expiry . . . . . . . . . . . . . . . . . . . . expiry of Remote Attestation Certificates (relative toserver-time)
RAcertCommonName . . . . . . . . . . . . RA-Certificate Attribute: CommonName
RAcertCountry . . . . . . . . . . . . . . . . . . . . RA-Certificate Attribute: Country
RAcertOrganization . . . . . . . . . . . . . . RA-Certificate Attribute: Organization
RAcertOU . . . . . . . . . . . . . . . . . . . . . . . . . RA-Certificate Attribute: OU
RAdefault_AIKtag . . . . . . . . . . . . . . . . . default label for AIK-Creation/-Storage (used in fixed-mode of RAclient)
RAServer_KeyTag . . . . . . . . . . . . . . . . . default label for Server-Key-Storage
RAServer_KnownHashesList . . . . . filename of stored KnownHashesList (used by RAserver).
RAServerIP . . . . . . . . . . . . . . . . . . . . . . . . RA-Server’s IP-Address (used in fixed-mode of RAclient)
RAServerPort . . . . . . . . . . . . . . . . . . . . . RA-Server’s Port
ServerKeyAlgorithm . . . . . . . . . . . . . . Server-KeyPair’s Algorithm (used in CreateServerKey-Pair)
ServerKeySize . . . . . . . . . . . . . . . . . . . . . Server-KeyPair’s Key-Size
ServerSignAlgorithmID . . . . . . . . . . Algorithm used for signing
SRKPwd . . . . . . . . . . . . . . . . . . . . . . . . . . . default SRK password (used in fixed-mode of PCA-client and RAclient)
TPM_CLI_AIK_policyOID . . . . . . . . AIK-Certificate Attribute: Policy OID
TPM_CLI_AIK_policyURL . . . . . . . . AIK-Certificate Attribute: Policy URL
TPM_CLI_EK_policyOID . . . . . . . . . EK-Certificate Attribute: Policy OID
TPM_CLI_EK_policyURL . . . . . . . . . EK-Certificate Attribute: Policy URL
TPM_CLI_EK_SpecFamily . . . . . . . . EK-Certificate Attribute: TPM-Spec-Family
TPM_CLI_EK_SpecLevel . . . . . . . . . . EK-Certificate Attribute: TPM-Spec-Level
TPM_CLI_EK_SpecRevision . . . . . . EK-Certificate Attribute: TPM-Spec-Revision
TPM_CLI_EK_TPMmanufacturer EK-Certificate Attribute: TPM Manufacturer
TPM_CLI_EK_TPMmodel . . . . . . . . EK-Certificate Attribute: TPM Model
TPM_CLI_EK_TPMversion . . . . . . . EK-Certificate Attribute: TPM Version
TPM_CLI_PE_majorVersion . . . . . . PE-Certificate Attribute: Platform Major Version
TPM_CLI_PE_minorVersion . . . . . PE-Certificate Attribute: Platform Minor Version
TPM_CLI_PE_Pclass . . . . . . . . . . . . . . PE-Certificate Attribute: Platform Class
TPM_CLI_PE_Pmanufacturer . . . . PE-Certificate Attribute: Platform Manufacturer
TPM_CLI_PE_Pmodel . . . . . . . . . . . . PE-Certificate Attribute: Platform Model
TPM_CLI_PE_policyOID . . . . . . . . . PE-Certificate Attribute: Policy OID
TPM_CLI_PE_policyURL . . . . . . . . . PE-Certificate Attribute: Policy URL
TPM_CLI_PE_Pversion . . . . . . . . . . . PE-Certificate Attribute: Platform Version
TPM_CLI_PE_revision . . . . . . . . . . . . PE-Certificate Attribute: Platform Revision
TPM_CLIcertCountry . . . . . . . . . . . . . TPM-Client-Certificate Attribute: Country
Settings 79
TPM_CLIcertOrganization . . . . . . . TPM-Client-Certificate Attribute: Organization
TPM_CLIcertOU . . . . . . . . . . . . . . . . . . TPM-Client-Certificate Attribute: OU
TpmKeyDBfile . . . . . . . . . . . . . . . . . . . . location of TPM-Key-DB
References
ethemba uses jTSS as underlying implementation of the TCG Software Stack for Java.
jTSS implements all the TSS layers directly in Java by staying very close to the TPMspecifications stated by the TCG. It is developed and maintained at the Institute forApplied Information Processing and Communication (Institut für angewandte Infor-mationsverarbeitung und Kommunikation, IAIK) at Graz University of Technology (TUGraz).
IAIK additionally provides a set of command line tools for basic operations on TPMs.These tools include several modules for attesting a platform (e.g. generate AIKs, certifi-cates and handle TPM quotes).
Some code of jTPMtools was re-used in ethemba to allow for convenient and reliable ac-cess. These modified modules can be found in a separate package underneath ethemba(jTPMtools).
For further information on jTSS and the OpenTC Project visit the following websites:
Trusted Computing for the Java Platformhttp://trustedjava.sourceforge.net
OpenTC Projecthttp://www.opentc.net
Institute for Applied Information Processing and Communicationshttp://www.iaik.tugraz.at
81