pyndn.security package

Submodules

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 .

class pyndn.security.key_chain.KeyChain(identityManager=None, policyManager=None)[source]

Bases: object

Create a new KeyChain to use the optional identityManager and policyManager.

Parameters:
  • identityManager (IdentityManager) – (optional) 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.
DEFAULT_KEY_PARAMS = <pyndn.security.key_params.RsaKeyParams object at 0x5e13490>
createIdentity(identityName, params=None)[source]

Create an 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 DEFAULT_KEY_PARAMS.
Returns:

The key name of the auto-generated KSK of the identity.

Return type:

Name

createIdentityAndCertificate(identityName, params=None)[source]

Create an 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 DEFAULT_KEY_PARAMS.
Returns:

The name of the default certificate of the identity.

Return type:

Name

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
deleteIdentity(identityName)[source]

Delete the identity from the public and private key storage. If the identity to be deleted is current default system default, the method will not delete the identity and will return immediately. :param Name identityName: The name of the identity to delete.

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 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 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.
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
getPolicyManager()[source]

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

Returns:The policy manager.
Return type:PolicyManager
installIdentityCertificate(certificate)[source]

Install an identity certificate into the public key identity storage.

Parameters:certificate (IdentityCertificate) – The certificate to to added.
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.
setDefaultCertificateForKey(certificate)[source]

Set the certificate as the default for its corresponding key.

Parameters:certificate (IdentityCertificate) – The certificate.
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, certificateNameOrWireFormat=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. There are two forms of sign: sign(target, certificateName, wireFormat = None). sign(target, wireFormat = None).

Parameters:
  • target (Data, Interest 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 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.
  • certificateName (Name) – (optional) The certificate name of the key to use for signing. If omitted, use the default identity in the identity storage.
  • 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, wireFormat=None)[source]

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

Parameters:
  • target (Data) – If this is a Data object, update its signature and wire encoding.
  • key (Blob) – The key for the HmacWithSha256.
  • wireFormat (A subclass of WireFormat) – (optional) The WireFormat for calling encodeData, etc., 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, onVerifyFailed, stepCount=0)[source]

Check the signature on the Data object and call either onVerify or onVerifyFailed. 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.
  • onVerifyFailed (function object) – If the signature check fails or can’t find the public key, this calls onVerifyFailed(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.
  • 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:
  • target (Data) – The Data object to verify.
  • key (Blob) – The key for the HmacWithSha256.
  • wireFormat (A subclass of WireFormat) – (optional) The WireFormat for calling encodeData, etc., or WireFormat.getDefaultWireFormat() if omitted.
Returns:

True if the signature verifies, otherwise False.

Return type:

bool

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

Check the signature on the signed interest and call either onVerify or onVerifyFailed. 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.
  • onVerifyFailed (function object) – If the signature check fails or can’t find the public key, this calls onVerifyFailed(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.
  • stepCount (int) – (optional) The number of verification steps that have been done. If omitted, use 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(size=None)[source]

Bases: pyndn.security.key_params.KeyParams

getKeySize()[source]
class pyndn.security.key_params.EcdsaKeyParams(size=None)[source]

Bases: pyndn.security.key_params.KeyParams

getKeySize()[source]
class pyndn.security.key_params.KeyParams(keyType)[source]

Bases: object

The constructor is protected and used by subclasses.

getKeyType()[source]
class pyndn.security.key_params.RsaKeyParams(size=None)[source]

Bases: pyndn.security.key_params.KeyParams

getKeySize()[source]

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
ECDSA = 1
RSA = 0

Module contents