Represents an NDN certificate following the version 2.0 format. More...

#include <ndn-cxx/security/certificate.hpp>

Inheritance diagram for ndn::security::v2::Certificate:

Collaboration diagram for ndn::security::v2::Certificate:

Public Member Functions
	Certificate ()

	Certificate (const Block &block)
	Construct certificate from a wire encoding. More...

	Certificate (const Data &data)
	Construct certificate from a data object. More...

	Certificate (Data &&data)
	Construct certificate from a data object. More...

InputBuffers	extractSignedRanges () const
	Extract ranges of Data covered by the signature. More...

uint64_t	getCongestionMark () const
	get the value of the CongestionMark tag More...

const Block &	getContent () const noexcept
	Get the Content element. More...

uint32_t	getContentType () const

Block	getExtension (uint32_t type) const
	Get extension with TLV `type`. More...

const optional< name::Component > &	getFinalBlock () const

time::milliseconds	getFreshnessPeriod () const

const Name &	getFullName () const
	Get full name including implicit digest. More...

Name	getIdentity () const
	Get identity name. More...

name::Component	getIssuerId () const
	Get issuer ID. More...

name::Component	getKeyId () const
	Get key ID. More...

optional< KeyLocator >	getKeyLocator () const noexcept
	Get KeyLocator. More...

Name	getKeyName () const
	Get key name. More...

const MetaInfo &	getMetaInfo () const noexcept
	Get MetaInfo. More...

const Name &	getName () const noexcept
	Get name. More...

