ndn.security package

Introduction

The ndn.security package provides basic tools for security use.

Signer

A Signer is a class used to sign a packet during encoding.

class ndn.encoding.Signer

abstract get_signature_value_size()

Get the size of SignatureValue. If the size is variable, return the maximum possible value.

Return type:

int

Returns:

the size of SignatureValue.

abstract write_signature_info(signature_info)

Fill in the fields of SignatureInfo.

Parameters:

signature_info – a blank SignatureInfo object.

abstract write_signature_value(wire, contents)

Calculate the SignatureValue and write it into wire. The length of wire is exactly what get_signature_value_size() returns. Basically this function should return the same value except for ECDSA.

Parameters:

• wire (Union[bytearray, memoryview]) – the buffer to contain SignatureValue.

• contents (List[Union[bytearray, memoryview]]) – a list of memory blocks that needs to be covered.

Return type:

int

Returns:

the actual size of SignatureValue.

Validator

A Validator is a async function called to validate an Interest or Data packet. It takes 2 arguments: a FormalName and a SignaturePtrs, and returns whether the packet is validated.

Keychain

A Keychain is a class which contains Identities, Keys associated with Identities and associated Certificates.

class ndn.security.keychain.Keychain

The abstract Keychain class, derived from collections.abc.Mapping. It behaves like an immutable dict from FormalName to Identity. The implementation of Identity varies with concrete implementations. Generally, its methods should also accept NonStrictName as inputs. This includes operators such as in and [].

abstract get_signer(sign_args)

Get a signer from sign_args.

Parameters:

sign_args (dict[str, Any]) – the signing arguments provided by the application.

Returns:

a signer.

Return type:

Signer

KeychainDigest

class ndn.security.keychain.keychain_digest.KeychainDigest

A signer which has no Identity and always returns a SHA-256 digest signer.

get_signer(sign_args)

Get a signer from sign_args.

Parameters:

sign_args (Dict[str, Any]) – the signing arguments provided by the application.

Returns:

a signer.

Return type:

Signer

KeychainSqlite3

This is the default Keychain.

class ndn.security.keychain.keychain_sqlite3.Certificate(row_id, key, name, data, is_default)

A dataclass for a Certificate.

Variables:

• id (int) – its id in the database.

• key (FormalName) – the Name of the associated Key.

• name (FormalName) – its Name.

• data (bytes) – the content.

• is_default (bool) – whether this is the default Identity.

property data: bytes | bytearray | memoryview

Get the binary data of the certificate, which is the wire form of the V2 certificate Data packet.

Returns:

Certificate binary data.

property key: List[bytes | bytearray | memoryview]

Get the Name of the Key

Returns:

Key Name.

property name: List[bytes | bytearray | memoryview]

Get the Name of the certificate

Returns:

Certificate Name.

class ndn.security.keychain.keychain_sqlite3.Identity(pib, row_id, name, is_default)

An Identity. It behaves like an immutable dict from FormalName to Key.

Variables:

• row_id (int) – its id in the database.

• name (FormalName) – its Name.

• is_default (bool) – whether this is the default Identity.

default_key()

Get the default Key.

Return type:

Key

Returns:

the default Key.

del_key(name)

Delete a specific Key.

Parameters:

name (NonStrictName) – the Name of the Key to delete.

has_default_key()

Whether it has a default Key.

Return type:

bool

Returns:

True if there is one.

property name: List[bytes | bytearray | memoryview]

Get the Name of the identity

Returns:

Identity Name.

new_key(key_type)

Create a new key with default arguments.

Parameters:

key_type (str) – the type of the Key. Can be ec or rsa.

Return type:

Key

Returns:

the new Key.

set_default_key(name)

Set the default Key.

Parameters:

name (NonStrictName) – the Name of the new default Key.

class ndn.security.keychain.keychain_sqlite3.Key(pib, identity, row_id, name, key_bits, is_default)

A Key. It behaves like an immutable dict from FormalName to Certificate.

Variables:

• row_id (int) – its id in the database.

• identity (FormalName.) – the Name of the associated Identity.

• name (FormalName) – its Name.

• key_bits (bytes) – the key bits of the public key.

• is_default (bool) – whether this is the default Identity.

default_cert()

Get the default Certificate.

Return type:

Certificate

Returns:

the default Certificate.

del_cert(name)

Delete a specific Certificare.

Parameters:

name (NonStrictName) – the Name of the Key to delete.

has_default_cert()

Whether it has a default Certificate.

Return type:

bool

Returns:

True if there is one.

property identity: List[bytes | bytearray | memoryview]

Get the Name of the Identity

Returns:

Identity Name.

property key_bits: bytes | bytearray | memoryview

Get the public key bits of the key.

Returns:

Public key bits.

property name: List[bytes | bytearray | memoryview]

Get the Name of the key

Returns:

Key Name.

set_default_cert(name)

Set the default Certificate.

Parameters:

name (NonStrictName) – the Name of the new default Certificate.

class ndn.security.keychain.keychain_sqlite3.KeychainSqlite3(path, tpm)

Store public infomation in a Sqlite3 database and private keys in a TPM.

Variables:

• path (str) – the path to the database. The default path is ~/.ndn/pib.db.

• tpm (Tpm) – an instance of TPM.

• tpm_locator (str) – a URI string describing the location of TPM.

default_identity()

Get the default Identity.

Return type:

Identity

Returns:

the default Identity.

del_cert(name)

Delete a specific Certificate.

Parameters:

name (NonStrictName) – the Certificate Name.

del_identity(name)

Delete a specific Identity.

Parameters:

name (NonStrictName) – the Identity Name.

del_key(name)

Delete a specific Key.

Parameters:

name (NonStrictName) – the Key Name.

get_signer(sign_args)

Get a signer from sign_args.

Parameters:

sign_args (dict[str, Any]) – the signing arguments provided by the application.

Returns:

a signer.

Return type:

Signer

has_default_identity()

Whether there is a default Identity. :rtype: bool :return: True if there is one.

new_identity(name)

Create a new Identity without a default Key. This is used to control the Keychain in a fine-grained way.

Parameters:

name (NonStrictName) – the Name of the new Identity.

Return type:

Identity

Returns:

the Identity created.

new_key(id_name, key_type='ec', **kwargs)

Generate a new key for a specific Identity.

Parameters:

• id_name (NonStrictName) – the Name of Identity.

• key_type (str) –

  the type of key. Can be one of the following:

  • ec: ECDSA key.

  • rsa: RSA key.

• kwargs – keyword arguments.

Keyword Arguments:

• key_size (int) - key size in bit.

• key_id (Union[BinaryStr, str]) - a one-Component ID of the Key.

• key_id_type (str) - the method to generate the ID if key_id is not specified. Can be random or sha256.

Return type:

Key

Returns:

the new Key.

set_default_identity(name)

Set the default Identity.

Parameters:

name (NonStrictName) – the Name of the new default Identity.

shutdown()

Close the connection.

touch_identity(id_name)

Get an Identity with specific name. Create a new one if it does not exist. The newly created one will automatically have a default ECC Key and self-signed Certificate.

Parameters:

id_name (NonStrictName) – the Name of Identity.

Return type:

Identity

Returns:

the specified Identity.