Struct KEY

pub struct KEY { /* private fields */ }

Available on crate feature dnssec only.

RFC 2535, Domain Name System Security Extensions, March 1999

3. The KEY Resource Record

   The KEY resource record (RR) is used to store a public key that is
   associated with a Domain Name System (DNS) name.  This can be the
   public key of a zone, a user, or a host or other end entity. Security
   aware DNS implementations MUST be designed to handle at least two
   simultaneously valid keys of the same type associated with the same
   name.

   The type number for the KEY RR is 25.

   A KEY RR is, like any other RR, authenticated by a SIG RR.  KEY RRs
   must be signed by a zone level key.

3.1 KEY RDATA format

   The RDATA for a KEY RR consists of flags, a protocol octet, the
   algorithm number octet, and the public key itself.  The format is as
   follows:

                        1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 3 3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |             flags             |    protocol   |   algorithm   |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                                                               /
   /                          public key                           /
   /                                                               /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-|

   The KEY RR is not intended for storage of certificates and a separate
   certificate RR has been developed for that purpose, defined in [RFC
   2538].

   The meaning of the KEY RR owner name, flags, and protocol octet are
   described in Sections 3.1.1 through 3.1.5 below.  The flags and
   algorithm must be examined before any data following the algorithm
   octet as they control the existence and format of any following data.
   The algorithm and public key fields are described in Section 3.2.
   The format of the public key is algorithm dependent.

   KEY RRs do not specify their validity period but their authenticating
   SIG RR(s) do as described in Section 4 below.

3.1.1 Object Types, DNS Names, and Keys

   The public key in a KEY RR is for the object named in the owner name.

   A DNS name may refer to three different categories of things.  For
   example, foo.host.example could be (1) a zone, (2) a host or other
   end entity , or (3) the mapping into a DNS name of the user or
   account foo@host.example.  Thus, there are flag bits, as described
   below, in the KEY RR to indicate with which of these roles the owner
   name and public key are associated.  Note that an appropriate zone
   KEY RR MUST occur at the apex node of a secure zone and zone KEY RRs
   occur only at delegation points.

3.1.2 The KEY RR Flag Field

   In the "flags" field:

     0   1   2   3   4   5   6   7   8   9   0   1   2   3   4   5
   +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
   |  A/C  | Z | XT| Z | Z | NAMTYP| Z | Z | Z | Z |      SIG      |
   +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+

   Bit 0 and 1 are the key "type" bits whose values have the following
   meanings:

           10: Use of the key is prohibited for authentication.
           01: Use of the key is prohibited for confidentiality.
           00: Use of the key for authentication and/or confidentiality
               is permitted. Note that DNS security makes use of keys
               for authentication only. Confidentiality use flagging is
               provided for use of keys in other protocols.
               Implementations not intended to support key distribution
               for confidentiality MAY require that the confidentiality
               use prohibited bit be on for keys they serve.
           11: If both bits are one, the "no key" value, there is no key
               information and the RR stops after the algorithm octet.
               By the use of this "no key" value, a signed KEY RR can
               authentically assert that, for example, a zone is not
               secured.  See section 3.4 below.

   Bits 2 is reserved and must be zero.

   Bits 3 is reserved as a flag extension bit.  If it is a one, a second
          16 bit flag field is added after the algorithm octet and
          before the key data.  This bit MUST NOT be set unless one or
          more such additional bits have been defined and are non-zero.

   Bits 4-5 are reserved and must be zero.

   Bits 6 and 7 form a field that encodes the name type. Field values
   have the following meanings:

           00: indicates that this is a key associated with a "user" or
               "account" at an end entity, usually a host.  The coding
               of the owner name is that used for the responsible
               individual mailbox in the SOA and RP RRs: The owner name
               is the user name as the name of a node under the entity
               name.  For example, "j_random_user" on
               host.subdomain.example could have a public key associated
               through a KEY RR with name
               j_random_user.host.subdomain.example.  It could be used
               in a security protocol where authentication of a user was
               desired.  This key might be useful in IP or other
               security for a user level service such a telnet, ftp,
               rlogin, etc.
           01: indicates that this is a zone key for the zone whose name
               is the KEY RR owner name.  This is the public key used
               for the primary DNS security feature of data origin
               authentication.  Zone KEY RRs occur only at delegation
               points.
           10: indicates that this is a key associated with the non-zone
               "entity" whose name is the RR owner name.  This will
               commonly be a host but could, in some parts of the DNS
               tree, be some other type of entity such as a telephone
               number [RFC 1530] or numeric IP address.  This is the
               public key used in connection with DNS request and
               transaction authentication services.  It could also be
               used in an IP-security protocol where authentication at
               the host, rather than user, level was desired, such as
               routing, NTP, etc.
           11: reserved.

   Bits 8-11 are reserved and must be zero.

   Bits 12-15 are the "signatory" field.  If non-zero, they indicate
              that the key can validly sign things as specified in DNS
              dynamic update [RFC 2137].  Note that zone keys (see bits
              6 and 7 above) always have authority to sign any RRs in
              the zone regardless of the value of the signatory field.

Implementations

impl KEY

pub fn new_sig0key(public_key: &dyn PublicKey, algorithm: Algorithm) -> Self

Create a KEY record for usage with SIG0 from an existing public_key.

Use the default KeyUsage of KeyUsage::Entity.

Arguments

• algorithm - algorithm of the KEY

Return

the KEY record data

pub fn new_sig0key_with_usage( public_key: &dyn PublicKey, algorithm: Algorithm, usage: KeyUsage, ) -> KEY

Create a KEY record for usage with SIG0 from an existing public_key.

Arguments

• algorithm - algorithm of the KEY
• usage - the key type

Return

