pyndn.security package

Subpackages

Submodules

pyndn.security.command_interest_preparer module

This module defines the CommandInterestPreparer class which keeps track of a timestamp and prepares a command interest by adding a timestamp and nonce to the name of an Interest. This class is primarily designed to be used by the CommandInterestSigner, but can also be using in an application that defines custom signing methods not supported by the KeyChain (such as HMAC-SHA1). See the Command Interest documentation: https://redmine.named-data.net/projects/ndn-cxx/wiki/CommandInterest

class pyndn.security.command_interest_preparer.CommandInterestPreparer[source]

Bases: object

Create a CommandInterestPreparer and initialize the timestamp to now.

prepareCommandInterestName(interest, wireFormat=None)[source]

Append a timestamp component and a random nonce component to interest’s name. This ensures that the timestamp is greater than the timestamp used in the previous call.

Parameters:
  • interest (Interest) – The interest whose name is append with components.
  • wireFormat (WireFormat) – (optional) A WireFormat object used to encode the SignatureInfo. If omitted, use WireFormat getDefaultWireFormat().

pyndn.security.command_interest_signer module

This module defines the CommandInterestSigner class which is a helper class to create command interests. This keeps track of a timestamp and generates command interests by adding name components according to the NFD Signed Command Interests protocol. See makeCommandInterest() for details. https://redmine.named-data.net/projects/ndn-cxx/wiki/CommandInterest

class pyndn.security.command_interest_signer.CommandInterestSigner(keyChain)[source]

Bases: pyndn.security.command_interest_preparer.CommandInterestPreparer

Create a CommandInterestSigner to use the keyChain to sign.

Parameters:keyChain (KeyChain) – The KeyChain used to sign.
MINIMUM_SIZE = 4
POS_NONCE = -3
POS_SIGNATURE_INFO = -2
POS_SIGNATURE_VALUE = -1
POS_TIMESTAMP = -4
makeCommandInterest(name, params=None, wireFormat=None)[source]

Append the timestamp and nonce name components to the supplied name, create an Interest object and signs it with the KeyChain given to the constructor. This ensures that the timestamp is greater than the timestamp used in the previous call.

Parameters:
  • name (Name) – The Name for the Interest, which is copied.
  • params (SigningInfo) – (optional) The signing parameters. If omitted, use a default SigningInfo().
  • wireFormat (WireFormat) – (optional) A WireFormat object used to encode the SignatureInfo and to encode interest name for signing. If omitted, use WireFormat getDefaultWireFormat().
Returns:

The new command Interest object.
Return type:

Interest

pyndn.security.key_chain module

This module defines the KeyChain class which provides a set of interfaces to the security library such as identity management, policy configuration and packet signing and verification. Note: This class is an experimental feature. See the API docs for more detail at http://named-data.net/doc/ndn-ccl-api/key-chain.html .

exception pyndn.security.key_chain.InvalidSigningInfoError(message)[source]

Bases: pyndn.security.key_chain.Error

Create an InvalidSigningInfoError which extends KeyChain.Error to indicate that the supplied SigningInfo is invalid.

Parameters:message (str) – The error message.
class pyndn.security.key_chain.KeyChain(arg1=None, arg2=None, arg3=None)[source]

Bases: object

There are four forms to create a KeyChain: KeyChain(pibLocator, tpmLocator, allowReset = False) - Create a KeyChain to use the PIB and TPM defined by the given locators, which creates a security v2 KeyChain that uses CertificateV2, Pib, Tpm and Validator (instead of v1 Certificate, IdentityStorage, PrivateKeyStorage and PolicyManager). KeyChain(identityManager, policyManager = None) - Create a security v1 KeyChain to use the optional identityManager and policyManager. KeyChain(pibImpl, tpmBackEnd, policyManager = None) - Create a security v2 KeyChain with explicitly-created PIB and TPM objects, and that optionally still uses the v1 PolicyManager. Finally, the default constructor KeyChain() creates a KeyChain with the default PIB and TPM, which are platform-dependent and can be overridden system-wide or individually by the user. The default constructor creates a security v2 KeyChain that uses CertificateV2, Pib, Tpm and Validator. However, if the default security v1 database file still exists, and the default security v2 database file does not yet exists, then assume that the system is running an older NFD and create a security v1 KeyChain with the default IdentityManager and a NoVerifyPolicyManager.

Parameters:
  • pibLocator (str) – The PIB locator, e.g., “pib-sqlite3:/example/dir”.
  • tpmLocator (str) – The TPM locator, e.g., “tpm-memory:”.
  • allowReset (bool) – (optional) If True, the PIB will be reset when the supplied tpmLocator mismatches the one in the PIB. If omitted, don’t allow reset.
  • identityManager (IdentityManager) – The identity manager as a subclass of IdentityManager. If omitted, use the default IdentityManager constructor.
  • policyManager (PolicyManager) – (optional) The policy manager as a subclass of PolicyManager. If omitted, use NoVerifyPolicyManager.
  • pibImpl (PibImpl) – An explicitly-created PIB object of a subclass of PibImpl.
  • tpmBackEnd (TpmBackEnd) – An explicitly-created TPM object of a subclass of TpmBackEnd.
