Clients/dnssdutil/DNSServerDNSSEC.h

   1 /*
   2         Copyright (c) 2020 Apple Inc. All rights reserved.
   3 */
   4
   5 #ifndef __DNSServerDNSSEC_h
   6 #define __DNSServerDNSSEC_h
   7
   8 #include <CoreUtils/CoreUtils.h>
   9
  10 CU_ASSUME_NONNULL_BEGIN
  11
  12 __BEGIN_DECLS
  13
  14 //---------------------------------------------------------------------------------------------------------------------------
  15 /*!     @brief  Zone Label Argument Limits
  16 */
  17
  18 #define kZoneLabelIndexArgMin           1
  19 #define kZoneLabelIndexArgMax           3
  20
  21 //---------------------------------------------------------------------------------------------------------------------------
  22 /*!     @brief  Reference to a DNSKeyInfo object.
  23 */
  24 typedef const union DNSKeyInfo *                DNSKeyInfoRef;
  25
  26 //---------------------------------------------------------------------------------------------------------------------------
  27 /*!     @brief          Gets a constant DNSKeyInfo object, which represents a DNSSEC DNS key.
  28
  29         @param          inAlgorithm             The desired DNSKeyInfo object's DNSSEC algorithm number.
  30         @param          inIndex                 The desired DNSKeyInfo object's index number.
  31         @param          inGetZSK                If true, gets a zone-signing key. Otherwise a key-signing key.
  32
  33         @result         If a reference to the DNSKeyInfo object if it exists, otherwise, NULL.
  34 */
  35 DNSKeyInfoRef _Nullable GetDNSKeyInfoEx( uint32_t inAlgorithm, uint32_t inIndex, Boolean inGetZSK );
  36 #define GetDNSKeyInfoKSK( ALGORITHM, INDEX )            GetDNSKeyInfoEx( ALGORITHM, INDEX, false )
  37 #define GetDNSKeyInfoZSK( ALGORITHM, INDEX )            GetDNSKeyInfoEx( ALGORITHM, INDEX, true )
  38
  39 //---------------------------------------------------------------------------------------------------------------------------
  40 /*!     @brief          Gets a DNSKeyInfo object's DNSSEC algorithm number.
  41
  42         @param          inKeyInfo               The DNSKeyInfo object.
  43
  44         @result         The DNSSEC algorithm number.
  45
  46         @discussion     See <https://www.iana.org/assignments/dns-sec-alg-numbers/dns-sec-alg-numbers.xhtml#dns-sec-alg-numbers-1>.
  47 */
  48 uint8_t DNSKeyInfoGetAlgorithm( DNSKeyInfoRef inKeyInfo );
  49
  50 //---------------------------------------------------------------------------------------------------------------------------
  51 /*!     @brief          Gets a pointer to a DNSKeyInfo object's DNSKEY record data.
  52
  53         @param          inKeyInfo               The DNSKeyInfo object.
  54
  55         @result         The DNSKEY record data in wire format. See <https://tools.ietf.org/html/rfc4034#section-2.1>.
  56
  57         @discussion     Use DNSKeyInfoGetRDataLen() to get the record data's length.
  58 */
  59 const uint8_t * DNSKeyInfoGetRDataPtr( DNSKeyInfoRef inKeyInfo );
  60
  61 //---------------------------------------------------------------------------------------------------------------------------
  62 /*!     @brief          Gets the length of a DNSKeyInfo object's DNSKEY record data.
  63
  64         @param          inKeyInfo               The DNSKeyInfo object.
  65
  66         @result         The length of the record data.
  67 */
  68 uint16_t        DNSKeyInfoGetRDataLen( DNSKeyInfoRef inKeyInfo );
  69
  70 //---------------------------------------------------------------------------------------------------------------------------
  71 /*!     @brief          Gets a pointer to a DNSKeyInfo object's public key.
  72
  73         @param          inKeyInfo               The DNSKeyInfo object.
  74
  75         @result         A pointer to the public key.
  76
  77         @discussion     Use DNSKeyInfoGetPubKeyLen() to get the public key's length.
  78 */
  79 const uint8_t * _Nullable DNSKeyInfoGetPubKeyPtr( DNSKeyInfoRef inKeyInfo );
  80
  81 //---------------------------------------------------------------------------------------------------------------------------
  82 /*!     @brief          Gets the length of a DNSKeyInfo object's public key.
  83
  84         @param          inKeyInfo               The DNSKeyInfo object.
  85
  86         @result         The length of the public key.
  87 */
  88 size_t  DNSKeyInfoGetPubKeyLen( DNSKeyInfoRef inKeyInfo );
  89
  90 //---------------------------------------------------------------------------------------------------------------------------
  91 /*!     @brief          Gets the DNSSEC key tag of DNSKeyInfo objects' DNSKEY record data.
  92
  93         @param          inKeyInfo               The DNSKeyInfo object.
  94
  95         @result         The DNSSEC key tag.
  96 */
  97 uint16_t        DNSKeyInfoGetKeyTag( DNSKeyInfoRef inKeyInfo );
  98
  99 //---------------------------------------------------------------------------------------------------------------------------
 100 /*!     @defined        kDNSServerSignatureLengthMax
 101
 102         @discussion     The maximum length of a DNSSEC signature for DNSSEC algorithms currently implemented by the test DNS server.
 103 */
 104 #define kDNSServerSignatureLengthMax            256
 105
 106 //---------------------------------------------------------------------------------------------------------------------------
 107 /*!     @brief          Signs a message using a DNSKeyInfo object's secret key.
 108
 109         @param          inKeyInfo                       The DNSKeyInfo object.
 110         @param          inMsgPtr                        Pointer to the message to sign.
 111         @param          inMsgLen                        Length, in bytes, of the message to sign.
 112         @param          outSignature            Buffer to which to write the signature.
 113         @param          outSignatureLen         Pointer of variable to get set to the signature's length.
 114
 115         @result         Returns true if the message was able to be signed, otherwise, returns false.
 116 */
 117 Boolean
 118         DNSKeyInfoSign(
 119                 DNSKeyInfoRef   inKeyInfo,
 120                 const uint8_t * inMsgPtr,
 121                 size_t                  inMsgLen,
 122                 uint8_t                 outSignature[ STATIC_PARAM kDNSServerSignatureLengthMax ],
 123                 size_t *                outSignatureLen );
 124
 125 //---------------------------------------------------------------------------------------------------------------------------
 126 /*!     @brief          Verifies a signature using a DNSKeyInfo object's public key.
 127
 128         @param          inKeyInfo                       The DNSKeyInfo object.
 129         @param          inMsgPtr                        Pointer to the message that was signed.
 130         @param          inMsgLen                        Length, in bytes, of the message that was signed.
 131         @param          inSignaturePtr          Pointer to the supposed signature.
 132         @param          inSignatureLen          Length, in bytes, of the supposed signature.
 133
 134         @result         Returns true if the signature was verified, otherwise, returns false.
 135 */
 136 Boolean
 137         DNSKeyInfoVerify(
 138                 DNSKeyInfoRef   inKeyInfo,
 139                 const uint8_t * inMsgPtr,
 140                 size_t                  inMsgLen,
 141                 const uint8_t * inSignaturePtr,
 142                 size_t                  inSignatureLen );
 143
 144 //---------------------------------------------------------------------------------------------------------------------------
 145 /*!     @brief          Gets a short description of a DNSKeyInfo object's DNSSEC algorithm.
 146
 147         @param          inKeyInfo               The DNSKeyInfo object.
 148
 149         @result         The description as a UTF-8 C string.
 150 */
 151 const char *    DNSKeyInfoGetAlgorithmDescription( DNSKeyInfoRef inKeyInfo );
 152
 153 __END_DECLS
 154
 155 CU_ASSUME_NONNULL_END
 156
 157 #endif  // __DNSServerDNSSEC_h