/*
* Copyright (C) Internet Systems Consortium, Inc. ("ISC")
*
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, you can obtain one at https://mozilla.org/MPL/2.0/.
*
* See the COPYRIGHT file distributed with this work for additional
* information regarding copyright ownership.
*/
#ifndef DNS_KASP_H
#define DNS_KASP_H 1
/*****
***** Module Info
*****/
/*! \file dns/kasp.h
* \brief
* DNSSEC Key and Signing Policy (KASP)
*
* A "kasp" is a DNSSEC policy, that determines how a zone should be
* signed and maintained.
*/
#include <isc/lang.h>
#include <isc/magic.h>
#include <isc/mutex.h>
#include <isc/refcount.h>
#include <dns/types.h>
ISC_LANG_BEGINDECLS
/* Stores a KASP key */
struct dns_kasp_key {
isc_mem_t *mctx;
/* Locked by themselves. */
isc_refcount_t references;
/* Under owner's locking control. */
ISC_LINK(struct dns_kasp_key) link;
/* Configuration */
uint32_t lifetime;
uint8_t algorithm;
int length;
uint8_t role;
};
struct dns_kasp_nsec3param {
uint8_t saltlen;
uint8_t algorithm;
uint8_t iterations;
bool optout;
};
/* Stores a DNSSEC policy */
struct dns_kasp {
unsigned int magic;
isc_mem_t *mctx;
char *name;
/* Internals. */
isc_mutex_t lock;
bool frozen;
/* Locked by themselves. */
isc_refcount_t references;
/* Under owner's locking control. */
ISC_LINK(struct dns_kasp) link;
/* Configuration: signatures */
uint32_t signatures_refresh;
uint32_t signatures_validity;
uint32_t signatures_validity_dnskey;
/* Configuration: Keys */
dns_kasp_keylist_t keys;
dns_ttl_t dnskey_ttl;
/* Configuration: Denial of existence */
bool nsec3;
dns_kasp_nsec3param_t nsec3param;
/* Configuration: Timings */
uint32_t publish_safety;
uint32_t retire_safety;
uint32_t purge_keys;
/* Zone settings */
dns_ttl_t zone_max_ttl;
uint32_t zone_propagation_delay;
/* Parent settings */
dns_ttl_t parent_ds_ttl;
uint32_t parent_propagation_delay;
};
#define DNS_KASP_MAGIC ISC_MAGIC('K', 'A', 'S', 'P')
#define DNS_KASP_VALID(kasp) ISC_MAGIC_VALID(kasp, DNS_KASP_MAGIC)
/* Defaults */
#define DNS_KASP_SIG_REFRESH (86400 * 5)
#define DNS_KASP_SIG_VALIDITY (86400 * 14)
#define DNS_KASP_SIG_VALIDITY_DNSKEY (86400 * 14)
#define DNS_KASP_KEY_TTL (3600)
#define DNS_KASP_DS_TTL (86400)
#define DNS_KASP_PUBLISH_SAFETY (3600)
#define DNS_KASP_PURGE_KEYS (86400 * 90)
#define DNS_KASP_RETIRE_SAFETY (3600)
#define DNS_KASP_ZONE_MAXTTL (86400)
#define DNS_KASP_ZONE_PROPDELAY (300)
#define DNS_KASP_PARENT_PROPDELAY (3600)
/* Key roles */
#define DNS_KASP_KEY_ROLE_KSK 0x01
#define DNS_KASP_KEY_ROLE_ZSK 0x02
isc_result_t
dns_kasp_create(isc_mem_t *mctx, const char *name, dns_kasp_t **kaspp);
/*%<
* Create a KASP.
*
* Requires:
*
*\li 'mctx' is a valid memory context.
*
*\li 'name' is a valid C string.
*
*\li kaspp != NULL && *kaspp == NULL
*
* Returns:
*
*\li #ISC_R_SUCCESS
*\li #ISC_R_NOMEMORY
*
*\li Other errors are possible.
*/
void
dns_kasp_attach(dns_kasp_t *source, dns_kasp_t **targetp);
/*%<
* Attach '*targetp' to 'source'.
*
* Requires:
*
*\li 'source' is a valid, frozen kasp.
*
*\li 'targetp' points to a NULL dns_kasp_t *.
*
* Ensures:
*
*\li *targetp is attached to source.
*
*\li While *targetp is attached, the kasp will not shut down.
*/
void
dns_kasp_detach(dns_kasp_t **kaspp);
/*%<
* Detach KASP.
*
* Requires:
*
*\li 'kaspp' points to a valid dns_kasp_t *
*
* Ensures:
*
*\li *kaspp is NULL.
*/
void
dns_kasp_freeze(dns_kasp_t *kasp);
/*%<
* Freeze kasp. No changes can be made to kasp configuration while frozen.
*
* Requires:
*
*\li 'kasp' is a valid, unfrozen kasp.
*
* Ensures:
*
*\li 'kasp' is frozen.
*/
void
dns_kasp_thaw(dns_kasp_t *kasp);
/*%<
* Thaw kasp.
*
* Requires:
*
*\li 'kasp' is a valid, frozen kasp.
*
* Ensures:
*
*\li 'kasp' is no longer frozen.
*/
const char *
dns_kasp_getname(dns_kasp_t *kasp);
/*%<
* Get kasp name.
*
* Requires:
*
*\li 'kasp' is a valid kasp.
*
* Returns:
*
*\li name of 'kasp'.
*/
uint32_t
dns_kasp_signdelay(dns_kasp_t *kasp);
/*%<
* Get the delay that is needed to ensure that all existing RRsets have been
* re-signed with a successor key. This is the signature validity minus the
* signature refresh time (that indicates how far before signature expiry an
* RRSIG should be refreshed).
*
* Requires:
*
*\li 'kasp' is a valid, frozen kasp.
*
* Returns:
*
*\li signature refresh interval.
*/
uint32_t
dns_kasp_sigrefresh(dns_kasp_t *kasp);
/*%<
* Get signature refresh interval.
*
* Requires:
*
*\li 'kasp' is a valid, frozen kasp.
*
* Returns:
*
*\li signature refresh interval.
*/
void
dns_kasp_setsigrefresh(dns_kasp_t *kasp, uint32_t value);
/*%<
* Set signature refresh interval.
*
* Requires:
*
*\li 'kasp' is a valid, thawed kasp.
*/
uint32_t
dns_kasp_sigvalidity(dns_kasp_t *kasp);
uint32_t
dns_kasp_sigvalidity_dnskey(dns_kasp_t *kasp);
/*%<
* Get signature validity.
*
* Requires:
*
*\li 'kasp' is a valid, frozen kasp.
*
* Returns:
*
*\li signature validity.
*/
void
dns_kasp_setsigvalidity(dns_kasp_t *kasp, uint32_t value);
void
dns_kasp_setsigvalidity_dnskey(dns_kasp_t *kasp, uint32_t value);
/*%<
* Set signature validity.
*
* Requires:
*
*\li 'kasp' is a valid, thawed kasp.
*/
dns_ttl_t
dns_kasp_dnskeyttl(dns_kasp_t *kasp);
/*%<
* Get DNSKEY TTL.
*
* Requires:
*
*\li 'kasp' is a valid, frozen kasp.
*
* Returns:
*
*\li DNSKEY TTL.
*/
void
dns_kasp_setdnskeyttl(dns_kasp_t *kasp, dns_ttl_t ttl);
/*%<
* Set DNSKEY TTL.
*
* Requires:
*
*\li 'kasp' is a valid, thawed kasp.
*/
uint32_t
dns_kasp_purgekeys(dns_kasp_t *kasp);
/*%<
* Get purge keys interval.
*
* Requires:
*
*\li 'kasp' is a valid, frozen kasp.
*
* Returns:
*
*\li Purge keys interval.
*/
void
dns_kasp_setpurgekeys(dns_kasp_t *kasp, uint32_t value);
/*%<
* Set purge keys interval.
*
* Requires:
*
*\li 'kasp' is a valid, thawed kasp.
*/
uint32_t
dns_kasp_publishsafety(dns_kasp_t *kasp);
/*%<
* Get publish safety interval.
*
* Requires:
*
*\li 'kasp' is a valid, frozen kasp.
*
* Returns:
*
*\li Publish safety interval.
*/
void
dns_kasp_setpublishsafety(dns_kasp_t *kasp, uint32_t value);
/*%<
* Set publish safety interval.
*
* Requires:
*
*\li 'kasp' is a valid, thawed kasp.
*/
uint32_t
dns_kasp_retiresafety(dns_kasp_t *kasp);
/*%<
* Get retire safety interval.
*
* Requires:
*
*\li 'kasp' is a valid, frozen kasp.
*
* Returns:
*
*\li Retire safety interval.
*/
void
dns_kasp_setretiresafety(dns_kasp_t *kasp, uint32_t value);
/*%<
* Set retire safety interval.
*
* Requires:
*
*\li 'kasp' is a valid, thawed kasp.
*/
dns_ttl_t
dns_kasp_zonemaxttl(dns_kasp_t *kasp);
/*%<
* Get maximum zone TTL.
*
* Requires:
*
*\li 'kasp' is a valid, frozen kasp.
*
* Returns:
*
*\li Maximum zone TTL.
*/
void
dns_kasp_setzonemaxttl(dns_kasp_t *kasp, dns_ttl_t ttl);
/*%<
* Set maximum zone TTL.
*
* Requires:
*
*\li 'kasp' is a valid, thawed kasp.
*/
uint32_t
dns_kasp_zonepropagationdelay(dns_kasp_t *kasp);
/*%<
* Get zone propagation delay.
*
* Requires:
*
*\li 'kasp' is a valid, frozen kasp.
*
* Returns:
*
*\li Zone propagation delay.
*/
void
dns_kasp_setzonepropagationdelay(dns_kasp_t *kasp, uint32_t value);
/*%<
* Set zone propagation delay.
*
* Requires:
*
*\li 'kasp' is a valid, thawed kasp.
*/
dns_ttl_t
dns_kasp_dsttl(dns_kasp_t *kasp);
/*%<
* Get DS TTL (should match that of the parent DS record).
*
* Requires:
*
*\li 'kasp' is a valid, frozen kasp.
*
* Returns:
*
*\li Expected parent DS TTL.
*/
void
dns_kasp_setdsttl(dns_kasp_t *kasp, dns_ttl_t ttl);
/*%<
* Set DS TTL.
*
* Requires:
*
*\li 'kasp' is a valid, thawed kasp.
*/
uint32_t
dns_kasp_parentpropagationdelay(dns_kasp_t *kasp);
/*%<
* Get parent zone propagation delay.
*
* Requires:
*
*\li 'kasp' is a valid, frozen kasp.
*
* Returns:
*
*\li Parent zone propagation delay.
*/
void
dns_kasp_setparentpropagationdelay(dns_kasp_t *kasp, uint32_t value);
/*%<
* Set parent propagation delay.
*
* Requires:
*
*\li 'kasp' is a valid, thawed kasp.
*/
isc_result_t
dns_kasplist_find(dns_kasplist_t *list, const char *name, dns_kasp_t **kaspp);
/*%<
* Search for a kasp with name 'name' in 'list'.
* If found, '*kaspp' is (strongly) attached to it.
*
* Requires:
*
*\li 'kaspp' points to a NULL dns_kasp_t *.
*
* Returns:
*
*\li #ISC_R_SUCCESS A matching kasp was found.
*\li #ISC_R_NOTFOUND No matching kasp was found.
*/
dns_kasp_keylist_t
dns_kasp_keys(dns_kasp_t *kasp);
/*%<
* Get the list of kasp keys.
*
* Requires:
*
*\li 'kasp' is a valid, frozen kasp.
*
* Returns:
*
*\li #ISC_R_SUCCESS
*\li #ISC_R_NOMEMORY
*
*\li Other errors are possible.
*/
bool
dns_kasp_keylist_empty(dns_kasp_t *kasp);
/*%<
* Check if the keylist is empty.
*
* Requires:
*
*\li 'kasp' is a valid kasp.
*
* Returns:
*
*\li true if the keylist is empty, false otherwise.
*/
void
dns_kasp_addkey(dns_kasp_t *kasp, dns_kasp_key_t *key);
/*%<
* Add a key.
*
* Requires:
*
*\li 'kasp' is a valid, thawed kasp.
*\li 'key' is not NULL.
*/
isc_result_t
dns_kasp_key_create(dns_kasp_t *kasp, dns_kasp_key_t **keyp);
/*%<
* Create a key inside a KASP.
*
* Requires:
*
*\li 'kasp' is a valid kasp.
*
*\li keyp != NULL && *keyp == NULL
*
* Returns:
*
*\li #ISC_R_SUCCESS
*\li #ISC_R_NOMEMORY
*
*\li Other errors are possible.
*/
void
dns_kasp_key_destroy(dns_kasp_key_t *key);
/*%<
* Destroy a KASP key.
*
* Requires:
*
*\li key != NULL
*/
uint32_t
dns_kasp_key_algorithm(dns_kasp_key_t *key);
/*%<
* Get the key algorithm.
*
* Requires:
*
*\li key != NULL
*
* Returns:
*
*\li Key algorithm.
*/
unsigned int
dns_kasp_key_size(dns_kasp_key_t *key);
/*%<
* Get the key size.
*
* Requires:
*
*\li key != NULL
*
* Returns:
*
*\li Configured key size, or default key size for key algorithm if no size
* configured.
*/
uint32_t
dns_kasp_key_lifetime(dns_kasp_key_t *key);
/*%<
* The lifetime of this key (how long may this key be active?)
*
* Requires:
*
*\li key != NULL
*
* Returns:
*
*\li Lifetime of key.
*
*/
bool
dns_kasp_key_ksk(dns_kasp_key_t *key);
/*%<
* Does this key act as a KSK?
*
* Requires:
*
*\li key != NULL
*
* Returns:
*
*\li True, if the key role has DNS_KASP_KEY_ROLE_KSK set.
*\li False, otherwise.
*
*/
bool
dns_kasp_key_zsk(dns_kasp_key_t *key);
/*%<
* Does this key act as a ZSK?
*
* Requires:
*
*\li key != NULL
*
* Returns:
*
*\li True, if the key role has DNS_KASP_KEY_ROLE_ZSK set.
*\li False, otherwise.
*
*/
bool
dns_kasp_nsec3(dns_kasp_t *kasp);
/*%<
* Return true if NSEC3 chain should be used.
*
* Requires:
*
*\li 'kasp' is a valid, frozen kasp.
*
*/
uint8_t
dns_kasp_nsec3iter(dns_kasp_t *kasp);
/*%<
* The number of NSEC3 iterations to use.
*
* Requires:
*
*\li 'kasp' is a valid, frozen kasp.
*\li 'kasp->nsec3' is true.
*
*/
uint8_t
dns_kasp_nsec3flags(dns_kasp_t *kasp);
/*%<
* The NSEC3 flags field value.
*
* Requires:
*
*\li 'kasp' is a valid, frozen kasp.
*\li 'kasp->nsec3' is true.
*
*/
uint8_t
dns_kasp_nsec3saltlen(dns_kasp_t *kasp);
/*%<
* The NSEC3 salt length.
*
* Requires:
*
*\li 'kasp' is a valid, frozen kasp.
*\li 'kasp->nsec3' is true.
*
*/
void
dns_kasp_setnsec3(dns_kasp_t *kasp, bool nsec3);
/*%<
* Set to use NSEC3 if 'nsec3' is 'true', otherwise policy will use NSEC.
*
* Requires:
*
*\li 'kasp' is a valid, unfrozen kasp.
*
*/
void
dns_kasp_setnsec3param(dns_kasp_t *kasp, uint8_t iter, bool optout,
uint8_t saltlen);
/*%<
* Set the desired NSEC3 parameters.
*
* Requires:
*
*\li 'kasp' is a valid, unfrozen kasp.
*\li 'kasp->nsec3' is true.
*
*/
ISC_LANG_ENDDECLS
#endif /* DNS_KASP_H */
