Represents an NDN certificate. More...

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

Inheritance diagram for ndn::security::Certificate:

Collaboration diagram for ndn::security::Certificate:

Classes
class	Error

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 noexcept
	Return the value of `ContentType`. More...

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

const std::optional< name::Component > &	getFinalBlock () const noexcept
	Return the value of `FinalBlockId`. More...

time::milliseconds	getFreshnessPeriod () const noexcept
	Return the value of `FreshnessPeriod`. More...

const Name &	getFullName () const
	Get the 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...

std::optional< KeyLocator >	getKeyLocator () const noexcept
	Get the `KeyLocator` element. More...

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

const MetaInfo &	getMetaInfo () const noexcept
	Get the `MetaInfo` element. More...

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

span< const uint8_t >	getPublicKey () const noexcept
	Return the public key as a DER-encoded SubjectPublicKeyInfo structure, i.e., exactly as it appears in the serialized certificate. More...

const SignatureInfo &	getSignatureInfo () const noexcept
	Get the `SignatureInfo` element. More...

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

const Block &	getSignatureValue () const noexcept
	Get the `SignatureValue` element. More...

template<typename T >
std::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::time_point &ts=time::system_clock::now()) const
	Check if the certificate is valid at `ts`. More...

template<typename T >
void	removeTag () const
	Remove a 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 (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 &	setContent (std::nullptr_t)=delete

Data &	setContent (std::string_view value)
	Set `Content` by copying from a string. More...

Data &	setContentType (uint32_t type)
	Set the `ContentType`. More...

Data &	setFinalBlock (std::optional< name::Component > finalBlockId)
	Set the `FinalBlockId`. More...

Data &	setFreshnessPeriod (time::milliseconds freshnessPeriod)
	Set the `FreshnessPeriod`. More...

Data &	setMetaInfo (const MetaInfo &metaInfo)
	Set the `MetaInfo` element. More...

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

Data &	setSignatureInfo (const SignatureInfo &info)
	Set the `SignatureInfo` element. More...

Data &	setSignatureValue (ConstBufferPtr value)
	Set `SignatureValue` from a shared buffer. More...

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

Data &	setSignatureValue (std::nullptr_t)=delete

template<typename T >
void	setTag (std::shared_ptr< T > tag) const
	Set (add or replace) 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 respects the naming conventions for certificates. More...

Static Public Attributes
static const name::Component	DEFAULT_ISSUER_ID {"NA"}

static constexpr ssize_t	ISSUER_ID_OFFSET = -2

static const name::Component	KEY_COMPONENT {"KEY"}

static constexpr ssize_t	KEY_COMPONENT_OFFSET = -4

static constexpr ssize_t	KEY_ID_OFFSET = -3

static constexpr size_t	MIN_CERT_NAME_LENGTH = 4

static constexpr size_t	MIN_KEY_NAME_LENGTH = 2

static constexpr ssize_t	VERSION_OFFSET = -1

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

Detailed Description

Represents an NDN certificate.

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

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 the 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: https://docs.named-data.net/NDN-packet-spec/0.3/certificate.html

Definition at line 57 of file certificate.hpp.

Constructor & Destructor Documentation

◆ Certificate() [1/4]

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

Definition at line 35 of file certificate.cpp.

◆ Certificate() [2/4]

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

explicit

Construct certificate from a data object.

Exceptions

tlv::Error if data does not follow certificate format

Definition at line 41 of file certificate.cpp.

◆ Certificate() [3/4]

ndn::security::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 55 of file certificate.cpp.

◆ Certificate() [4/4]

ndn::security::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 60 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 323 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_bytes(), or
Block::value() and Block::value_size(), or
Block::value_begin() and Block::value_end().

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

Definition at line 188 of file data.hpp.

◆ getContentType()

uint32_t ndn::Data::getContentType ( ) const

inlinenoexceptinherited

Return the value of ContentType.

If the ContentType element is not present, returns tlv::ContentType_Blob.

Definition at line 312 of file data.hpp.

◆ getExtension()

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

Get extension with TLV type.

Exceptions

Error The specified block type does not exist

Definition at line 102 of file certificate.cpp.

◆ getFinalBlock()

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

inlinenoexceptinherited

Return the value of FinalBlockId.

Definition at line 342 of file data.hpp.

◆ getFreshnessPeriod()

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

inlinenoexceptinherited

Return the value of FreshnessPeriod.

If the FreshnessPeriod element is not present, returns DEFAULT_FRESHNESS_PERIOD. If the FreshnessPeriod value is not representable in the return type, it's clamped to the nearest representable value.

Definition at line 327 of file data.hpp.

◆ getFullName()

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

inherited

Get the 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 200 of file data.cpp.

◆ getIdentity()

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

Get identity name.

Definition at line 66 of file certificate.cpp.

◆ getIssuerId()

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

Get issuer ID.

Definition at line 84 of file certificate.cpp.

◆ getKeyId()

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

Get key ID.

Definition at line 78 of file certificate.cpp.

◆ getKeyLocator()

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

inlinenoexceptinherited

Get the KeyLocator element.

Definition at line 367 of file data.hpp.

◆ getKeyName()

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

Get key name.

Definition at line 72 of file certificate.cpp.

◆ getMetaInfo()

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

inlinenoexceptinherited

Get the MetaInfo element.

Definition at line 153 of file data.hpp.

◆ getName()

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

inlinenoexceptinherited

Get the Data name.

Definition at line 137 of file data.hpp.

◆ getPublicKey()

span<const uint8_t> ndn::security::Certificate::getPublicKey ( ) const

inlinenoexcept

Return the public key as a DER-encoded SubjectPublicKeyInfo structure, i.e., exactly as it appears in the serialized certificate.

Definition at line 118 of file certificate.hpp.

◆ getSignatureInfo()

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

inlinenoexceptinherited

Get the SignatureInfo element.

Definition at line 243 of file data.hpp.

◆ getSignatureType()

int32_t ndn::Data::getSignatureType ( ) const

inlinenoexceptinherited

Get the SignatureType.

Returns: tlv::SignatureTypeValue, or -1 to indicate an invalid SignatureInfo.

Definition at line 358 of file data.hpp.

◆ getSignatureValue()

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

inlinenoexceptinherited

Get the SignatureValue element.

Definition at line 265 of file data.hpp.

◆ getTag()

template<typename T >

std::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 72 of file tag-host.hpp.

◆ getValidityPeriod()

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

Get validity period of the certificate.

Definition at line 90 of file certificate.cpp.

◆ hasContent()

bool ndn::Data::hasContent ( ) const

inlinenoexceptinherited

Return whether this Data has a Content element.

Definition at line 169 of file data.hpp.

◆ hasWire()

bool ndn::Data::hasWire ( ) const

inlinenoexceptinherited

Check if this instance has cached wire encoding.

Definition at line 119 of file data.hpp.

◆ isValid()

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

Check if the certificate is valid at ts.

Definition at line 96 of file certificate.cpp.

◆ isValidName()

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

static

Check if the specified name respects the naming conventions for certificates.

Definition at line 112 of file certificate.cpp.

◆ removeTag()

template<typename T >

void ndn::TagHost::removeTag

inherited

Remove a tag item.

Template Parameters

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

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

Definition at line 98 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 214 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/5]

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