Buffer	getPublicKey () const
	Get public key bits (in PKCS#8 format) More...

const SignatureInfo &	getSignatureInfo () const noexcept
	Get SignatureInfo. More...

int32_t	getSignatureType () const noexcept
	Get SignatureType. More...

const Block &	getSignatureValue () const noexcept
	Get SignatureValue. More...

template<typename T >
shared_ptr< T >	getTag () const
	get a tag item More...

ValidityPeriod	getValidityPeriod () const
	Get validity period of the certificate. More...

bool	hasContent () const noexcept
	Return whether this Data has a Content element. More...

bool	hasWire () const noexcept
	Check if this instance has cached wire encoding. More...

bool	isValid (const time::system_clock::TimePoint &ts=time::system_clock::now()) const
	Check if the certificate is valid at `ts`. More...

template<typename T >
void	removeTag () const
	remove tag item More...

void	setCongestionMark (uint64_t mark)
	set the CongestionMark tag to the specified value More...

Data &	setContent (const Block &block)
	Set Content from a Block. More...

Data &	setContent (const uint8_t *value, size_t length)
	Set Content by copying from a raw buffer. More...

Data &	setContent (ConstBufferPtr value)
	Set Content from a shared buffer. More...

Data &	setContent (span< const uint8_t > value)
	Set Content by copying from a contiguous sequence of bytes. More...

Data &	setContentType (uint32_t type)

Data &	setFinalBlock (optional< name::Component > finalBlockId)

Data &	setFreshnessPeriod (time::milliseconds freshnessPeriod)

Data &	setMetaInfo (const MetaInfo &metaInfo)
	Set MetaInfo. More...

Data &	setName (const Name &name)
	Set name. More...

Data &	setSignatureInfo (const SignatureInfo &info)
	Set SignatureInfo. More...

Data &	setSignatureValue (ConstBufferPtr value)
	Set SignatureValue. More...

template<typename T >
void	setTag (shared_ptr< T > tag) const
	set a tag item More...

Data &	unsetContent ()
	Remove the Content element. More...

void	wireDecode (const Block &wire)
	Decode from `wire`. More...

const Block &	wireEncode () const
	Encode into a Block. More...

const Block &	wireEncode (EncodingBuffer &encoder, span< const uint8_t > signature) const
	Finalize Data packet encoding with the specified signature. More...

template<encoding::Tag TAG>
size_t	wireEncode (EncodingImpl< TAG > &encoder, bool wantUnsignedPortionOnly=false) const
	Prepend wire encoding to `encoder`. More...

Static Public Member Functions
static bool	isValidName (const Name &certName)
	Check if the specified name follows the naming convention for the certificate. More...

Static Public Attributes
static const ssize_t	ISSUER_ID_OFFSET = -2

static const name::Component	KEY_COMPONENT

static const ssize_t	KEY_COMPONENT_OFFSET = -4

static const ssize_t	KEY_ID_OFFSET = -3

static const size_t	MIN_CERT_NAME_LENGTH = 4

static const size_t	MIN_KEY_NAME_LENGTH = 2

static const ssize_t	VERSION_OFFSET = -1

Protected Member Functions
void	resetWire ()
	Clear wire encoding and cached FullName. More...

Detailed Description

Represents an NDN certificate following the version 2.0 format.

Example of an NDN certificate name:

/edu/ucla/cs/yingdi/KEY/%03%CD...%F1/%9F%D3...%B7/v=1617592200702
\_________________/    \___________/\___________/\______________/
   Identity Name           KeyId      IssuerId       Version
\__________________________________/
              Key Name

Notes:

KeyId is an opaque name component to identify an instance of the public key for the certificate namespace. The value of KeyId is controlled by the namespace owner. The library includes helpers for generation of key IDs using 8-byte random number, SHA-256 digest of the public key, timestamp, or a specified numerical identifier.
IssuerId is an opaque name component to identify the issuer of the certificate. The value is controlled by the issuer. The library includes helpers to set issuer ID to a 8-byte random number, SHA-256 digest of the issuer's public key, or a specified numerical identifier.
Key Name is a logical name of the key used for management purposes. The key name includes the identity name, the keyword KEY, and the KeyId component.

See also: doc/specs/certificate.rst

Definition at line 60 of file certificate.hpp.

Constructor & Destructor Documentation

◆ Certificate() [1/4]

ndn::security::v2::Certificate::Certificate ( )

Definition at line 48 of file certificate.cpp.

◆ Certificate() [2/4]

ndn::security::v2::Certificate::Certificate ( Data && data )

explicit

Construct certificate from a data object.

Exceptions

tlv::Error if data does not follow certificate format

Definition at line 53 of file certificate.cpp.

◆ Certificate() [3/4]

ndn::security::v2::Certificate::Certificate ( const Data & data )

explicit

Construct certificate from a data object.

Exceptions

tlv::Error if data does not follow certificate format

Definition at line 70 of file certificate.cpp.

◆ Certificate() [4/4]

ndn::security::v2::Certificate::Certificate ( const Block & block )

explicit

Construct certificate from a wire encoding.

Exceptions

tlv::Error if wire encoding is invalid or does not follow certificate format

Definition at line 75 of file certificate.cpp.

Member Function Documentation

◆ extractSignedRanges()

InputBuffers ndn::Data::extractSignedRanges ( ) const

inherited

Extract ranges of Data covered by the signature.

Exceptions

Error Data cannot be encoded or is missing ranges necessary for signing

Warning: The returned pointers will be invalidated if wireDecode() or wireEncode() are called.

Definition at line 322 of file data.cpp.

◆ getCongestionMark()

uint64_t ndn::PacketBase::getCongestionMark ( ) const

inherited

get the value of the CongestionMark tag

Definition at line 28 of file packet-base.cpp.

◆ getContent()

const Block& ndn::Data::getContent ( ) const

inlinenoexceptinherited

Get the Content element.

If the element is not present (hasContent() == false), an invalid Block will be returned.

The value of the returned Content Block (if valid) can be accessed through Block::value() / Block::value_size() or Block::value_begin() / Block::value_end().

See also: hasContent(); Block::blockFromValue(), Block::parse()

Definition at line 173 of file data.hpp.

◆ getContentType()

uint32_t ndn::Data::getContentType ( ) const

inlineinherited

Definition at line 273 of file data.hpp.

◆ getExtension()

Block ndn::security::v2::Certificate::getExtension ( uint32_t type ) const

Get extension with TLV type.

Exceptions

Error The specified block type does not exist

Definition at line 125 of file certificate.cpp.

◆ getFinalBlock()

const optional<name::Component>& ndn::Data::getFinalBlock ( ) const

inlineinherited

Definition at line 291 of file data.hpp.

◆ getFreshnessPeriod()

time::milliseconds ndn::Data::getFreshnessPeriod ( ) const

inlineinherited

Definition at line 282 of file data.hpp.

◆ getFullName()

const Name & ndn::Data::getFullName ( ) const

inherited

Get full name including implicit digest.

Precondition: hasWire() == true; i.e. wireEncode() must have been called

Exceptions

Error Data has no wire encoding

Definition at line 207 of file data.cpp.

◆ getIdentity()

Name ndn::security::v2::Certificate::getIdentity ( ) const

Get identity name.

Definition at line 87 of file certificate.cpp.

◆ getIssuerId()

name::Component ndn::security::v2::Certificate::getIssuerId ( ) const

Get issuer ID.

Definition at line 99 of file certificate.cpp.

◆ getKeyId()

name::Component ndn::security::v2::Certificate::getKeyId ( ) const

Get key ID.

Definition at line 93 of file certificate.cpp.

◆ getKeyLocator()

optional<KeyLocator> ndn::Data::getKeyLocator ( ) const

inlinenoexceptinherited

Get KeyLocator.

Definition at line 312 of file data.hpp.

◆ getKeyName()

Name ndn::security::v2::Certificate::getKeyName ( ) const

Get key name.

Definition at line 81 of file certificate.cpp.

◆ getMetaInfo()

const MetaInfo& ndn::Data::getMetaInfo ( ) const

inlinenoexceptinherited

Get MetaInfo.

Definition at line 141 of file data.hpp.

◆ getName()

const Name& ndn::Data::getName ( ) const

inlinenoexceptinherited

Get name.

Definition at line 127 of file data.hpp.

◆ getPublicKey()

Buffer ndn::security::v2::Certificate::getPublicKey ( ) const

Get public key bits (in PKCS#8 format)

Exceptions

Error If content is empty

Definition at line 105 of file certificate.cpp.

◆ getSignatureInfo()

const SignatureInfo& ndn::Data::getSignatureInfo ( ) const

inlinenoexceptinherited

Get SignatureInfo.

Definition at line 227 of file data.hpp.

◆ getSignatureType()

int32_t ndn::Data::getSignatureType ( ) const

inlinenoexceptinherited

Get SignatureType.

Returns: tlv::SignatureTypeValue, or -1 to indicate the signature is invalid

Definition at line 304 of file data.hpp.

◆ getSignatureValue()

const Block& ndn::Data::getSignatureValue ( ) const

inlinenoexceptinherited

Get SignatureValue.

Definition at line 247 of file data.hpp.

◆ getTag()

template<typename T >

shared_ptr< T > ndn::TagHost::getTag

inherited

get a tag item

Template Parameters

T	type of the tag, which must be a subclass of ndn::Tag

Return values

nullptr if no Tag of type T is stored

Definition at line 66 of file tag-host.hpp.

◆ getValidityPeriod()

ValidityPeriod ndn::security::v2::Certificate::getValidityPeriod ( ) const

Get validity period of the certificate.

Definition at line 113 of file certificate.cpp.

◆ hasContent()

bool ndn::Data::hasContent ( ) const

inlinenoexceptinherited

Return whether this Data has a Content element.

Definition at line 156 of file data.hpp.

◆ hasWire()

bool ndn::Data::hasWire ( ) const

inlinenoexceptinherited

Check if this instance has cached wire encoding.

Definition at line 111 of file data.hpp.

◆ isValid()

bool ndn::security::v2::Certificate::isValid ( const time::system_clock::TimePoint & ts = time::system_clock::now() ) const

Check if the certificate is valid at ts.

Definition at line 119 of file certificate.cpp.

◆ isValidName()

bool ndn::security::v2::Certificate::isValidName ( const Name & certName )

static

Check if the specified name follows the naming convention for the certificate.

Definition at line 135 of file certificate.cpp.

◆ removeTag()

template<typename T >

void ndn::TagHost::removeTag

inherited

remove tag item

Note: Tag can be removed even on a const tag host instance

Definition at line 93 of file tag-host.hpp.

◆ resetWire()

void ndn::Data::resetWire ( )

protectedinherited

Clear wire encoding and cached FullName.

Note: This does not clear the SignatureValue.

Definition at line 221 of file data.cpp.

◆ setCongestionMark()

void ndn::PacketBase::setCongestionMark ( uint64_t mark )

inherited

set the CongestionMark tag to the specified value

Definition at line 41 of file packet-base.cpp.

◆ setContent() [1/4]

Data & ndn::Data::setContent ( const Block & block )

inherited

Set Content from a Block.

Parameters

block TLV block to be used as Content; must be valid

Returns: a reference to this Data, to allow chaining

If the block's TLV-TYPE is tlv::Content, it will be used directly as this Data's Content element. Otherwise, the block will be nested into a Content element.

Definition at line 246 of file data.cpp.

◆ setContent() [2/4]

Data & ndn::Data::setContent	(	const uint8_t *	value,
		size_t	length
	)

inherited

Set Content by copying from a raw buffer.

Parameters

value	buffer with the TLV-VALUE of the content; may be nullptr if `length` is zero
length	size of the buffer

Returns: a reference to this Data, to allow chaining

Deprecated:: Use setContent(span<const uint8_t>)

Definition at line 272 of file data.cpp.

◆ setContent() [3/4]

Data & ndn::Data::setContent ( ConstBufferPtr value )

inherited

Set Content from a shared buffer.

Parameters

value buffer with the TLV-VALUE of the content; must not be nullptr

Returns: a reference to this Data, to allow chaining

Definition at line 282 of file data.cpp.

◆ setContent() [4/4]

Data & ndn::Data::setContent ( span< const uint8_t > value )

inherited

Set Content by copying from a contiguous sequence of bytes.

Parameters

value buffer with the TLV-VALUE of the content

Returns: a reference to this Data, to allow chaining

Definition at line 264 of file data.cpp.

◆ setContentType()

Data & ndn::Data::setContentType ( uint32_t type )

inherited

Definition at line 336 of file data.cpp.

◆ setFinalBlock()

Data & ndn::Data::setFinalBlock ( optional< name::Component > finalBlockId )

inherited

Definition at line 356 of file data.cpp.

◆ setFreshnessPeriod()

Data & ndn::Data::setFreshnessPeriod ( time::milliseconds freshnessPeriod )

inherited

Definition at line 346 of file data.cpp.

◆ setMetaInfo()

Data & ndn::Data::setMetaInfo ( const MetaInfo & metaInfo )

inherited

Set MetaInfo.

Returns: a reference to this Data, to allow chaining

Definition at line 238 of file data.cpp.

◆ setName()

Data & ndn::Data::setName ( const Name & name )

inherited

Set name.

Returns: a reference to this Data, to allow chaining

Definition at line 228 of file data.cpp.

◆ setSignatureInfo()

Data & ndn::Data::setSignatureInfo ( const SignatureInfo & info )

inherited

Set SignatureInfo.

This is a low-level function that should not normally be called directly by applications. Instead, provide a SignatureInfo to the SigningInfo object passed to KeyChain::sign().

Returns: a reference to this Data, to allow chaining

Warning: SignatureInfo is overwritten when the packet is signed via KeyChain::sign().

See also: SigningInfo

Definition at line 302 of file data.cpp.

◆ setSignatureValue()

Data & ndn::Data::setSignatureValue ( ConstBufferPtr value )

inherited

Set SignatureValue.

Parameters

value buffer containing the TLV-VALUE of the SignatureValue; must not be nullptr

This is a low-level function that should not normally be called directly by applications. Instead, use KeyChain::sign() to sign the packet.

Returns: a reference to this Data, to allow chaining

Warning: SignatureValue is overwritten when the packet is signed via KeyChain::sign().

Definition at line 310 of file data.cpp.

◆ setTag()

template<typename T >

void ndn::TagHost::setTag ( shared_ptr< T > tag ) const

inherited

set a tag item

Template Parameters

T	type of the tag, which must be a subclass of ndn::Tag

Note: Tag can be set even on a const tag host instance

Definition at line 79 of file tag-host.hpp.

◆ unsetContent()

Data & ndn::Data::unsetContent ( )

inherited

Remove the Content element.

Returns: a reference to this Data, to allow chaining

Postcondition: hasContent() == false

Definition at line 294 of file data.cpp.

◆ wireDecode()

void ndn::Data::wireDecode ( const Block & wire )

inherited

Decode from wire.

Definition at line 125 of file data.cpp.

◆ wireEncode() [1/3]

const Block & ndn::Data::wireEncode ( ) const

inherited

Encode into a Block.

Precondition: Data must be signed.

Definition at line 109 of file data.cpp.

◆ wireEncode() [2/3]

const Block & ndn::Data::wireEncode	(	EncodingBuffer &	encoder,
		span< const uint8_t >	signature
	)		const

inherited

Finalize Data packet encoding with the specified signature.

Parameters

encoder	EncodingBuffer containing Name, MetaInfo, Content, and SignatureInfo, but without SignatureValue and the outermost Type-Length of the Data element.
signature	Raw signature bytes, without TLV Type and Length; this will become the TLV-VALUE of the SignatureValue element added to the packet.

This method is intended to be used in concert with wireEncode(encoder, true), e.g.:

Data data;
...
EncodingBuffer encoder;
data.wireEncode(encoder, true);
...
auto signature = create_signature_over_signed_portion(encoder.data(), encoder.size());
data.wireEncode(encoder, signature);

Definition at line 94 of file data.cpp.

◆ wireEncode() [3/3]

template<encoding::Tag TAG>

size_t ndn::Data::wireEncode	(	EncodingImpl< TAG > &	encoder,
		bool	wantUnsignedPortionOnly = `false`
	)		const

inherited

Prepend wire encoding to encoder.

Parameters

encoder	EncodingEstimator or EncodingBuffer instance.
wantUnsignedPortionOnly	If true, prepend only Name, MetaInfo, Content, and SignatureInfo to `encoder`, but omit SignatureValue and the outermost TLV Type and Length of the Data element. This is intended to be used with wireEncode(EncodingBuffer&, span<const uint8_t>) const.

Exceptions

Error Signature is not present and wantUnsignedPortionOnly is false.

Definition at line 46 of file data.cpp.

Member Data Documentation

◆ ISSUER_ID_OFFSET

const ssize_t ndn::security::v2::Certificate::ISSUER_ID_OFFSET = -2

static

Definition at line 146 of file certificate.hpp.

◆ KEY_COMPONENT

const name::Component ndn::security::v2::Certificate::KEY_COMPONENT

static

Definition at line 151 of file certificate.hpp.

◆ KEY_COMPONENT_OFFSET

const ssize_t ndn::security::v2::Certificate::KEY_COMPONENT_OFFSET = -4

static

Definition at line 147 of file certificate.hpp.

◆ KEY_ID_OFFSET

const ssize_t ndn::security::v2::Certificate::KEY_ID_OFFSET = -3

static

Definition at line 148 of file certificate.hpp.

◆ MIN_CERT_NAME_LENGTH

const size_t ndn::security::v2::Certificate::MIN_CERT_NAME_LENGTH = 4

static

Definition at line 149 of file certificate.hpp.

◆ MIN_KEY_NAME_LENGTH

const size_t ndn::security::v2::Certificate::MIN_KEY_NAME_LENGTH = 2

static

Definition at line 150 of file certificate.hpp.

◆ VERSION_OFFSET

const ssize_t ndn::security::v2::Certificate::VERSION_OFFSET = -1

static

Definition at line 145 of file certificate.hpp.

ndn-cxx: NDN C++ library with eXperimental eXtensions 0.8.0 documentation

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Certificate() [1/4]

◆ Certificate() [2/4]

◆ Certificate() [3/4]

◆ Certificate() [4/4]

Member Function Documentation

◆ extractSignedRanges()

◆ getCongestionMark()

◆ getContent()

◆ getContentType()

◆ getExtension()

◆ getFinalBlock()

◆ getFreshnessPeriod()

◆ getFullName()

◆ getIdentity()

◆ getIssuerId()

◆ getKeyId()

◆ getKeyLocator()

◆ getKeyName()

◆ getMetaInfo()

◆ getName()

◆ getPublicKey()

◆ getSignatureInfo()

◆ getSignatureType()

◆ getSignatureValue()

◆ getTag()

◆ getValidityPeriod()

◆ hasContent()

◆ hasWire()

◆ isValid()

◆ isValidName()

◆ removeTag()

◆ resetWire()

◆ setCongestionMark()

◆ setContent() [1/4]

◆ setContent() [2/4]

◆ setContent() [3/4]

◆ setContent() [4/4]

◆ setContentType()

◆ setFinalBlock()

◆ setFreshnessPeriod()

◆ setMetaInfo()

◆ setName()

◆ setSignatureInfo()

◆ setSignatureValue()

◆ setTag()

◆ unsetContent()

◆ wireDecode()

◆ wireEncode() [1/3]

◆ wireEncode() [2/3]

◆ wireEncode() [3/3]

Member Data Documentation

◆ ISSUER_ID_OFFSET

◆ KEY_COMPONENT

◆ KEY_COMPONENT_OFFSET

◆ KEY_ID_OFFSET

◆ MIN_CERT_NAME_LENGTH

◆ MIN_KEY_NAME_LENGTH

◆ VERSION_OFFSET