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 158