DEFAULT_KEY_PARAMS = <pyndn.security.key_params.RsaKeyParams object>
exception Error(message)[source]

Bases: exceptions.Exception

Create a KeyChain.Error which represents an error in KeyChain processing.

Parameters:message (str) – The error message.
addCertificate(key, certificate)[source]

Add a certificate for the key. If the key had no default certificate selected, the added certificate will be set as the default certificate for this key.

Parameters:
  • key (PibKey) – A valid PibKey object.
  • certificate (CertificateV2) – The certificate to add. This copies the object.
Raises:

ValueError – If the key does not match the certificate.
Note:

This method overwrites a certificate with the same name, without considering the implicit digest.
createIdentity(identityName, params=None)[source]

Create a security v1 identity by creating a pair of Key-Signing-Key (KSK) for this identity and a self-signed certificate of the KSK. If a key pair or certificate for the identity already exists, use it.

Deprecated:

Use createIdentityAndCertificate which returns the certificate name instead of the key name. You can use IdentityCertificate.certificateNameToPublicKeyName to convert the certificate name to the key name.
Parameters:
  • identityName (Name) – The name of the identity.
  • params (KeyParams) – (optional) The key parameters if a key needs to be generated for the identity. If omitted, use getDefaultKeyParams().
Returns:

The key name of the auto-generated KSK of the identity.
Return type:

Name
createIdentityAndCertificate(identityName, params=None)[source]

Create a security v1 identity by creating a pair of Key-Signing-Key (KSK) for this identity and a self-signed certificate of the KSK. If a key pair or certificate for the identity already exists, use it.

Parameters:
  • identityName (Name) – The name of the identity.
  • params (KeyParams) – (optional) The key parameters if a key needs to be generated for the identity. If omitted, use getDefaultKeyParams().
Returns:

The name of the default certificate of the identity.
Return type:

Name
createIdentityV2(identityName, params=None)[source]

Create a security V2 identity for identityName. This method will check if the identity exists in PIB and whether the identity has a default key and default certificate. If the identity does not exist, this method will create the identity in PIB. If the identity’s default key does not exist, this method will create a key pair and set it as the identity’s default key. If the key’s default certificate is missing, this method will create a self-signed certificate for the key. If identityName did not exist and no default identity was selected before, the created identity will be set as the default identity.

Parameters:
  • identityName (Name) – The name of the identity.
  • params (KeyParams) – (optional) The key parameters if a key needs to be generated for the identity. If omitted, use getDefaultKeyParams().
Returns:

The created PibIdentity instance.
Return type:

PibIdentity
createKey(identity, params=None)[source]

Create a key for the identity according to params. If the identity had no default key selected, the created key will be set as the default for this identity. This method will also create a self-signed certificate for the created key.

Parameters:
  • identity (PibIdentity) – A valid PibIdentity object.
  • params (KeyParams) – (optional) The key parameters if a key needs to be generated for the identity. If omitted, use getDefaultKeyParams().
Returns:

The new PibKey.
Return type:

PibKey
createSigningRequest(keyName)[source]

Create a public key signing request.

Parameters:keyName (Name) – The name of the key.
Returns:The signing request data.
Return type:Blob
deleteCertificate(key, certificateName)[source]

Delete the certificate with the given name from the given key. If the certificate does not exist, this does nothing.

Parameters:
  • key (PibKey) – A valid PibKey object.
  • certificateName (Name) – The name of the certificate to delete.
Raises:

ValueError – If certificateName does not follow certificate naming conventions.
deleteIdentity(identity)[source]

This method has two forms: deleteIdentity(identity) - Delete the PibIdentity identity. After this operation, the identity is invalid. deleteIdentity(identityName) - Delete the identity from the public and private key storage. If the identity to be deleted is the current default system default, the method will not delete the identity and will return immediately.

Parameters:
  • identity (PibIdentity) – The identity to delete.
  • identityName (Name) – The name of the identity to delete.
deleteKey(identity, key)[source]

Delete the given key of the given identity. The key becomes invalid.

Parameters:
  • identity (PibIdentity) – A valid PibIdentity object.
  • key (PibKey) – The key to delete.
Raises:

ValueError – If the key does not belong to the identity.
exportSafeBag(certificate, password=None)[source]

Export a certificate and its corresponding private key in a SafeBag.

Parameters:
  • certificate (CertificateV2) – The certificate to export. This gets the key from the TPM using certificate.getKeyName().
  • password (an array which implements the buffer protocol) – (optional) 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 put a PKCS #8 EncryptedPrivateKeyInfo in the SafeBag. If the password is omitted or None, put an unencrypted PKCS #8 PrivateKeyInfo in the SafeBag.
Returns:

A SafeBag carrying the certificate and private key.
Return type:

SafeBag
Raises:

KeyChain.Error – if the certificate.getKeyName() key does not exist, if the TPM does not support exporting an unencrypted private key, or for other errors exporting the private key.
generateEcdsaKeyPair(identityName, isKsk=False, keySize=2048)[source]

Generate a pair of ECDSA keys for the specified identity.