inherited

Set Content from a Block.

Parameters

block TLV element 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 239 of file data.cpp.

◆ setContent() [2/5]

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 null

Returns: A reference to this Data, to allow chaining.

Definition at line 273 of file data.cpp.

◆ setContent() [3/5]

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 257 of file data.cpp.

◆ setContent() [4/5]

Data& ndn::Data::setContent ( std::nullptr_t )

deleteinherited

◆ setContent() [5/5]

Data & ndn::Data::setContent ( std::string_view value )

inherited

Set Content by copying from a string.

Parameters

value string with the TLV-VALUE of the content

Returns: A reference to this Data, to allow chaining.

Definition at line 265 of file data.cpp.

◆ setContentType()

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

inherited

Set the ContentType.

Parameters

type	A number defined in tlv::ContentTypeValue

Definition at line 337 of file data.cpp.

◆ setFinalBlock()

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

inherited

Set the FinalBlockId.

Definition at line 357 of file data.cpp.

◆ setFreshnessPeriod()

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

inherited

Set the FreshnessPeriod.

Exceptions

std::invalid_argument specified FreshnessPeriod is negative.

Definition at line 347 of file data.cpp.

◆ setMetaInfo()

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

inherited

Set the MetaInfo element.

Returns: A reference to this Data, to allow chaining.

