Class desfire::any_key

Defined in File keys.hpp

Inheritance Relationships

Base Type

public mlab::any_of< cipher_type, key, cipher_type::none >

Class Documentation

class any_key : public mlab::any_of<cipher_type, key, cipher_type::none>

Type-erased class that holds a key of any cipher type.

Rule of five.

Copy-constructors have to be manually implemented for mlab::any_of.

any_key(any_key const &other)

any_key &operator=(any_key const &other)

any_key(any_key &&other) noexcept = default

any_key &operator=(any_key &&other) noexcept = default

Public Functions

any_key() = default: Default-constructs an empty key with cipher_type::none.

template<cipher_type Cipher> any_key(key<Cipher> obj)

Converts implicitly a strongly typed key of a given type to a type-erased any_key.

Template Parameters:: Cipher – Cipher of the key
Parameters:: obj – Key instance (moved into the instance).

explicit any_key(cipher_type cipher)

Constructs key number 0, with the key body set to all zeroes, of the given cipher type.

Parameters:: cipher – Cipher type for which to construct the key.

any_key(cipher_type cipher, mlab::range<std::uint8_t const*> k, std::uint8_t key_no = 0)

Constructs a key of the given cipher, using the body specified in k and the key number key_no.

Parameters:

cipher – cipher Cipher type for which to construct the key.
k – Key body. This must be a preallocated buffer of the appropriate size for the key. If it is smaller, the rest of the body is filled with zeroes.
key_no – Number of the key, in the range 0..13 (included).

any_key(cipher_type cipher, mlab::range<std::uint8_t const*> k, std::uint8_t key_no, std::uint8_t v)

Constructs a key of the given cipher, using the body specified in k and the key number key_no. Subsequently, applies the version v.

Parameters:

cipher – cipher Cipher type for which to construct the key.
k – Key body. This must be a preallocated buffer of the appropriate size for the key. If it is smaller, the rest of the body is filled with zeroes.
key_no – Number of the key, in the range 0..13 (included).
v – Key version.

any_key(cipher_type cipher, random_oracle rng, std::uint8_t key_no = 0)

Constructs a random key of the given cipher, using the given random number generator and the key number key_no.

Parameters:

cipher – cipher Cipher type for which to construct the key.
rng – Random number generator function to use for filling the key body.
key_no – Number of the key, in the range 0..13 (included).

any_key(cipher_type cipher, random_oracle rng, std::uint8_t key_no, std::uint8_t v)

Constructs a random key of the given cipher, using the given random number generator and the key number key_no. Subsequently, applies the version v.

Parameters:

cipher – cipher Cipher type for which to construct the key.
rng – Random number generator function to use for filling the key body.
key_no – Number of the key, in the range 0..13 (included).
v – Key version.

std::uint8_t key_number() const

Key number of the key.

Returns:: A number in the range 0..13 (included).

std::uint8_t version() const

Version of the key. DES-based keys encode the version in the key body, while AES128 keys store that separately.

Returns:: A number in the range 0..255 (included).

mlab::range<std::uint8_t const*> body() const

Returns a data range holding the key body.

Returns:: A pair of iterators, which yield a zero-length sequence if the key has cipher_type::none.

void set_key_number(std::uint8_t v)

Changes the key number to v.

Parameters:: v – A number in the range 0..13 (included).

void set_version(std::uint8_t v)

Changes the key version to v. DES-based keys encode the version in the key body, while AES128 keys store that separately.

Parameters:: v – A byte.

void set_body(mlab::range<std::uint8_t const*> k)

Changes the key body.

Note

For DES keys, this will change the key version. The rationale is that the incoming data is from a known key, therefore it is ok to carry on the version. If you are generating a random key, use randomize.

Parameters:: k – Key body, it will be copied. This must be a preallocated buffer of the appropriate size for the key. If it is smaller, the rest of the body is filled with zeroes.

void randomize(random_oracle rng)

Randomizes the key without changing its type.

Note

This does not change the key version.

Parameters:: rng – Random number generator function to use for filling the key body.

any_key with_key_number(std::uint8_t key_no) const

Copies the same key but changes the key_number.

Parameters:: key_no – Number of the key, in the range 0..13 (included).
Returns:: An identical key, with different key_number.

std::size_t size() const: Size in bytes of the key. Does not account for the fact that DES key in Desfire cards are stored as 16 bytes, that is, will return 8 for a DES key. Also does not count the version byte for AES128 keys, i.e. for AES it will return 16.

bool parity_bits_are_version() const

Does this key store the version into the parity (LSB) bits of the key body? True only for DES-based keys.

Returns:: True if the LSB bits of the body include the version.

bin_data get_packed_key_body() const: Returns a copy of the key body as used in authentication procedures.

Note

DES keys are 2K3DES keys with two identical halves. Does not include version for keys that do not have parity_bits_are_version.

bin_data xored_with(any_key const &key_to_xor_with) const

XOR-s together the get_packed_key_body of this instance and key_to_xor_with (includes version). For AES128 keys, where parity_bits_are_version returns false, the key version is appended at the end and is excluded from the xoring process.

Parameters:: key_to_xor_with – Key for which to extract the body in order to XOR it with this instance.
Returns:: The result of get_packed_key_body, XOR-ed with key_to_xor_with and with a version byte appended if necessary.

bool operator==(any_key const &other) const: Two keys are equal iff they have same cipher type, version and key body.

bool operator!=(any_key const &other) const: Two keys are equal iff they have same cipher type, version and key body.