Parameters:
  • identityName (Name) – The name of the identity.
  • isKsk (bool) – (optional) true for generating a Key-Signing-Key (KSK), false for a Data-Signing-Key (DSK). If omitted, generate a Data-Signing-Key.
  • keySize (int) – (optional) The size of the key. If omitted, use a default secure key size.
Returns:

The generated key name.
Return type:

Name
generateEcdsaKeyPairAsDefault(identityName, isKsk=False, keySize=2048)[source]

Generate a pair of ECDSA keys for the specified identity and set it as the default key for the identity.

Parameters:
  • NameidentityName – The name of the identity.
  • isKsk (bool) – (optional) true for generating a Key-Signing-Key (KSK), false for a Data-Signing-Key (DSK). If omitted, generate a Data-Signing-Key.
  • keySize (int) – (optional) The size of the key. If omitted, use a default secure key size.
Returns:

The generated key name.
Return type:

Name
generateRSAKeyPair(identityName, isKsk=False, keySize=2048)[source]

Generate a pair of RSA keys for the specified identity.

Parameters:
  • identityName (Name) – The name of the identity.
  • isKsk (bool) – (optional) true for generating a Key-Signing-Key (KSK), false for a Data-Signing-Key (DSK). If omitted, generate a Data-Signing-Key.
  • keySize (int) – (optional) The size of the key. If omitted, use a default secure key size.
Returns:

The generated key name.
Return type:

Name
generateRSAKeyPairAsDefault(identityName, isKsk=False, keySize=2048)[source]

Generate a pair of RSA keys for the specified identity and set it as the default key for the identity.

Parameters:
  • NameidentityName – The name of the identity.
  • isKsk (bool) – (optional) true for generating a Key-Signing-Key (KSK), false for a Data-Signing-Key (DSK). If omitted, generate a Data-Signing-Key.
  • keySize (int) – (optional) The size of the key. If omitted, use a default secure key size.
Returns:

The generated key name.
Return type:

Name
getCertificate(certificateName)[source]

Get a certificate with the specified name.

Parameters:certificateName (Name) – The name of the requested certificate.
Returns:The requested certificate.
Return type:IdentityCertificate
getDefaultCertificateName()[source]

Get the default certificate name of the default identity.

Returns:The requested certificate name.
Return type:Name
Raises:SecurityException – if the default identity is not set or the default key name for the identity is not set or the default certificate name for the key name is not set.
getDefaultIdentity()[source]

Get the default identity.

Returns:The name of default identity.
Return type:Name
Raises:SecurityException – if the default identity is not set.
static getDefaultKeyParams()[source]
getIdentityCertificate(certificateName)[source]
Deprecated:Use getCertificate.
getIdentityManager()[source]

Get the identity manager given to or created by the constructor.

Returns:The identity manager.
Return type:IdentityManager
getIsSecurityV1()[source]

Get the flag set by the constructor if this is a security v1 or v2 KeyChain.

Returns:True if this is a security v1 KeyChain, false if this is a security v2 KeyChain.
Return type:bool
getPib()[source]
Return type:Pib
getPolicyManager()[source]

Get the policy manager given to or created by the constructor.

Returns:The policy manager.
Return type:PolicyManager
getTpm()[source]
Return type:Tpm
importSafeBag(safeBag, password=None)[source]

Import a certificate and its corresponding private key encapsulated in a SafeBag. If the certificate and key are imported properly, the default setting will be updated as if a new key and certificate is added into this KeyChain.

Parameters:
  • safeBag (SafeBag) – The SafeBag containing the certificate and private key. This copies the values from the SafeBag.
  • password (an array which implements the buffer protocol) – (optional) 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 omitted or None, import an unencrypted PKCS #8 PrivateKeyInfo.
Raises:

KeyChain.Error – if the private key cannot be imported, or if a public key or private key of the same name already exists, or if a certificate of the same name already exists.
installIdentityCertificate(certificate)[source]

Install an identity certificate into the public key identity storage.

Parameters:certificate (IdentityCertificate) – The certificate to to added.
static registerPibBackend(scheme, makePibImpl)[source]

Add to the PIB factories map where scheme is the key and makePibImpl is the value. If your application has its own PIB implementations, this must be called before creating a KeyChain instance which uses your PIB scheme.

Parameters:
  • scheme (str) – The PIB scheme.
  • makePibImpl (function object) – A callback which takes the PIB location and returns a new PibImpl instance.
static registerTpmBackend(scheme, makeTpmBackEnd)[source]

Add to the TPM factories map where scheme is the key and makeTpmBackEnd is the value. If your application has its own TPM implementations, this must be called before creating a KeyChain instance which uses your TPM scheme.

Parameters:
  • scheme (str) – The TPM scheme.
  • makeTpmBackEnd (function object) – A callback which takes the TPM location and returns a new TpmBackEnd instance.
revokeCertificate(certificateName)[source]

Revoke a certificate.

Parameters:certificateName (Name) – The name of the certificate that will be revoked.
revokeKey(keyName)[source]

Revoke a key.

Parameters:keyName (Name) – The name of the key that will be revoked.
selfSign(key, wireFormat=None)[source]