Definition at line 231 of file data.cpp.

◆ setName()

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

inherited

Set the Data name.

Returns: A reference to this Data, to allow chaining.

Definition at line 221 of file data.cpp.

◆ setSignatureInfo()

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

inherited

Set the SignatureInfo element.

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 295 of file data.cpp.

◆ setSignatureValue() [1/3]

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

inherited

Set SignatureValue from a shared buffer.

Parameters

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

Returns: A reference to this Data, to allow chaining.

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

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

Definition at line 311 of file data.cpp.

◆ setSignatureValue() [2/3]

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

inherited

Set SignatureValue by copying from a contiguous sequence of bytes.

Parameters

value buffer from which the TLV-VALUE of the SignatureValue will be copied

Returns: A reference to this Data, to allow chaining.

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

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

Definition at line 303 of file data.cpp.

◆ setSignatureValue() [3/3]

Data& ndn::Data::setSignatureValue ( std::nullptr_t )

deleteinherited

◆ setTag()

template<typename T >

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

inherited

Set (add or replace) 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 84 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 285 of file data.cpp.

◆ wireDecode()

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

inherited

Decode from wire.

Definition at line 118 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 102 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 87 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 39 of file data.cpp.

Member Data Documentation

◆ DEFAULT_ISSUER_ID

const name::Component ndn::security::Certificate::DEFAULT_ISSUER_ID {"NA"}

inlinestatic

Definition at line 159 of file certificate.hpp.

◆ ISSUER_ID_OFFSET

constexpr ssize_t ndn::security::Certificate::ISSUER_ID_OFFSET = -2

staticconstexpr

Definition at line 153 of file certificate.hpp.

◆ KEY_COMPONENT

const name::Component ndn::security::Certificate::KEY_COMPONENT {"KEY"}

inlinestatic

Definition at line 158 of file certificate.hpp.

◆ KEY_COMPONENT_OFFSET

constexpr ssize_t ndn::security::Certificate::KEY_COMPONENT_OFFSET = -4

staticconstexpr

Definition at line 155 of file certificate.hpp.

◆ KEY_ID_OFFSET

constexpr ssize_t ndn::security::Certificate::KEY_ID_OFFSET = -3

staticconstexpr

Definition at line 154 of file certificate.hpp.

◆ MIN_CERT_NAME_LENGTH

constexpr size_t ndn::security::Certificate::MIN_CERT_NAME_LENGTH = 4

staticconstexpr

Definition at line 156 of file certificate.hpp.

◆ MIN_KEY_NAME_LENGTH

constexpr size_t ndn::security::Certificate::MIN_KEY_NAME_LENGTH = 2

staticconstexpr

Definition at line 157 of file certificate.hpp.

◆ VERSION_OFFSET

constexpr ssize_t ndn::security::Certificate::VERSION_OFFSET = -1

staticconstexpr

Definition at line 152 of file certificate.hpp.

ndn-cxx: NDN C++ library with eXperimental eXtensions 0.8.1-102-g0751bba8 documentation

Classes

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/5]

◆ setContent() [2/5]

◆ setContent() [3/5]

◆ setContent() [4/5]

◆ setContent() [5/5]

◆ setContentType()

◆ setFinalBlock()

◆ setFreshnessPeriod()

◆ setMetaInfo()

◆ setName()

◆ setSignatureInfo()

◆ setSignatureValue() [1/3]

◆ setSignatureValue() [2/3]

◆ setSignatureValue() [3/3]

◆ setTag()

◆ unsetContent()

◆ wireDecode()

◆ wireEncode() [1/3]

◆ wireEncode() [2/3]

◆ wireEncode() [3/3]

Member Data Documentation

◆ DEFAULT_ISSUER_ID

◆ ISSUER_ID_OFFSET

◆ KEY_COMPONENT

◆ KEY_COMPONENT_OFFSET

◆ KEY_ID_OFFSET

◆ MIN_CERT_NAME_LENGTH

◆ MIN_KEY_NAME_LENGTH

◆ VERSION_OFFSET