net.named_data.jndn.security.tpm

Class Tpm

java.lang.Object

net.named_data.jndn.security.tpm.Tpm

public class Tpm
extends Object

The TPM (Trusted Platform Module) stores the private portion of a user's cryptography keys. The format and location of stored information is indicated by the TPM locator. The TPM is designed to work with a PIB (Public Information Base) which stores public keys and related information such as certificates. The TPM also provides functionalities of cryptographic transformation, such as signing and decryption. A TPM consists of a unified front-end interface and a backend implementation. The front-end caches the handles of private keys which are provided by the backend implementation. Note: A Tpm instance is created and managed only by the KeyChain. It is returned by the KeyChain getTpm() method, through which it is possible to check for the existence of private keys, get public keys for the private keys, sign, and decrypt the supplied buffers using managed private keys.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Tpm.Error A Tpm.Error extends Exception and represents a semantic error in TPM processing.

Constructor Summary

Constructors

Constructor and Description
Tpm(String scheme, String location, TpmBackEnd backEnd)

Method Summary

Modifier and Type	Method and Description
Name	createKey_(Name identityName, KeyParams params) Create a key for the identityName according to params.
Blob	decrypt(ByteBuffer cipherText, Name keyName) Return the plain text which is decrypted from cipherText using the key with name keyName.
void	deleteKey_(Name keyName) Delete the key with name keyName.
Blob	exportPrivateKey_(Name keyName, ByteBuffer password) Get the encoded private key with name keyName in PKCS #8 format, possibly encrypted.
TpmBackEnd	getBackEnd_() Get the TpmBackEnd.
Blob	getPublicKey(Name keyName) Get the public portion of an asymmetric key pair with name keyName.
String	getTpmLocator()
boolean	hasKey(Name keyName) Check if the key with name keyName exists in the TPM.
void	importPrivateKey_(Name keyName, ByteBuffer pkcs8, ByteBuffer password) Import an encoded private key with name keyName in PKCS #8 format, possibly password-encrypted.
boolean	isTerminalMode() Check if the TPM is in terminal mode.
boolean	isTpmLocked() Check if the TPM is locked.
void	setTerminalMode(boolean isTerminal) Set the terminal mode of the TPM.
Blob	sign(ByteBuffer data, Name keyName, DigestAlgorithm digestAlgorithm) Compute a digital signature from the byte buffer using the key with name keyName.
boolean	unlockTpm(ByteBuffer password) Unlock the TPM.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Tpm

public Tpm(String scheme,
           String location,
           TpmBackEnd backEnd)

Method Detail

getTpmLocator

public String getTpmLocator()

hasKey

public final boolean hasKey(Name keyName)
                     throws TpmBackEnd.Error

Check if the key with name keyName exists in the TPM.

Parameters:

keyName - The name of the key.

Returns:

True if the key exists.

Throws:

TpmBackEnd.Error

getPublicKey

public final Blob getPublicKey(Name keyName)
                        throws TpmBackEnd.Error

Get the public portion of an asymmetric key pair with name keyName.

Parameters:

keyName - The name of the key.

Returns:

The encoded public key, or an isNull Blob if the key does not exist.

Throws:

TpmBackEnd.Error

sign

public final Blob sign(ByteBuffer data,
                       Name keyName,
                       DigestAlgorithm digestAlgorithm)
                throws TpmBackEnd.Error

Compute a digital signature from the byte buffer using the key with name keyName.

Parameters:

data - The input byte buffer.

keyName - The name of the key.

digestAlgorithm - The digest algorithm for the signature.

Returns:

The signature Blob, or an isNull Blob if the key does not exist, or for an unrecognized digestAlgorithm.

Throws:

TpmBackEnd.Error

decrypt

public final Blob decrypt(ByteBuffer cipherText,
                          Name keyName)
                   throws TpmBackEnd.Error

Return the plain text which is decrypted from cipherText using the key with name keyName.