Generate a self-signed certificate for the public key and add it to the PIB. This creates the certificate name from the key name by appending “self” and a version based on the current time. If no default certificate for the key has been set, then set the certificate as the default for the key.

Parameters:
  • key (PibKey) – The PibKey with the key name and public key.
  • wireFormat (WireFormat) – (optional) A WireFormat object used to encode the certificate. If omitted, use WireFormat getDefaultWireFormat().
Returns:

The new certificate.
Return type:

CertificateV2
setDefaultCertificate(key, certificate)[source]

Set the certificate as the default certificate of the key. The certificate will be added to the key, potentially overriding an existing certificate if it has the same name (without considering implicit digest).

Parameters:
  • key (PibKey) – A valid PibKey object.
  • certificate (CertificateV2) – The certificate to become the default. This copies the object.
setDefaultCertificateForKey(certificate)[source]

Set the certificate as the default for its corresponding key.

Parameters:certificate (IdentityCertificate) – The certificate.
setDefaultIdentity(identity)[source]

Set the identity as the default identity.

Parameters:identity (PibIdentity) – The identity to make the default.
setDefaultKey(identity, key)[source]

Set the key as the default key of identity.

Parameters:
  • identity (PibIdentity) – A valid PibIdentity object.
  • key (PibKey) – The key to become the default.
Raises:

ValueError – If the key does not belong to the identity.
setDefaultKeyForIdentity(keyName, identityNameCheck=None)[source]

Set a key as the default key of an identity. The identity name is inferred from keyName.

Parameters:
  • keyName (Name) – The name of the key.
  • identityNameCheck (Name) – (optional) The identity name to check that the keyName contains the same identity name. If an empty name, it is ignored.
setFace(face)[source]

Set the Face which will be used to fetch required certificates.

Parameters:face (Face) – The Face object.
sign(target, paramsOrCertificateName=None, wireFormat=None)[source]

Sign the target. If it is a Data or Interest object, set its signature. If it is an array, return a signature object.

Parameters:
  • target (Data, Interest or an array which implements the buffer protocol) – If this is a Data object, wire encode for signing, replace its Signature object based on the type of key and other info in the SigningInfo params or default identity, and update the wireEncoding. If this is an Interest object, wire encode for signing, append a SignatureInfo to the Interest name, sign the name components and append a final name component with the signature bits. If it is an array, sign it and return a Signature object.
  • paramsOrCertificateName (SigningInfo or Name) – (optional) If a SigningInfo, it is the signing parameters. If a Name, it is the certificate name of the key to use for signing. If omitted and this is a security v1 KeyChain then use the IdentityManager to get the default identity. Otherwise, use the PIB to get the default key of the default identity.
  • wireFormat (A subclass of WireFormat) – (optional) A WireFormat object used to encode the input. If omitted, use WireFormat.getDefaultWireFormat().
Returns:

The Signature object (only if the target is an array).
Return type:

An object of a subclass of Signature
signByIdentity(target, identityName=None, wireFormat=None)[source]

Sign the target. If it is a Data object, set its signature. If it is an array, return a signature object.

Parameters:
  • target (Data or an array which implements the buffer protocol) – If this is a Data object, wire encode for signing, update its signature and key locator field and wireEncoding. If it is an array, sign it and return a Signature object.
  • identityName (Name) – (optional) The identity name for the key to use for signing. If omitted, infer the signing identity from the data packet name.
  • wireFormat (A subclass of WireFormat) – (optional) A WireFormat object used to encode the input. If omitted, use WireFormat.getDefaultWireFormat().
Returns:

The Signature object (only if the target is an array).
Return type:

An object of a subclass of Signature
static signWithHmacWithSha256(target, key, keyName=None, wireFormat=None)[source]

Wire encode the target, compute an HmacWithSha256 and update the object. Note: This method is an experimental feature. The API may change.

Parameters:
  • target (Data or Interest) – If the target is a Data object (which should already have an HmacWithSha256Signature with a KeyLocator for the key name), then update its signature and wire encoding. If the target is an Interest, then append a SignatureInfo to the Interest name, compute an HmacWithSha256 signature for the name components and append a final name component with the signature bits.
  • key (Blob) – The key for the HmacWithSha256.
  • keyName (Name) – (needed if target is an Interest) The name of the key for the KeyLocator in the SignatureInfo which is added to the Interest name.
  • wireFormat (A subclass of WireFormat) – (optional) The WireFormat for encoding the target, or WireFormat.getDefaultWireFormat() if omitted.
signWithSha256(target, wireFormat=None)[source]

Sign the target using DigestSha256.

Parameters:
  • target (Data or Interest) – If this is a Data object, wire encode for signing, digest it and set its SignatureInfo to a DigestSha256, updating its signature and wireEncoding. If this is an Interest object, wire encode for signing, append a SignatureInfo for DigestSha256 to the Interest name, digest the name components and append a final name component with the signature bits.
  • wireFormat (A subclass of WireFormat) – (optional) A WireFormat object used to encode the input. If omitted, use WireFormat.getDefaultWireFormat().
verifyData(data, onVerified, onValidationFailed, stepCount=0)[source]

Check the signature on the Data object and call either onVerify or onValidationFailed. We use callback functions because verify may fetch information to check the signature.

