net.named_data.jndn.security.tpm

Class TpmBackEnd

java.lang.Object

net.named_data.jndn.security.tpm.TpmBackEnd

Direct Known Subclasses:

TpmBackEndFile, TpmBackEndMemory

public abstract class TpmBackEnd
extends Object

TpmBackEnd is an abstract base class for a TPM backend implementation which provides a TpmKeyHandle to the TPM front end. This class defines the interface that an actual TPM backend implementation should provide, for example TpmBackEndMemory.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TpmBackEnd.Error A TpmBackEnd.Error extends Exception and represents a non-semantic error in backend TPM processing.

Constructor Summary

Constructors

Constructor and Description
TpmBackEnd()

Method Summary

Modifier and Type	Method and Description
TpmKeyHandle	createKey(Name identityName, KeyParams params) Create a key for the identityName according to params.
void	deleteKey(Name keyName) Delete the key with name keyName.
protected abstract TpmKeyHandle	doCreateKey(Name identityName, KeyParams params) Create a key for identityName according to params.
protected abstract void	doDeleteKey(Name keyName) Delete the key with name keyName.
protected Blob	doExportKey(Name keyName, ByteBuffer password) Get the encoded private key with name keyName in PKCS #8 format, possibly password-encrypted.
protected abstract TpmKeyHandle	doGetKeyHandle(Name keyName) Get the handle of the key with name keyName.
protected abstract boolean	doHasKey(Name keyName) Check if the key with name keyName exists in the TPM.
protected void	doImportKey(Name keyName, ByteBuffer pkcs8, ByteBuffer password) Import an encoded private key with name keyName in PKCS #8 format, possibly password-encrypted.
Blob	exportKey(Name keyName, ByteBuffer password) Get the encoded private key with name keyName in PKCS #8 format, possibly password-encrypted.
TpmKeyHandle	getKeyHandle(Name keyName) Get the handle of the key with name keyName.
boolean	hasKey(Name keyName) Check if the key with name keyName exists in the TPM.
void	importKey(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.
protected static void	setKeyName(TpmKeyHandle keyHandle, Name identityName, KeyParams params) Set the key name in keyHandle according to identityName and params.
void	setTerminalMode(boolean isTerminal) Set the terminal mode of the TPM.
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

TpmBackEnd

public TpmBackEnd()

Method Detail

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

getKeyHandle

public final TpmKeyHandle getKeyHandle(Name keyName)
                                throws TpmBackEnd.Error

Get the handle of the key with name keyName. Calling getKeyHandle multiple times with the same keyName will return different TpmKeyHandle objects that all refer to the same key.

Parameters:

keyName - The name of the key.

Returns:

The handle of the key, or null if the key does not exist.

Throws:

TpmBackEnd.Error

createKey

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

Create a key for the identityName according to params.

Parameters:

identityName - The name if the identity.

params - The KeyParams for creating the key.

Returns:

The handle of the created key.

Throws:

Tpm.Error - if params is invalid.

TpmBackEnd.Error - if the key 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.

Parameters:

keyName - The name of the key to delete.

Throws:

TpmBackEnd.Error - if the deletion fails.

exportKey

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

Get the encoded private key with name keyName in PKCS #8 format, possibly password-encrypted.

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 encoded private key.

Throws:

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

importKey

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

Import an encoded private key with name keyName in PKCS #8 format, possibly password-encrypted.

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 a key with name keyName already exists, or for an error importing the key.

isTerminalMode

public boolean isTerminalMode()
                       throws TpmBackEnd.Error

Check if the TPM is in terminal mode. The default implementation always returns true.

Returns:

True if in terminal mode.

Throws:

TpmBackEnd.Error

setTerminalMode

public 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. The default implementation does nothing.

Parameters:

isTerminal - True to enable terminal mode.

Throws:

TpmBackEnd.Error

isTpmLocked

public boolean isTpmLocked()
                    throws TpmBackEnd.Error

Check if the TPM is locked. The default implementation returns false.

Returns:

True if the TPM is locked, otherwise false.

Throws:

TpmBackEnd.Error

unlockTpm

public boolean unlockTpm(ByteBuffer password)
                  throws TpmBackEnd.Error

Unlock the TPM. If !isTerminalMode(), prompt for a password from the GUI. The default implementation does nothing and returns !isTpmLocked().

Parameters:

password - The password to unlock TPM.

Returns:

True if the TPM was unlocked.

Throws:

TpmBackEnd.Error

setKeyName

protected static void setKeyName(TpmKeyHandle keyHandle,
                                 Name identityName,
                                 KeyParams params)
                          throws TpmBackEnd.Error

Set the key name in keyHandle according to identityName and params.

Throws:

TpmBackEnd.Error

doHasKey

protected abstract boolean doHasKey(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

doGetKeyHandle

protected abstract TpmKeyHandle doGetKeyHandle(Name keyName)
                                        throws TpmBackEnd.Error

Get the handle of the key with name keyName.

Parameters:

keyName - The name of the key.

Returns:

The handle of the key, or null if the key does not exist.

Throws:

TpmBackEnd.Error

doCreateKey

protected abstract TpmKeyHandle doCreateKey(Name identityName,
                                            KeyParams params)
                                     throws TpmBackEnd.Error

Create a key for identityName according to params. The created key is named as: /{identityName}/[keyId]/KEY . The key name is set in the returned TpmKeyHandle.

Parameters:

identityName - The name if the identity.

params - The KeyParams for creating the key.

Returns:

The handle of the created key.

Throws:

TpmBackEnd.Error - if the key cannot be created.

doDeleteKey

protected abstract void doDeleteKey(Name keyName)
                             throws TpmBackEnd.Error

Delete the key with name keyName. If the key doesn't exist, do nothing.

Parameters:

keyName - The name of the key to delete.

Throws:

TpmBackEnd.Error - if the deletion fails.

doExportKey

protected Blob doExportKey(Name keyName,
                           ByteBuffer password)
                    throws TpmBackEnd.Error

Get the encoded private key with name keyName in PKCS #8 format, possibly password-encrypted.

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 encoded private key.

Throws:

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

doImportKey

protected void doImportKey(Name keyName,
                           ByteBuffer pkcs8,
                           ByteBuffer password)
                    throws TpmBackEnd.Error

Import an encoded private key with name keyName in PKCS #8 format, possibly password-encrypted.

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 - for an error importing the key.