Parameters:

cipherText - The cipher text byte buffer.

keyName - The name of the key.

Returns:

The decrypted data, or an isNull Blob if the key does not exist.

Throws:

TpmBackEnd.Error

isTerminalMode

public final boolean isTerminalMode()
                             throws TpmBackEnd.Error

Check if the TPM is in terminal mode.

Returns:

True if in terminal mode.

Throws:

TpmBackEnd.Error

setTerminalMode

public final void setTerminalMode(boolean isTerminal)
                           throws TpmBackEnd.Error

Set the terminal mode of the TPM. In terminal mode, the TPM will not ask for a password from the GUI.

Parameters:

isTerminal - True to enable terminal mode.

Throws:

TpmBackEnd.Error

isTpmLocked

public final boolean isTpmLocked()
                          throws TpmBackEnd.Error

Check if the TPM is locked.

Returns:

True if the TPM is locked, otherwise false.

Throws:

TpmBackEnd.Error

unlockTpm

public final boolean unlockTpm(ByteBuffer password)
                        throws TpmBackEnd.Error

Unlock the TPM. If !isTerminalMode(), prompt for a password from the GUI.

Parameters:

password - The password to unlock TPM.

Returns:

True if the TPM was unlocked.

Throws:

TpmBackEnd.Error

getBackEnd_

public final TpmBackEnd getBackEnd_()

Get the TpmBackEnd. This should only be called by KeyChain.

createKey_

public final Name createKey_(Name identityName,
                             KeyParams params)
                      throws Tpm.Error,
                             TpmBackEnd.Error

Create a key for the identityName according to params. The created key is named /{identityName}/[keyId]/KEY . This should only be called by KeyChain.

Parameters:

identityName - The name if the identity.

params - The KeyParams for creating the key.

Returns:

The name of the created key.

Throws:

Tpm.Error - if params is invalid or the key type is unsupported.

TpmBackEnd.Error - if the key already exists or cannot be created.

deleteKey_

public final void deleteKey_(Name keyName)
                      throws TpmBackEnd.Error

Delete the key with name keyName. If the key doesn't exist, do nothing. Note: Continuing to use existing Key handles on a deleted key results in undefined behavior. This should only be called by KeyChain.

Throws:

TpmBackEnd.Error - if the deletion fails.

exportPrivateKey_

public final Blob exportPrivateKey_(Name keyName,
                                    ByteBuffer password)
                             throws TpmBackEnd.Error

Get the encoded private key with name keyName in PKCS #8 format, possibly encrypted. This should only be called by KeyChain.

Parameters:

keyName - The name of the key in the TPM.

password - The password for encrypting the private key, which should have characters in the range of 1 to 127. If the password is supplied, use it to return a PKCS #8 EncryptedPrivateKeyInfo. If the password is null, return an unencrypted PKCS #8 PrivateKeyInfo.

Returns:

The private key encoded in PKCS #8 format.

Throws:

TpmBackEnd.Error - if the key does not exist or if the key cannot be exported, e.g., insufficient privileges.

importPrivateKey_

public final void importPrivateKey_(Name keyName,
                                    ByteBuffer pkcs8,
                                    ByteBuffer password)
                             throws TpmBackEnd.Error

Import an encoded private key with name keyName in PKCS #8 format, possibly password-encrypted. This should only be called by KeyChain.

Parameters:

keyName - The name of the key to use in the TPM.

pkcs8 - The input byte buffer. If the password is supplied, this is a PKCS #8 EncryptedPrivateKeyInfo. If the password is null, this is an unencrypted PKCS #8 PrivateKeyInfo.

password - The password for decrypting the private key, which should have characters in the range of 1 to 127. If the password is supplied, use it to decrypt the PKCS #8 EncryptedPrivateKeyInfo. If the password is null, import an unencrypted PKCS #8 PrivateKeyInfo.

Throws:

TpmBackEnd.Error - if the key cannot be imported.