Parameters:
  • data (Data) – The Data object with the signature to check.
  • onVerified (function object) – If the signature is verified, this calls onVerified(data). NOTE: The library will log any exceptions raised by this callback, but for better error handling the callback should catch and properly handle any exceptions.
  • onValidationFailed (function object) – If the signature check fails or can’t find the public key, this calls onValidationFailed(data, reason) with the Data object and reason string. This also supports the deprecated callback onValidationFailed(data) but you should use the callback with the reason string. NOTE: The library will log any exceptions raised by this callback, but for better error handling the callback should catch and properly handle any exceptions.
  • stepCount (int) – (optional) The number of verification steps that have been done. If omitted, use 0.
static verifyDataWithHmacWithSha256(data, key, wireFormat=None)[source]

Compute a new HmacWithSha256 for the target and verify it against the signature value. Note: This method is an experimental feature. The API may change.

Parameters:
  • data (Data) – The Data object to verify.
  • key (Blob) – The key for the HmacWithSha256.
  • wireFormat (A subclass of WireFormat) – (optional) A WireFormat object used to encode the input. If omitted, use WireFormat getDefaultWireFormat().
Returns:

True if the signature verifies, otherwise False.
Return type:

bool
verifyInterest(interest, onVerified, onValidationFailed, stepCount=0, wireFormat=None)[source]

Check the signature on the signed interest and call either onVerify or onValidationFailed. We use callback functions because verify may fetch information to check the signature.

Parameters:
  • interest (Interest) – The interest with the signature to check.
  • onVerified (function object) – If the signature is verified, this calls onVerified(interest). NOTE: The library will log any exceptions raised by this callback, but for better error handling the callback should catch and properly handle any exceptions.
  • onValidationFailed (function object) – If the signature check fails or can’t find the public key, this calls onValidationFailed(interest, reason) with the Interest object and reason string. This also supports the deprecated callback onValidationFailed(interest) but you should use the callback with the reason string. NOTE: The library will log any exceptions raised by this callback, but for better error handling the callback should catch and properly handle any exceptions.
  • stepCount (int) – (optional) The number of verification steps that have been done. If omitted, use 0.
static verifyInterestWithHmacWithSha256(interest, key, wireFormat=None)[source]

Compute a new HmacWithSha256 for all but the final name component and verify it against the signature value in the final name component. Note: This method is an experimental feature. The API may change.

Parameters:
  • interest (Interest) – The Interest object to verify.
  • key (Blob) – The key for the HmacWithSha256.
  • wireFormat (A subclass of WireFormat) – (optional) A WireFormat object used to encode the input. If omitted, use WireFormat getDefaultWireFormat().
Returns:

True if the signature verifies, otherwise False.
Return type:

bool
exception pyndn.security.key_chain.LocatorMismatchError(message)[source]

Bases: pyndn.security.key_chain.Error

Create a LocatorMismatchError which extends KeyChain.Error to indicate that the supplied TPM locator does not match the locator stored in the PIB.

Parameters:message (str) – The error message.

pyndn.security.key_id_type module

This module defines the KeyIdType enum which represents the type of a KeyId component in a key name.

class pyndn.security.key_id_type.KeyIdType[source]

Bases: object

RANDOM = 2
SHA256 = 1
USER_SPECIFIED = 0

pyndn.security.key_params module

This module defines KeyParams which is a base class for key parameters. This also defines the subclasses which are used to store parameters for key generation.

class pyndn.security.key_params.AesKeyParams(keyIdOrSize=None, arg2=None)[source]

Bases: pyndn.security.key_params.KeyParams

Possible forms of the constructor are: AesKeyParams(keyId, size) AesKeyParams(keyId) AesKeyParams(size, keyIdType) AesKeyParams(size) AesKeyParams()

static getDefaultSize()[source]
getKeySize()[source]
static getType()[source]
class pyndn.security.key_params.EcKeyParams(keyIdOrSize=None, arg2=None)[source]

Bases: pyndn.security.key_params.KeyParams

Possible forms of the constructor are: EcKeyParams(keyId, size) EcKeyParams(keyId) EcKeyParams(size, keyIdType) EcKeyParams(size) EcKeyParams()

static getDefaultSize()[source]
getKeySize()[source]
static getType()[source]
class pyndn.security.key_params.EcdsaKeyParams(keyIdOrSize=None, arg2=None)[source]

Bases: pyndn.security.key_params.EcKeyParams

Deprecated:Use EcKeyParams
class pyndn.security.key_params.KeyParams(keyType, keyIdTypeOrKeyId)[source]

Bases: object

Create a key generation parameter. This constructor is protected and used by subclasses.

Parameters:
  • keyType (An int from the KeyType enum.) – The type for the created key.
  • keyIdTypeOrKeyId (int from KeyIdType or Name.Component.) – If this is a KeyIdType, it is the method for how the key id should be generated, which must not be KeyIdType.USER_SPECIFIED. If this is a Name.Component, it is the user-specified key ID, in which case this sets the keyIdType to KeyIdType.USER_SPECIFIED. (The keyId must not be empty.)
Throws ValueError:
 