the KEY record data

pub fn new( key_trust: KeyTrust, key_usage: KeyUsage, signatory: UpdateScope, protocol: Protocol, algorithm: Algorithm, public_key: Vec<u8>, ) -> Self

Construct a new KEY RData

Arguments

• key_trust - declare the security level of this key
• key_usage - what type of thing is this key associated to
• revoke - this key has been revoked
• algorithm - specifies the algorithm which this Key uses to sign records
• public_key - the public key material, in native endian, the emitter will perform any necessary conversion

Return

A new KEY RData for use in a Resource Record

pub fn key_trust(&self) -> KeyTrust

Returns the trust level of the key

pub fn key_usage(&self) -> KeyUsage

Returns the entity type using this key

pub fn signatory(&self) -> UpdateScope

Returns the signatory information of the KEY

pub fn revoke(&self) -> bool

Returns true if the key_trust is DoNotTrust

pub fn protocol(&self) -> Protocol

Returns the protocol which this key can be used with

pub fn algorithm(&self) -> Algorithm

RFC 4034, DNSSEC Resource Records, March 2005

2.1.3.  The Algorithm Field

   The Algorithm field identifies the public key's cryptographic
   algorithm and determines the format of the Public Key field.  A list
   of DNSSEC algorithm types can be found in Appendix A.1

pub fn public_key(&self) -> &[u8]

RFC 4034, DNSSEC Resource Records, March 2005

2.1.4.  The Public Key Field

   The Public Key Field holds the public key material.  The format
   depends on the algorithm of the key being stored and is described in
   separate documents.

pub fn flags(&self) -> u16

Output the encoded form of the flags

Trait Implementations

impl BinEncodable for KEY

fn emit(&self, encoder: &mut BinEncoder<'_>) -> Result<(), ProtoError>

Write the type to the stream

fn to_bytes(&self) -> Result<Vec<u8>, ProtoError>

Returns the object in binary form

impl Clone for KEY

fn clone(&self) -> KEY

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for KEY

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for KEY

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for KEY

Note that KEY is a deprecated type in DNS

RFC 2535, Domain Name System Security Extensions, March 1999

7.1 Presentation of KEY RRs

   KEY RRs may appear as single logical lines in a zone data master file
   [RFC 1033].

   The flag field is represented as an unsigned integer or a sequence of
   mnemonics as follows separated by instances of the vertical bar ("|")
   character:

     BIT  Mnemonic  Explanation
    0-1           key type
        NOCONF    =1 confidentiality use prohibited
        NOAUTH    =2 authentication use prohibited
        NOKEY     =3 no key present
    2   FLAG2     - reserved
    3   EXTEND    flags extension
    4   FLAG4     - reserved
    5   FLAG5     - reserved
    6-7           name type
        USER      =0 (default, may be omitted)
        ZONE      =1
        HOST      =2 (host or other end entity)
        NTYP3     - reserved
    8   FLAG8     - reserved
    9   FLAG9     - reserved
   10   FLAG10    - reserved
   11   FLAG11    - reserved
   12-15          signatory field, values 0 to 15
            can be represented by SIG0, SIG1, ... SIG15

   No flag mnemonic need be present if the bit or field it represents is
   zero.

   The protocol octet can be represented as either an unsigned integer
   or symbolically.  The following initial symbols are defined:

        000    NONE
        001    TLS
        002    EMAIL
        003    DNSSEC
        004    IPSEC
        255    ALL

   Note that if the type flags field has the NOKEY value, nothing
   appears after the algorithm octet.

   The remaining public key portion is represented in base 64 (see
   Appendix A) and may be divided up into any number of white space
   separated substrings, down to single base 64 digits, which are
   concatenated to obtain the full signature.  These substrings can span
   lines using the standard parenthesis.

   Note that the public key may have internal sub-fields but these do
   not appear in the master file representation.  For example, with
   algorithm 1 there is a public exponent size, then a public exponent,
   and then a modulus.  With algorithm 254, there will be an OID size,
   an OID, and algorithm dependent information. But in both cases only a
   single logical base 64 string will appear in the master file.

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl From<KEY> for RData

fn from(key: KEY) -> Self

Converts to this type from the input type.

impl Hash for KEY

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for KEY

fn eq(&self, other: &KEY) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RecordData for KEY

fn try_from_rdata(data: RData) -> Result<Self, RData>

Attempts to convert to this RecordData from the RData type, if it is not the correct type the original is returned

fn try_borrow(data: &RData) -> Option<&Self>

Attempts to borrow this RecordData from the RData type, if it is not the correct type the original is returned

fn record_type(&self) -> RecordType

Get the associated RecordType for the RecordData

fn into_rdata(self) -> RData

Converts this RecordData into generic RecordData

fn is_update(&self) -> bool

RDLENGTH = 0

impl Serialize for KEY

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Verifier for KEY

fn algorithm(&self) -> Algorithm

Return the algorithm which this Verifier covers

fn key(&self) -> Result<Arc<dyn PublicKey + '_>, ProtoError>

Return the public key associated with this verifier

fn verify(&self, hash: &[u8], signature: &[u8]) -> Result<(), ProtoError>

Verifies the hash matches the signature with the current key.

fn verify_message<M: BinEncodable>( &self, message: &M, signature: &[u8], sig0: &SIG, ) -> Result<(), ProtoError>

Verifies a message with the against the given signature, i.e. SIG0

fn verify_rrsig<'a>( &self, name: &Name, dns_class: DNSClass, sig: &RRSIG, records: impl Iterator<Item = &'a Record>, ) -> Result<(), ProtoError>

Verifies an RRSig with the associated key, e.g. DNSKEY

impl Eq for KEY

impl StructuralPartialEq for KEY