Home | History | Annotate | Line # | Download | only in dnssdutil 
      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		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