If keyIdTypeOrKeyId is a KeyIdType and it is KeyIdType.USER_SPECIFIED, or if keyIdTypeOrKeyId is a Name.Component and it is empty.
getKeyId()[source]
getKeyIdType()[source]
getKeyType()[source]
setKeyId(keyId)[source]
class pyndn.security.key_params.RsaKeyParams(keyIdOrSize=None, arg2=None)[source]

Bases: pyndn.security.key_params.KeyParams

Possible forms of the constructor are: RsaKeyParams(keyId, size) RsaKeyParams(keyId) RsaKeyParams(size, keyIdType) RsaKeyParams(size) RsaKeyParams()

static getDefaultSize()[source]
getKeySize()[source]
static getType()[source]

pyndn.security.safe_bag module

This module defines the SafeBag class which represents a container for sensitive related information such as a certificate and private key.

class pyndn.security.safe_bag.SafeBag(arg1, privateKeyBag=None, publicKeyEncoding=None, password=None, digestAlgorithm=1, wireFormat=None)[source]

Bases: object

There are three forms of the SafeBag constructor: SafeBag(certificate, privateKeyBag) - Create a SafeBag with the given certificate and private key. SafeBag(keyName, privateKeyBag, publicKeyEncoding [, password, digestAlgorithm, wireFormat]) - Create a SafeBag with given private key and a new self-signed certificate for the given public key. SafeBag(input) - Create a SafeBag by decoding the input as an NDN-TLV SafeBag.

Parameters:
  • certificate (Data) – The certificate data packet (used only for SafeBag(certificate, privateKeyBag)). This copies the object.
  • privateKeyBag (Blob) – The encoded private key. If encrypted, this is a PKCS #8 EncryptedPrivateKeyInfo. If not encrypted, this is an unencrypted PKCS #8 PrivateKeyInfo.
  • password (an array which implements the buffer protocol) – (optional) The password for decrypting the private key in order to sign the self-signed certificate, 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 omitted or None, privateKeyBag is an unencrypted PKCS #8 PrivateKeyInfo.
  • digestAlgorithm (int from the DigestAlgorithm enum) – (optional) The digest algorithm for signing the self-signed certificate. If omitted, use DigestAlgorithm.SHA256 .
  • wireFormat (WireFormat) – (optional) A WireFormat object used to encode the self-signed certificate in order to sign it. If omitted, use WireFormat.getDefaultWireFormat().
  • input (A Blob or an array type with int elements) – The array with the bytes to decode.
getCertificate()[source]

Get the certificate data packet.

Returns:The certificate as a Data packet. If you need to process it as a certificate object then you must create a new CertificateV2(data).
Return type:Data
getPrivateKeyBag()[source]

Get the encoded private key.

Returns:The encoded private key. If encrypted, this is a PKCS #8 EncryptedPrivateKeyInfo. If not encrypted, this is an unencrypted PKCS #8 PrivateKeyInfo.
Return type:Blob
wireDecode(input)[source]

Decode the input as an NDN-TLV SafeBag and update this object.

Parameters:input (A Blob or an array type with int elements) – The array with the bytes to decode.
wireEncode(wireFormat=None)[source]

Encode this as an NDN-TLV SafeBag.

Returns:The encoded byte array as a Blob.
Return type:Blob

pyndn.security.security_exception module

This module defines the SecurityException class which extends Exception to report an exception from the security library.

exception pyndn.security.security_exception.SecurityException(message)[source]

Bases: exceptions.Exception

exception pyndn.security.security_exception.UnrecognizedDigestAlgorithmException(message)[source]

Bases: pyndn.security.security_exception.SecurityException

exception pyndn.security.security_exception.UnrecognizedKeyFormatException(message)[source]

Bases: pyndn.security.security_exception.SecurityException

pyndn.security.security_types module

This module defines constants used by the security library.

class pyndn.security.security_types.DigestAlgorithm[source]

Bases: object

SHA256 = 1
class pyndn.security.security_types.KeyClass[source]

Bases: object

PRIVATE = 2
PUBLIC = 1
SYMMETRIC = 3
class pyndn.security.security_types.KeyType[source]

Bases: object

AES = 128
EC = 1
ECDSA = 1
RSA = 0

pyndn.security.signing_info module

This module defines the SigningInfo class which holds the signing parameters passed to the KeyChain. A SigningInfo is invalid if the specified identity/key/certificate does not exist, or the PibIdentity or PibKey instance is not valid.

class pyndn.security.signing_info.SigningInfo(arg1=None, arg2=None)[source]

Bases: object

The SigningInfo constructor has multiple forms: SigningInfo() - Create a default SigningInfo with SigningInfo.SignerType.NULL (which will cause KeyChain.sign to use the

default identity) and an empty Name.
SigningInfo(signingInfo) - Create a SigningInfo as a copy of the given
signingInfo (taking a pointer to the given signingInfo PibIdentity and PibKey without copying).

