pyndn.security.tpm package

Submodules

pyndn.security.tpm.tpm module

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.

class pyndn.security.tpm.tpm.Tpm(scheme, location, backEnd)

Bases: object

exception Error(message)

Bases: exceptions.Exception

Create a Tpm.Error which represents a semantic error in TPM processing.

Parameters:message (str) – The error message.

decrypt(cipherText, keyName)

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

Parameters:

• cipherText (an array which implements the buffer protocol) – The cipher text byte buffer.
• keyName (Name) – The name of the key.

Returns:

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

Return type:

Blob

getPublicKey(keyName)

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

Parameters:keyName (Name) – The name of the key. Returns:The encoded public key, or an isNull Blob if the key does not exist. Return type:Blob

getTpmLocator()

hasKey(keyName)

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

Parameters:keyName (Name) – The name of the key. Returns:True if the key exists. Return type:bool

isTerminalMode()

Check if the TPM is in terminal mode.

Returns:True if in terminal mode. Return type:bool

isTpmLocked()

Check if the TPM is locked.

Returns:True if the TPM is locked, otherwise False. Return type:bool

setTerminalMode(isTerminal)

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

Parameters:isTerminal (bool) – True to enable terminal mode.

sign(data, keyName, digestAlgorithm)

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

Parameters:

• data (an array which implements the buffer protocol) – The input byte buffer.
• keyName (Name) – The name of the key.
• digestAlgorithm (int from 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.

Return type:

Blob

unlockTpm(password)

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

Parameters:password (an array which implements the buffer protocol) – The password to unlock TPM. Returns:True if the TPM was unlocked. Return type:bool

pyndn.security.tpm.tpm_back_end module

This module defines the TpmBackEnd class which 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.

class pyndn.security.tpm.tpm_back_end.TpmBackEnd

Bases: object

exception Error(message)

Bases: exceptions.Exception

Create a TpmBackEnd.Error which represents a non-semantic error in backend TPM processing.

Parameters:message (str) – The error message.

createKey(identityName, params)

Create a key for the identityName according to params.

Parameters:

• identityName (Name) – The name if the identity.
• params (KeyParams) – The KeyParams for creating the key.

Returns:

The handle of the created key.

Return type:

TpmKeyHandle

Raises:

TpmBackEnd.Error – If the key cannot be created.

deleteKey(keyName)

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 (Name) – The name of the key to delete. Raises:TpmBackEnd.Error – If the deletion fails.

exportKey(keyName, password)

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

Parameters:

• keyName (Name) – The name of the key in the TPM.
• password (an array which implements the buffer protocol) – 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 None, return an unencrypted PKCS #8 PrivateKeyInfo.

Returns:

The encoded private key.

Return type:

Blob

Raises:

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

getKeyHandle(keyName)

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 (Name) – The name of the key. Returns:The handle of the key, or None if the key does not exist. Return type:TpmKeyHandle

hasKey(keyName)

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

Parameters:keyName (Name) – The name of the key. Returns:True if the key exists. Return type:bool

importKey(keyName, pkcs8, password)

Import an encoded private key with name keyName in PKCS #8 format,

possibly password-encrypted.

Parameters:

• keyName (Name) – The name of the key to use in the TPM.
• pkcs8 (an array which implements the buffer protocol) – The input byte buffer. If the password is supplied, this is a PKCS #8 EncryptedPrivateKeyInfo. If the password is None, this is an unencrypted PKCS #8 PrivateKeyInfo.
• password (an array which implements the buffer protocol) – 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 None, import an unencrypted PKCS #8 PrivateKeyInfo.

Raises:

TpmBackEnd.Error – For an error importing the key.

isTerminalMode()

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

returns True.

Returns:True if in terminal mode. Return type:bool

isTpmLocked()

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

Returns:True if the TPM is locked, otherwise False. Return type:bool

static setKeyName(keyHandle, identityName, params)

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

Parameters:

• keyHandle (TpmKeyHandle) –
• identityName (Name) –
• params (KeyParams) –

setTerminalMode(isTerminal)

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 (bool) – True to enable terminal mode.

unlockTpm(password)

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

Parameters:password (an array which implements the buffer protocol) – The password to unlock TPM. Returns:True if the TPM was unlocked. Return type:bool

pyndn.security.tpm.tpm_back_end_file module

This module defines the TpmBackEndFile class which extends TpmBackEnd to implement a TPM back-end using on-disk file storage. In this TPM, each private key is stored in a separate file with permission 0400, i.e., owner read-only. The key is stored in PKCS #1 format in base64 encoding.

class pyndn.security.tpm.tpm_back_end_file.TpmBackEndFile(locationPath=None)

Bases: pyndn.security.tpm.tpm_back_end.TpmBackEnd

Create a TpmBackEndFile to use the given path to store files (of provided) or to the default location.

Parameters:locationPath (str) – (optional) The full path of the directory to store private keys. If omitted or None or “”, use the default location ~/.ndn/ndnsec-key-file. This creates the directory if it doesn’t exist.

exception Error(message)

Bases: pyndn.security.tpm.tpm_back_end.Error

Create a TpmBackEndFile.Error which extends TpmBackEnd.Error and represents a non-semantic error in backend TPM file processing.

Parameters:message (str) – The error message.

static getScheme()

pyndn.security.tpm.tpm_back_end_memory module

This module defines the TpmBackEndMemory class which extends TpmBackEnd to implement a TPM back-end using in-memory storage.

class pyndn.security.tpm.tpm_back_end_memory.TpmBackEndMemory

Bases: pyndn.security.tpm.tpm_back_end.TpmBackEnd

static getScheme()

pyndn.security.tpm.tpm_back_end_osx module

This module defines the TpmBackEndOsx class which extends TpmBackEnd to implement a TPM back-end using the macOS Keychain services.

class pyndn.security.tpm.tpm_back_end_osx.Osx

Bases: object

static get()

Get the static instance of Osx, creating it only when needed.

class pyndn.security.tpm.tpm_back_end_osx.SecKeychainAttribute

Bases: _ctypes.Structure

data

Structure/Union member

length

Structure/Union member

tag

Structure/Union member

class pyndn.security.tpm.tpm_back_end_osx.SecKeychainAttributeList

Bases: _ctypes.Structure

attr

Structure/Union member

count

Structure/Union member

class pyndn.security.tpm.tpm_back_end_osx.TpmBackEndOsx

Bases: pyndn.security.tpm.tpm_back_end.TpmBackEnd

exception Error(message)

Bases: pyndn.security.tpm.tpm_back_end.Error

Create a TpmBackEndOsx.Error which extends TpmBackEnd.Error and represents a non-semantic error in the backend TPM for the macOS Keychain services.

Parameters:message (str) – The error message.

static decrypt(key, cipherText)

Use the macOS Keychain key to decrypt.

Parameters:

• key (c_void_p) – The macOS Keychain private key.
• cipherText (an array which implements the buffer protocol) – The cipher text byte buffer.

Returns:

The decrypted data.

Return type:

Blob

static derivePublicKey(key)

Use the macOS Keychain key to derive the public key.

Parameters:key (c_void_p) – The macOS Keychain private key. Returns:The public key encoding Blob. Return type:Blob

static getScheme()

isTerminalMode()

Check if the TPM is in terminal mode.

Returns:True if in terminal mode. Return type:bool

setTerminalMode(isTerminal)

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

Parameters:isTerminal (bool) – True to enable terminal mode.

static sign(key, digestAlgorithm, data)

Use the macOS Keychain key to sign.

Parameters:

• key (c_void_p) – The macOS Keychain private key.
• digestAlgorithm (int from DigestAlgorithm) – The digest algorithm.
• data (an array which implements the buffer protocol) – The input byte buffer.

Returns:

The signature Blob, or an isNull Blob for an unrecognized digestAlgorithm.

Return type:

Blob

pyndn.security.tpm.tpm_key_handle module

This module defines the TpmKeyHandle class which is an abstract base class for a TPM key handle, which provides an interface to perform cryptographic operations with a key in the TPM.

class pyndn.security.tpm.tpm_key_handle.TpmKeyHandle

Bases: object

decrypt(cipherText)

Return the plain text which is decrypted from cipherText using this key.

Parameters:cipherText (an array which implements the buffer protocol) – The cipher text byte buffer. Returns:The decrypted data. Return type:Blob

derivePublicKey()

Get the encoded public key derived from this key.

Returns:The public key encoding Blob. Return type:Blob

getKeyName()

Get the key name.

Returns:The key name. Return type:Name

setKeyName(keyName)

Set the key name.

Parameters:keyName (Name) – The key name which is copied.

sign(digestAlgorithm, data)

Compute a digital signature from the byte buffer using this key with digestAlgorithm.

Parameters:

• digestAlgorithm (int from DigestAlgorithm) – The digest algorithm.
• data (an array which implements the buffer protocol) – The input byte buffer.

Returns:

The signature Blob, or an isNull Blob for an unrecognized digestAlgorithm.

Return type:

Blob

pyndn.security.tpm.tpm_key_handle_memory module

This module defines the TpmKeyHandleMemory class which extends TpmKeyHandle to implement a TPM key handle that keeps the private key in memory.

class pyndn.security.tpm.tpm_key_handle_memory.TpmKeyHandleMemory(key)

Bases: pyndn.security.tpm.tpm_key_handle.TpmKeyHandle

Create a TpmKeyHandleMemory to use the given in-memory key.

Parameters:key (TpmPrivateKey) – The in-memory key.

pyndn.security.tpm.tpm_key_handle_osx module

This module defines the TpmKeyHandleOsx class which extends TpmKeyHandle to implement a TPM key handle that uses the macOS Keychain services.

class pyndn.security.tpm.tpm_key_handle_osx.TpmKeyHandleOsx(key)

Bases: pyndn.security.tpm.tpm_key_handle.TpmKeyHandle

Create a TpmKeyHandleOsx to use the given macOS Keychain key.

Parameters:key (c_void_p) – The macOS Keychain key.

pyndn.security.tpm.tpm_private_key module

This module defines the TpmPrivateKey class which holds an in-memory private key and provides cryptographic operations such as for signing by the in-memory TPM.

class pyndn.security.tpm.tpm_private_key.TpmPrivateKey

Bases: object

Create an uninitialized TpmPrivateKey. You must call a load method to initialize it, such as loadPkcs1.

DES_EDE3_CBC_OID = '1.2.840.113549.3.7'

DES_EDE3_KEY_LENGTH = 24

EC_ENCRYPTION_OID = '1.2.840.10045.2.1'

exception Error(message)

Bases: exceptions.Exception

Create a TpmPrivateKey.Error to represents an error in private key processing.

Parameters:message (str) – The error message.

PBES2_OID = '1.2.840.113549.1.5.13'

PBKDF2_OID = '1.2.840.113549.1.5.12'

RSA_ENCRYPTION_OID = '1.2.840.113549.1.1.1'

decrypt(cipherText, algorithmType=None)

Decrypt the cipherText using this private key according the encryption algorithmType. Only RSA encryption is supported for now.

Parameters:

• cipherText (an array which implements the buffer protocol) – The cipher text byte buffer.
• algorithmType (EncryptAlgorithmType) – (optional) This decrypts according to algorithmType. If omitted, use RsaOaep.

Returns:

The decrypted data.

Return type:

Blob

Raises:

TpmPrivateKey.Error – If the private key is not loaded, if decryption is not supported for this key type, or for error decrypting.

derivePublicKey()

Get the encoded public key for this private key.

Returns:The public key encoding Blob. Return type:Blob Raises:TpmPrivateKey.Error – If no private key is loaded, or error converting to a public key.

static generatePrivateKey(keyParams)

Generate a key pair according to keyParams and return a new TpmPrivateKey with the private key. You can get the public key with derivePublicKey.

Parameters:

keyParams (KeyParams) – The parameters of the key.

Returns:

A new TpmPrivateKey.

Return type:

TpmPrivateKey

Raises:

• ValueError – If the key type is not supported.
• TpmPrivateKey.Error – For an invalid key size, or an error generating.

loadEncryptedPkcs8(encoding, password)

Load the encrypted private key from a buffer with the PKCS #8 encoding of the EncryptedPrivateKeyInfo. This replaces any existing private key in this object. This partially decodes the private key to determine the key type.

Parameters:

• encoding (str, or an array type with int elements which is converted to str) – The byte buffer with the private key encoding.
• password (an array which implements the buffer protocol) – The password for decrypting the private key, which should have characters in the range of 1 to 127..

Raises:

TpmPrivateKey.Error – For errors decoding the key.

loadPkcs1(encoding, keyType=None)

Load the unencrypted private key from a buffer with the PKCS #1 encoding. This replaces any existing private key in this object.

Parameters:

• encoding (str, or an array type with int elements which is converted to str) – The byte buffer with the private key encoding.
• keyType (KeyType) – (optional) The KeyType, such as KeyType.RSA. If omitted or None, then partially decode the private key to determine the key type.

Raises:

TpmPrivateKey.Error – For errors decoding the key.

loadPkcs8(encoding, keyType=None)

Load the unencrypted private key from a buffer with the PKCS #8 encoding. This replaces any existing private key in this object.

Parameters:

• encoding (str, or an array type with int elements which is converted to str) – The byte buffer with the private key encoding.
• keyType (KeyType) – (optional) The KeyType, such as KeyType.RSA. If omitted or None, then partially decode the private key to determine the key type.

Raises:

TpmPrivateKey.Error – For errors decoding the key.

sign(data, digestAlgorithm)

Sign the data with this private key, returning a signature Blob.

Parameters:

• data (an array which implements the buffer protocol) – The input byte buffer.
• digestAlgorithm (int from DigestAlgorithm) – The digest algorithm.

Returns:

The signature Blob, or an isNull Blob if this private key is not initialized.

Return type:

Blob

Raises:

TpmPrivateKey.Error – For unrecognized digestAlgorithm or an error in signing.

toEncryptedPkcs8(password)

Get the encoded encrypted private key in PKCS #8.

Parameters:password (an array which implements the buffer protocol) – The password for encrypting the private key, which should have characters in the range of 1 to 127.. Returns:The encoding Blob of the EncryptedPrivateKeyInfo. Return type:Blob Raises:TpmPrivateKey.Error – If no private key is loaded, or error encoding.

toPkcs1()

Get the encoded unencrypted private key in PKCS #1.

Returns:The private key encoding Blob. Return type:Blob Raises:TpmPrivateKey.Error – If no private key is loaded, or error encoding.

toPkcs8()

Get the encoded unencrypted private key in PKCS #8.

Returns:The private key encoding Blob. Return type:Blob Raises:TpmPrivateKey.Error – If no private key is loaded, or error encoding.

Module contents