SigningInfo(signerType, signerName) - Create a SigningInfo with the signerType and optional signer Name. Signinginfo(identity) - Create a SigningInfo of type SigningInfo.SignerType.ID according to the given PibIdentity, where the digest algorithm is set to DigestAlgorithm.SHA256. SigningInfo(key) - Create a SigningInfo of type SigningInfo.SignerType.KEY according to the given PibKey, where the digest algorithm is set to DigestAlgorithm.SHA256. SigningInfo(signingString) - Create a SigningInfo from its string representation, where the digest algorithm is set to DigestAlgorithm.SHA256.

Parameters:
  • signingInfo (SigningInfo) – The SigningInfo to copy.
  • signerType (An int from the SigningInfo.SignerType enum.) – The type of signer.
  • signerName (Name) – The name of signer. The interpretation of the signerName differs based on the signerType. This copies the Name.
  • identity (PibIdentity) – An existing PibIdentity which is not copied.
  • key (PibKey) – An existing PibKey which is not copied.
  • signingString (str) – The representative signing string for the signing method, as follows: Default signing: “” (the empty string). Signing with the default certificate of the default key for the identity with the specified name: id:/my-identity. Signing with the default certificate of the key with the specified name: key:/my-identity/ksk-1. Signing with the certificate with the specified name: cert:/my-identity/KEY/ksk-1/ID-CERT/%FD%01. Signing with sha256 digest: id:/localhost/identity/digest-sha256 (the value returned by getDigestSha256Identity()).
Raises:

ValueError – If the signingString format is invalid.
class SignerType[source]

Bases: object

CERT = 3
ID = 1
KEY = 2
NULL = 0
SHA256 = 4
getDigestAlgorithm()[source]

Get the digest algorithm for public key operations.

Returns:The digest algorithm.
Return type:int from the DigestAlgorithm enum
static getDigestSha256Identity()[source]

Get the localhost identity which indicates that the signature is generated using SHA-256.

Returns:A new Name of the SHA-256 identity.
Return type:Name
getPibIdentity()[source]

Get the PibIdentity of the signer.

Returns:The PibIdentity handler of the signer, or None if getSignerName() should be used to find the identity.
Return type:PibIdentity
Raises:ValueError – If the signer type is not SignerType.ID.
getPibKey()[source]

Get the PibKey of the signer.

Returns:The PibKey handler of the signer, or None if getSignerName() should be used to find the key.
Return type:PibKey
Raises:ValueError – If the signer type is not SignerType.KEY.
getSignerName()[source]

Get the name of signer.

Returns:The name of signer. The interpretation differs based on the signerType.
Return type:Name
getSignerType()[source]

Get the type of the signer.

:return:The type of the signer :rtype: int from the SigningInfo.SignerType enum

getValidityPeriod()[source]

Get the validity period for the signature info. Note that the equivalent ndn-cxx method uses a semi-prepared SignatureInfo, but this method only uses the ValidityPeriod from the SignatureInfo.

Returns:The validity period.
Return type:ValidityPeriod
reset(signerType)[source]

Check and set the signerType, and set others to default values. This does NOT reset the digest algorithm.

Parameters:signerType (int from the SigningInfo.SignerType enum) – The type of signer.
setDigestAlgorithm(digestAlgorithm)[source]

Set the digest algorithm for public key operations.

Parameters:digestAlgorithm (int from the DigestAlgorithm enum) – The digest algorithm.
Returns:This SigningInfo.
Return type:SigningInfo
setPibIdentity(identity)[source]

Set this to type SignerType.ID according to the given PibIdentity. This does not change the digest algorithm.

Parameters:identity (PibIdentity) – An existing PibIdentity which is not copied, or None. If this is None then use the default identity, otherwise use identity.getName().
Returns:This SigningInfo.
Return type:SigningInfo
setPibKey(key)[source]

Set this to type SignerType.KEY according to the given PibKey. This does not change the digest algorithm.

Parameters:key (PibKey) – An existing PibKey which is not copied, or None. If this is None then use the default key for the identity, otherwise use key.getName().
Returns:This SigningInfo.
Return type:SigningInfo
setSha256Signing()[source]

Set this to type SignerType.SHA256, and set the digest algorithm to DigestAlgorithm.SHA256.

Returns:This SigningInfo.
Return type:SigningInfo
setSigningCertificateName(certificateName)[source]

Set this to type SignerType.CERT and a certificate with name certificateName. This does not change the digest algorithm.

Parameters:certificateName (Name) – The name of the certificate. This copies the Name.
Returns:This SigningInfo.
Return type:SigningInfo
setSigningIdentity(identityName)[source]

Set this to type SignerType.ID and an identity with name identityName. This does not change the digest algorithm.

Parameters:identityName (Name) – The name of the identity. This copies the Name.
Returns:This SigningInfo.
Return type:SigningInfo
setSigningKeyName(keyName)[source]

Set this to type SignerType.KEY and a key with name keyName. This does not change the digest algorithm.

Parameters:keyName (Name) – The name of the key. This copies the Name.
Returns:This SigningInfo.
Return type:SigningInfo
setValidityPeriod(validityPeriod)[source]

Set the validity period for the signature info. Note that the equivalent ndn-cxx method uses a semi-prepared SignatureInfo, but this method only uses the ValidityPeriod from the SignatureInfo.

Parameters:validityPeriod (ValidityPeriod) – The validity period, which is copied.
Returns:This SigningInfo.
Return type:SigningInfo

pyndn.security.validator_config module

This module defines the ValidatorConfig class which extends Validator to implement a validator which can be set up via a configuration file.

class pyndn.security.validator_config.ValidatorConfig(fetcherOrFace)[source]

Bases: pyndn.security.v2.validator.Validator

The constructor has two forms: ValidatorConfig(fetcher) - Create a ValidatorConfig that uses the given certificate fetcher. ValidatorConfig(face) - Create a ValidatorConfig that uses a CertificateFetcherFromNetwork for the given Face.

Parameters:
  • fetcher (CertificateFetcher) – the certificate fetcher to use.
  • face (Face) – The face for the certificate fetcher to call expressInterest.
load(filePathOrInputOrConfigSection, inputName=None)[source]

There are three forms of load: load(filePath) - Load the configuration from the given config file. load(input, inputName) - Load the configuration from the given input string. load(configSection, inputName) - Load the configuration from the given configSection. Each of these forms of load replaces any existing configuration.

Parameters:
  • filePath (str) – The The path of the config file.
  • input (str) – The contents of the configuration rules, with lines separated by “n” or “rn”.
  • configSection (BoostInfoTree) – The configuration section loaded from the config file. It should have one “validator” section.
  • inputName (str) – Used for log messages, etc.

pyndn.security.validator_config_error module

This module defines the ValidatorConfigError class for reporting an error using ValidatorConfig.

exception pyndn.security.validator_config_error.ValidatorConfigError(message)[source]

Bases: exceptions.Exception

Create a ValidatorConfigError.

Parameters:message (str) – The error message.

pyndn.security.validator_null module

This module defines the ValidatorNull class which extends Validator with an “accept-all” policy and an offline certificate fetcher.

class pyndn.security.validator_null.ValidatorNull[source]

Bases: pyndn.security.v2.validator.Validator

pyndn.security.verification_helpers module

This module defines the VerificationHelpers which has static methods to verify signatures and digests.

class pyndn.security.verification_helpers.VerificationHelpers[source]

Bases: object

static verifyDataSignature(data, publicKeyOrCertificate, digestAlgorithm=None, wireFormat=None)[source]

Verify the Data packet using the public key. This does not check the type of public key or digest algorithm against the type of SignatureInfo in the Data packet such as Sha256WithRsaSignature.

Parameters:
  • data (Data) – The Data packet to verify.
  • publicKeyOrCertificate (Blob, or an object which is the same as the bytes() operator, or CertificateV2) – The object containing the public key, or the public key DER which is used to make the PublicKey object, or the certificate containing the public key.
  • digestAlgorithm – (optional) The digest algorithm. If omitted, use DigestAlgorithm.SHA256.
  • wireFormat (WireFormat) – (optional) A WireFormat object used to encode the Data packet. If omitted, use WireFormat.getDefaultWireFormat().
Raises:

ValueError for an invalid public key type or digestAlgorithm.
static verifyDigest(buffer, digest, digestAlgorithm)[source]

Verify the buffer against the digest using the digest algorithm.

Parameters:
  • buffer (Blob or an object which is the same as the bytes() operator) – The input buffer to verify.
  • digest (Blob or an object which is the same as the bytes() operator) – The digest bytes.
  • digestAlgorithm (int from DigestAlgorithm) – The digest algorithm.
Returns:

True if verification succeeds, False if verification fails.
Return type:

bool
Raises:

ValueError for an invalid digestAlgorithm.
static verifyInterestSignature(interest, publicKeyOrCertificate, digestAlgorithm=None, wireFormat=None)[source]

Verify the Interest packet using the public key, where the last two name components are the SignatureInfo and signature bytes. This does not check the type of public key or digest algorithm against the type of SignatureInfo such as Sha256WithRsaSignature.

Parameters:
  • interest (Interest) – The Interest packet to verify.
  • publicKeyOrCertificate (Blob, or an object which is the same as the bytes() operator, or CertificateV2) – The object containing the public key, or the public key DER which is used to make the PublicKey object, or the certificate containing the public key.
  • digestAlgorithm – (optional) The digest algorithm. If omitted, use DigestAlgorithm.SHA256.
  • wireFormat (WireFormat) – (optional) A WireFormat object used to encode the Interest packet. If omitted, use WireFormat.getDefaultWireFormat().
Raises:

ValueError for an invalid public key type or digestAlgorithm.
static verifySignature(buffer, signature, publicKey, digestAlgorithm=1)[source]

Verify the buffer against the signature using the public key.

Parameters:
  • buffer (Blob or an object which is the same as the bytes() operator) – The input buffer to verify.
  • signature (Blob or an object which is the same as the bytes() operator) – The signature bytes.
  • publicKey (PublicKey or Blob or an object which is the same as the bytes() operator) – The object containing the public key, or the public key DER which is used to make the PublicKey object.
  • digestAlgorithm (int from DigestAlgorithm) – (optional) The digest algorithm. If omitted, use DigestAlgorithm.SHA256.
Returns:

True if verification succeeds, False if verification fails.
Return type:

bool
Raises:

ValueError for an invalid public key type or digestAlgorithm.

Module contents