/contrib/bind9/lib/dns/include/dst/dst.h

https://bitbucket.org/freebsd/freebsd-head/ · C Header · 885 lines · 202 code · 84 blank · 599 comment · 0 complexity · e4bc7aa3d63e0655df2360722674a24d MD5 · raw file

  1. /*
  2. * Copyright (C) 2004-2012 Internet Systems Consortium, Inc. ("ISC")
  3. * Copyright (C) 2000-2002 Internet Software Consortium.
  4. *
  5. * Permission to use, copy, modify, and/or distribute this software for any
  6. * purpose with or without fee is hereby granted, provided that the above
  7. * copyright notice and this permission notice appear in all copies.
  8. *
  9. * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10. * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11. * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12. * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13. * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14. * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15. * PERFORMANCE OF THIS SOFTWARE.
  16. */
  17. /* $Id$ */
  18. #ifndef DST_DST_H
  19. #define DST_DST_H 1
  20. /*! \file dst/dst.h */
  21. #include <isc/lang.h>
  22. #include <isc/stdtime.h>
  23. #include <dns/types.h>
  24. #include <dns/name.h>
  25. #include <dns/secalg.h>
  26. #include <dst/gssapi.h>
  27. ISC_LANG_BEGINDECLS
  28. /***
  29. *** Types
  30. ***/
  31. /*%
  32. * The dst_key structure is opaque. Applications should use the accessor
  33. * functions provided to retrieve key attributes. If an application needs
  34. * to set attributes, new accessor functions will be written.
  35. */
  36. typedef struct dst_key dst_key_t;
  37. typedef struct dst_context dst_context_t;
  38. /* DST algorithm codes */
  39. #define DST_ALG_UNKNOWN 0
  40. #define DST_ALG_RSAMD5 1
  41. #define DST_ALG_RSA DST_ALG_RSAMD5 /*%< backwards compatibility */
  42. #define DST_ALG_DH 2
  43. #define DST_ALG_DSA 3
  44. #define DST_ALG_ECC 4
  45. #define DST_ALG_RSASHA1 5
  46. #define DST_ALG_NSEC3DSA 6
  47. #define DST_ALG_NSEC3RSASHA1 7
  48. #define DST_ALG_RSASHA256 8
  49. #define DST_ALG_RSASHA512 10
  50. #define DST_ALG_ECCGOST 12
  51. #define DST_ALG_HMACMD5 157
  52. #define DST_ALG_GSSAPI 160
  53. #define DST_ALG_HMACSHA1 161 /* XXXMPA */
  54. #define DST_ALG_HMACSHA224 162 /* XXXMPA */
  55. #define DST_ALG_HMACSHA256 163 /* XXXMPA */
  56. #define DST_ALG_HMACSHA384 164 /* XXXMPA */
  57. #define DST_ALG_HMACSHA512 165 /* XXXMPA */
  58. #define DST_ALG_PRIVATE 254
  59. #define DST_ALG_EXPAND 255
  60. #define DST_MAX_ALGS 255
  61. /*% A buffer of this size is large enough to hold any key */
  62. #define DST_KEY_MAXSIZE 1280
  63. /*%
  64. * A buffer of this size is large enough to hold the textual representation
  65. * of any key
  66. */
  67. #define DST_KEY_MAXTEXTSIZE 2048
  68. /*% 'Type' for dst_read_key() */
  69. #define DST_TYPE_KEY 0x1000000 /* KEY key */
  70. #define DST_TYPE_PRIVATE 0x2000000
  71. #define DST_TYPE_PUBLIC 0x4000000
  72. /* Key timing metadata definitions */
  73. #define DST_TIME_CREATED 0
  74. #define DST_TIME_PUBLISH 1
  75. #define DST_TIME_ACTIVATE 2
  76. #define DST_TIME_REVOKE 3
  77. #define DST_TIME_INACTIVE 4
  78. #define DST_TIME_DELETE 5
  79. #define DST_TIME_DSPUBLISH 6
  80. #define DST_MAX_TIMES 6
  81. /* Numeric metadata definitions */
  82. #define DST_NUM_PREDECESSOR 0
  83. #define DST_NUM_SUCCESSOR 1
  84. #define DST_NUM_MAXTTL 2
  85. #define DST_NUM_ROLLPERIOD 3
  86. #define DST_MAX_NUMERIC 3
  87. /*
  88. * Current format version number of the private key parser.
  89. *
  90. * When parsing a key file with the same major number but a higher minor
  91. * number, the key parser will ignore any fields it does not recognize.
  92. * Thus, DST_MINOR_VERSION should be incremented whenever new
  93. * fields are added to the private key file (such as new metadata).
  94. *
  95. * When rewriting these keys, those fields will be dropped, and the
  96. * format version set back to the current one..
  97. *
  98. * When a key is seen with a higher major number, the key parser will
  99. * reject it as invalid. Thus, DST_MAJOR_VERSION should be incremented
  100. * and DST_MINOR_VERSION set to zero whenever there is a format change
  101. * which is not backward compatible to previous versions of the dst_key
  102. * parser, such as change in the syntax of an existing field, the removal
  103. * of a currently mandatory field, or a new field added which would
  104. * alter the functioning of the key if it were absent.
  105. */
  106. #define DST_MAJOR_VERSION 1
  107. #define DST_MINOR_VERSION 3
  108. /***
  109. *** Functions
  110. ***/
  111. isc_result_t
  112. dst_lib_init(isc_mem_t *mctx, isc_entropy_t *ectx, unsigned int eflags);
  113. isc_result_t
  114. dst_lib_init2(isc_mem_t *mctx, isc_entropy_t *ectx,
  115. const char *engine, unsigned int eflags);
  116. /*%<
  117. * Initializes the DST subsystem.
  118. *
  119. * Requires:
  120. * \li "mctx" is a valid memory context
  121. * \li "ectx" is a valid entropy context
  122. *
  123. * Returns:
  124. * \li ISC_R_SUCCESS
  125. * \li ISC_R_NOMEMORY
  126. * \li DST_R_NOENGINE
  127. *
  128. * Ensures:
  129. * \li DST is properly initialized.
  130. */
  131. void
  132. dst_lib_destroy(void);
  133. /*%<
  134. * Releases all resources allocated by DST.
  135. */
  136. isc_boolean_t
  137. dst_algorithm_supported(unsigned int alg);
  138. /*%<
  139. * Checks that a given algorithm is supported by DST.
  140. *
  141. * Returns:
  142. * \li ISC_TRUE
  143. * \li ISC_FALSE
  144. */
  145. isc_result_t
  146. dst_context_create(dst_key_t *key, isc_mem_t *mctx, dst_context_t **dctxp);
  147. /*%<
  148. * Creates a context to be used for a sign or verify operation.
  149. *
  150. * Requires:
  151. * \li "key" is a valid key.
  152. * \li "mctx" is a valid memory context.
  153. * \li dctxp != NULL && *dctxp == NULL
  154. *
  155. * Returns:
  156. * \li ISC_R_SUCCESS
  157. * \li ISC_R_NOMEMORY
  158. *
  159. * Ensures:
  160. * \li *dctxp will contain a usable context.
  161. */
  162. void
  163. dst_context_destroy(dst_context_t **dctxp);
  164. /*%<
  165. * Destroys all memory associated with a context.
  166. *
  167. * Requires:
  168. * \li *dctxp != NULL && *dctxp == NULL
  169. *
  170. * Ensures:
  171. * \li *dctxp == NULL
  172. */
  173. isc_result_t
  174. dst_context_adddata(dst_context_t *dctx, const isc_region_t *data);
  175. /*%<
  176. * Incrementally adds data to the context to be used in a sign or verify
  177. * operation.
  178. *
  179. * Requires:
  180. * \li "dctx" is a valid context
  181. * \li "data" is a valid region
  182. *
  183. * Returns:
  184. * \li ISC_R_SUCCESS
  185. * \li DST_R_SIGNFAILURE
  186. * \li all other errors indicate failure
  187. */
  188. isc_result_t
  189. dst_context_sign(dst_context_t *dctx, isc_buffer_t *sig);
  190. /*%<
  191. * Computes a signature using the data and key stored in the context.
  192. *
  193. * Requires:
  194. * \li "dctx" is a valid context.
  195. * \li "sig" is a valid buffer.
  196. *
  197. * Returns:
  198. * \li ISC_R_SUCCESS
  199. * \li DST_R_VERIFYFAILURE
  200. * \li all other errors indicate failure
  201. *
  202. * Ensures:
  203. * \li "sig" will contain the signature
  204. */
  205. isc_result_t
  206. dst_context_verify(dst_context_t *dctx, isc_region_t *sig);
  207. /*%<
  208. * Verifies the signature using the data and key stored in the context.
  209. *
  210. * Requires:
  211. * \li "dctx" is a valid context.
  212. * \li "sig" is a valid region.
  213. *
  214. * Returns:
  215. * \li ISC_R_SUCCESS
  216. * \li all other errors indicate failure
  217. *
  218. * Ensures:
  219. * \li "sig" will contain the signature
  220. */
  221. isc_result_t
  222. dst_key_computesecret(const dst_key_t *pub, const dst_key_t *priv,
  223. isc_buffer_t *secret);
  224. /*%<
  225. * Computes a shared secret from two (Diffie-Hellman) keys.
  226. *
  227. * Requires:
  228. * \li "pub" is a valid key that can be used to derive a shared secret
  229. * \li "priv" is a valid private key that can be used to derive a shared secret
  230. * \li "secret" is a valid buffer
  231. *
  232. * Returns:
  233. * \li ISC_R_SUCCESS
  234. * \li any other result indicates failure
  235. *
  236. * Ensures:
  237. * \li If successful, secret will contain the derived shared secret.
  238. */
  239. isc_result_t
  240. dst_key_fromfile(dns_name_t *name, dns_keytag_t id, unsigned int alg, int type,
  241. const char *directory, isc_mem_t *mctx, dst_key_t **keyp);
  242. /*%<
  243. * Reads a key from permanent storage. The key can either be a public or
  244. * private key, and is specified by name, algorithm, and id. If a private key
  245. * is specified, the public key must also be present. If directory is NULL,
  246. * the current directory is assumed.
  247. *
  248. * Requires:
  249. * \li "name" is a valid absolute dns name.
  250. * \li "id" is a valid key tag identifier.
  251. * \li "alg" is a supported key algorithm.
  252. * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union.
  253. * DST_TYPE_KEY look for a KEY record otherwise DNSKEY
  254. * \li "mctx" is a valid memory context.
  255. * \li "keyp" is not NULL and "*keyp" is NULL.
  256. *
  257. * Returns:
  258. * \li ISC_R_SUCCESS
  259. * \li any other result indicates failure
  260. *
  261. * Ensures:
  262. * \li If successful, *keyp will contain a valid key.
  263. */
  264. isc_result_t
  265. dst_key_fromnamedfile(const char *filename, const char *dirname,
  266. int type, isc_mem_t *mctx, dst_key_t **keyp);
  267. /*%<
  268. * Reads a key from permanent storage. The key can either be a public or
  269. * key, and is specified by filename. If a private key is specified, the
  270. * public key must also be present.
  271. *
  272. * If 'dirname' is not NULL, and 'filename' is a relative path,
  273. * then the file is looked up relative to the given directory.
  274. * If 'filename' is an absolute path, 'dirname' is ignored.
  275. *
  276. * Requires:
  277. * \li "filename" is not NULL
  278. * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union
  279. * DST_TYPE_KEY look for a KEY record otherwise DNSKEY
  280. * \li "mctx" is a valid memory context
  281. * \li "keyp" is not NULL and "*keyp" is NULL.
  282. *
  283. * Returns:
  284. * \li ISC_R_SUCCESS
  285. * \li any other result indicates failure
  286. *
  287. * Ensures:
  288. * \li If successful, *keyp will contain a valid key.
  289. */
  290. isc_result_t
  291. dst_key_read_public(const char *filename, int type,
  292. isc_mem_t *mctx, dst_key_t **keyp);
  293. /*%<
  294. * Reads a public key from permanent storage. The key must be a public key.
  295. *
  296. * Requires:
  297. * \li "filename" is not NULL
  298. * \li "type" is DST_TYPE_KEY look for a KEY record otherwise DNSKEY
  299. * \li "mctx" is a valid memory context
  300. * \li "keyp" is not NULL and "*keyp" is NULL.
  301. *
  302. * Returns:
  303. * \li ISC_R_SUCCESS
  304. * \li DST_R_BADKEYTYPE if the key type is not the expected one
  305. * \li ISC_R_UNEXPECTEDTOKEN if the file can not be parsed as a public key
  306. * \li any other result indicates failure
  307. *
  308. * Ensures:
  309. * \li If successful, *keyp will contain a valid key.
  310. */
  311. isc_result_t
  312. dst_key_tofile(const dst_key_t *key, int type, const char *directory);
  313. /*%<
  314. * Writes a key to permanent storage. The key can either be a public or
  315. * private key. Public keys are written in DNS format and private keys
  316. * are written as a set of base64 encoded values. If directory is NULL,
  317. * the current directory is assumed.
  318. *
  319. * Requires:
  320. * \li "key" is a valid key.
  321. * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union
  322. *
  323. * Returns:
  324. * \li ISC_R_SUCCESS
  325. * \li any other result indicates failure
  326. */
  327. isc_result_t
  328. dst_key_fromdns(dns_name_t *name, dns_rdataclass_t rdclass,
  329. isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp);
  330. /*%<
  331. * Converts a DNS KEY record into a DST key.
  332. *
  333. * Requires:
  334. * \li "name" is a valid absolute dns name.
  335. * \li "source" is a valid buffer. There must be at least 4 bytes available.
  336. * \li "mctx" is a valid memory context.
  337. * \li "keyp" is not NULL and "*keyp" is NULL.
  338. *
  339. * Returns:
  340. * \li ISC_R_SUCCESS
  341. * \li any other result indicates failure
  342. *
  343. * Ensures:
  344. * \li If successful, *keyp will contain a valid key, and the consumed
  345. * pointer in data will be advanced.
  346. */
  347. isc_result_t
  348. dst_key_todns(const dst_key_t *key, isc_buffer_t *target);
  349. /*%<
  350. * Converts a DST key into a DNS KEY record.
  351. *
  352. * Requires:
  353. * \li "key" is a valid key.
  354. * \li "target" is a valid buffer. There must be at least 4 bytes unused.
  355. *
  356. * Returns:
  357. * \li ISC_R_SUCCESS
  358. * \li any other result indicates failure
  359. *
  360. * Ensures:
  361. * \li If successful, the used pointer in 'target' is advanced by at least 4.
  362. */
  363. isc_result_t
  364. dst_key_frombuffer(dns_name_t *name, unsigned int alg,
  365. unsigned int flags, unsigned int protocol,
  366. dns_rdataclass_t rdclass,
  367. isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp);
  368. /*%<
  369. * Converts a buffer containing DNS KEY RDATA into a DST key.
  370. *
  371. * Requires:
  372. *\li "name" is a valid absolute dns name.
  373. *\li "alg" is a supported key algorithm.
  374. *\li "source" is a valid buffer.
  375. *\li "mctx" is a valid memory context.
  376. *\li "keyp" is not NULL and "*keyp" is NULL.
  377. *
  378. * Returns:
  379. *\li ISC_R_SUCCESS
  380. * \li any other result indicates failure
  381. *
  382. * Ensures:
  383. *\li If successful, *keyp will contain a valid key, and the consumed
  384. * pointer in source will be advanced.
  385. */
  386. isc_result_t
  387. dst_key_tobuffer(const dst_key_t *key, isc_buffer_t *target);
  388. /*%<
  389. * Converts a DST key into DNS KEY RDATA format.
  390. *
  391. * Requires:
  392. *\li "key" is a valid key.
  393. *\li "target" is a valid buffer.
  394. *
  395. * Returns:
  396. *\li ISC_R_SUCCESS
  397. * \li any other result indicates failure
  398. *
  399. * Ensures:
  400. *\li If successful, the used pointer in 'target' is advanced.
  401. */
  402. isc_result_t
  403. dst_key_privatefrombuffer(dst_key_t *key, isc_buffer_t *buffer);
  404. /*%<
  405. * Converts a public key into a private key, reading the private key
  406. * information from the buffer. The buffer should contain the same data
  407. * as the .private key file would.
  408. *
  409. * Requires:
  410. *\li "key" is a valid public key.
  411. *\li "buffer" is not NULL.
  412. *
  413. * Returns:
  414. *\li ISC_R_SUCCESS
  415. * \li any other result indicates failure
  416. *
  417. * Ensures:
  418. *\li If successful, key will contain a valid private key.
  419. */
  420. gss_ctx_id_t
  421. dst_key_getgssctx(const dst_key_t *key);
  422. /*%<
  423. * Returns the opaque key data.
  424. * Be cautions when using this value unless you know what you are doing.
  425. *
  426. * Requires:
  427. *\li "key" is not NULL.
  428. *
  429. * Returns:
  430. *\li gssctx key data, possibly NULL.
  431. */
  432. isc_result_t
  433. dst_key_fromgssapi(dns_name_t *name, gss_ctx_id_t gssctx, isc_mem_t *mctx,
  434. dst_key_t **keyp, isc_region_t *intoken);
  435. /*%<
  436. * Converts a GSSAPI opaque context id into a DST key.
  437. *
  438. * Requires:
  439. *\li "name" is a valid absolute dns name.
  440. *\li "gssctx" is a GSSAPI context id.
  441. *\li "mctx" is a valid memory context.
  442. *\li "keyp" is not NULL and "*keyp" is NULL.
  443. *
  444. * Returns:
  445. *\li ISC_R_SUCCESS
  446. * \li any other result indicates failure
  447. *
  448. * Ensures:
  449. *\li If successful, *keyp will contain a valid key and be responsible for
  450. * the context id.
  451. */
  452. isc_result_t
  453. dst_key_fromlabel(dns_name_t *name, int alg, unsigned int flags,
  454. unsigned int protocol, dns_rdataclass_t rdclass,
  455. const char *engine, const char *label, const char *pin,
  456. isc_mem_t *mctx, dst_key_t **keyp);
  457. isc_result_t
  458. dst_key_generate(dns_name_t *name, unsigned int alg,
  459. unsigned int bits, unsigned int param,
  460. unsigned int flags, unsigned int protocol,
  461. dns_rdataclass_t rdclass,
  462. isc_mem_t *mctx, dst_key_t **keyp);
  463. isc_result_t
  464. dst_key_generate2(dns_name_t *name, unsigned int alg,
  465. unsigned int bits, unsigned int param,
  466. unsigned int flags, unsigned int protocol,
  467. dns_rdataclass_t rdclass,
  468. isc_mem_t *mctx, dst_key_t **keyp,
  469. void (*callback)(int));
  470. /*%<
  471. * Generate a DST key (or keypair) with the supplied parameters. The
  472. * interpretation of the "param" field depends on the algorithm:
  473. * \code
  474. * RSA: exponent
  475. * 0 use exponent 3
  476. * !0 use Fermat4 (2^16 + 1)
  477. * DH: generator
  478. * 0 default - use well known prime if bits == 768 or 1024,
  479. * otherwise use 2 as the generator.
  480. * !0 use this value as the generator.
  481. * DSA: unused
  482. * HMACMD5: entropy
  483. * 0 default - require good entropy
  484. * !0 lack of good entropy is ok
  485. *\endcode
  486. *
  487. * Requires:
  488. *\li "name" is a valid absolute dns name.
  489. *\li "keyp" is not NULL and "*keyp" is NULL.
  490. *
  491. * Returns:
  492. *\li ISC_R_SUCCESS
  493. * \li any other result indicates failure
  494. *
  495. * Ensures:
  496. *\li If successful, *keyp will contain a valid key.
  497. */
  498. isc_boolean_t
  499. dst_key_compare(const dst_key_t *key1, const dst_key_t *key2);
  500. /*%<
  501. * Compares two DST keys. Returns true if they match, false otherwise.
  502. *
  503. * Keys ARE NOT considered to match if one of them is the revoked version
  504. * of the other.
  505. *
  506. * Requires:
  507. *\li "key1" is a valid key.
  508. *\li "key2" is a valid key.
  509. *
  510. * Returns:
  511. *\li ISC_TRUE
  512. * \li ISC_FALSE
  513. */
  514. isc_boolean_t
  515. dst_key_pubcompare(const dst_key_t *key1, const dst_key_t *key2,
  516. isc_boolean_t match_revoked_key);
  517. /*%<
  518. * Compares only the public portions of two DST keys. Returns true
  519. * if they match, false otherwise. This allows us, for example, to
  520. * determine whether a public key found in a zone matches up with a
  521. * key pair found on disk.
  522. *
  523. * If match_revoked_key is TRUE, then keys ARE considered to match if one
  524. * of them is the revoked version of the other. Otherwise, they are not.
  525. *
  526. * Requires:
  527. *\li "key1" is a valid key.
  528. *\li "key2" is a valid key.
  529. *
  530. * Returns:
  531. *\li ISC_TRUE
  532. * \li ISC_FALSE
  533. */
  534. isc_boolean_t
  535. dst_key_paramcompare(const dst_key_t *key1, const dst_key_t *key2);
  536. /*%<
  537. * Compares the parameters of two DST keys. This is used to determine if
  538. * two (Diffie-Hellman) keys can be used to derive a shared secret.
  539. *
  540. * Requires:
  541. *\li "key1" is a valid key.
  542. *\li "key2" is a valid key.
  543. *
  544. * Returns:
  545. *\li ISC_TRUE
  546. * \li ISC_FALSE
  547. */
  548. void
  549. dst_key_attach(dst_key_t *source, dst_key_t **target);
  550. /*
  551. * Attach to a existing key increasing the reference count.
  552. *
  553. * Requires:
  554. *\li 'source' to be a valid key.
  555. *\li 'target' to be non-NULL and '*target' to be NULL.
  556. */
  557. void
  558. dst_key_free(dst_key_t **keyp);
  559. /*%<
  560. * Decrement the key's reference counter and, when it reaches zero,
  561. * release all memory associated with the key.
  562. *
  563. * Requires:
  564. *\li "keyp" is not NULL and "*keyp" is a valid key.
  565. *\li reference counter greater than zero.
  566. *
  567. * Ensures:
  568. *\li All memory associated with "*keyp" will be freed.
  569. *\li *keyp == NULL
  570. */
  571. /*%<
  572. * Accessor functions to obtain key fields.
  573. *
  574. * Require:
  575. *\li "key" is a valid key.
  576. */
  577. dns_name_t *
  578. dst_key_name(const dst_key_t *key);
  579. unsigned int
  580. dst_key_size(const dst_key_t *key);
  581. unsigned int
  582. dst_key_proto(const dst_key_t *key);
  583. unsigned int
  584. dst_key_alg(const dst_key_t *key);
  585. isc_uint32_t
  586. dst_key_flags(const dst_key_t *key);
  587. dns_keytag_t
  588. dst_key_id(const dst_key_t *key);
  589. dns_keytag_t
  590. dst_key_rid(const dst_key_t *key);
  591. dns_rdataclass_t
  592. dst_key_class(const dst_key_t *key);
  593. isc_boolean_t
  594. dst_key_isprivate(const dst_key_t *key);
  595. isc_boolean_t
  596. dst_key_iszonekey(const dst_key_t *key);
  597. isc_boolean_t
  598. dst_key_isnullkey(const dst_key_t *key);
  599. isc_result_t
  600. dst_key_buildfilename(const dst_key_t *key, int type,
  601. const char *directory, isc_buffer_t *out);
  602. /*%<
  603. * Generates the filename used by dst to store the specified key.
  604. * If directory is NULL, the current directory is assumed.
  605. *
  606. * Requires:
  607. *\li "key" is a valid key
  608. *\li "type" is either DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or 0 for no suffix.
  609. *\li "out" is a valid buffer
  610. *
  611. * Ensures:
  612. *\li the file name will be written to "out", and the used pointer will
  613. * be advanced.
  614. */
  615. isc_result_t
  616. dst_key_sigsize(const dst_key_t *key, unsigned int *n);
  617. /*%<
  618. * Computes the size of a signature generated by the given key.
  619. *
  620. * Requires:
  621. *\li "key" is a valid key.
  622. *\li "n" is not NULL
  623. *
  624. * Returns:
  625. *\li #ISC_R_SUCCESS
  626. *\li DST_R_UNSUPPORTEDALG
  627. *
  628. * Ensures:
  629. *\li "n" stores the size of a generated signature
  630. */
  631. isc_result_t
  632. dst_key_secretsize(const dst_key_t *key, unsigned int *n);
  633. /*%<
  634. * Computes the size of a shared secret generated by the given key.
  635. *
  636. * Requires:
  637. *\li "key" is a valid key.
  638. *\li "n" is not NULL
  639. *
  640. * Returns:
  641. *\li #ISC_R_SUCCESS
  642. *\li DST_R_UNSUPPORTEDALG
  643. *
  644. * Ensures:
  645. *\li "n" stores the size of a generated shared secret
  646. */
  647. isc_uint16_t
  648. dst_region_computeid(const isc_region_t *source, unsigned int alg);
  649. isc_uint16_t
  650. dst_region_computerid(const isc_region_t *source, unsigned int alg);
  651. /*%<
  652. * Computes the (revoked) key id of the key stored in the provided
  653. * region with the given algorithm.
  654. *
  655. * Requires:
  656. *\li "source" contains a valid, non-NULL region.
  657. *
  658. * Returns:
  659. *\li the key id
  660. */
  661. isc_uint16_t
  662. dst_key_getbits(const dst_key_t *key);
  663. /*%<
  664. * Get the number of digest bits required (0 == MAX).
  665. *
  666. * Requires:
  667. * "key" is a valid key.
  668. */
  669. void
  670. dst_key_setbits(dst_key_t *key, isc_uint16_t bits);
  671. /*%<
  672. * Set the number of digest bits required (0 == MAX).
  673. *
  674. * Requires:
  675. * "key" is a valid key.
  676. */
  677. isc_result_t
  678. dst_key_setflags(dst_key_t *key, isc_uint32_t flags);
  679. /*
  680. * Set the key flags, and recompute the key ID.
  681. *
  682. * Requires:
  683. * "key" is a valid key.
  684. */
  685. isc_result_t
  686. dst_key_getnum(const dst_key_t *key, int type, isc_uint32_t *valuep);
  687. /*%<
  688. * Get a member of the numeric metadata array and place it in '*valuep'.
  689. *
  690. * Requires:
  691. * "key" is a valid key.
  692. * "type" is no larger than DST_MAX_NUMERIC
  693. * "timep" is not null.
  694. */
  695. void
  696. dst_key_setnum(dst_key_t *key, int type, isc_uint32_t value);
  697. /*%<
  698. * Set a member of the numeric metadata array.
  699. *
  700. * Requires:
  701. * "key" is a valid key.
  702. * "type" is no larger than DST_MAX_NUMERIC
  703. */
  704. void
  705. dst_key_unsetnum(dst_key_t *key, int type);
  706. /*%<
  707. * Flag a member of the numeric metadata array as "not set".
  708. *
  709. * Requires:
  710. * "key" is a valid key.
  711. * "type" is no larger than DST_MAX_NUMERIC
  712. */
  713. isc_result_t
  714. dst_key_gettime(const dst_key_t *key, int type, isc_stdtime_t *timep);
  715. /*%<
  716. * Get a member of the timing metadata array and place it in '*timep'.
  717. *
  718. * Requires:
  719. * "key" is a valid key.
  720. * "type" is no larger than DST_MAX_TIMES
  721. * "timep" is not null.
  722. */
  723. void
  724. dst_key_settime(dst_key_t *key, int type, isc_stdtime_t when);
  725. /*%<
  726. * Set a member of the timing metadata array.
  727. *
  728. * Requires:
  729. * "key" is a valid key.
  730. * "type" is no larger than DST_MAX_TIMES
  731. */
  732. void
  733. dst_key_unsettime(dst_key_t *key, int type);
  734. /*%<
  735. * Flag a member of the timing metadata array as "not set".
  736. *
  737. * Requires:
  738. * "key" is a valid key.
  739. * "type" is no larger than DST_MAX_TIMES
  740. */
  741. isc_result_t
  742. dst_key_getprivateformat(const dst_key_t *key, int *majorp, int *minorp);
  743. /*%<
  744. * Get the private key format version number. (If the key does not have
  745. * a private key associated with it, the version will be 0.0.) The major
  746. * version number is placed in '*majorp', and the minor version number in
  747. * '*minorp'.
  748. *
  749. * Requires:
  750. * "key" is a valid key.
  751. * "majorp" is not NULL.
  752. * "minorp" is not NULL.
  753. */
  754. void
  755. dst_key_setprivateformat(dst_key_t *key, int major, int minor);
  756. /*%<
  757. * Set the private key format version number.
  758. *
  759. * Requires:
  760. * "key" is a valid key.
  761. */
  762. #define DST_KEY_FORMATSIZE (DNS_NAME_FORMATSIZE + DNS_SECALG_FORMATSIZE + 7)
  763. void
  764. dst_key_format(const dst_key_t *key, char *cp, unsigned int size);
  765. /*%<
  766. * Write the uniquely identifying information about the key (name,
  767. * algorithm, key ID) into a string 'cp' of size 'size'.
  768. */
  769. isc_buffer_t *
  770. dst_key_tkeytoken(const dst_key_t *key);
  771. /*%<
  772. * Return the token from the TKEY request, if any. If this key was
  773. * not negotiated via TKEY, return NULL.
  774. *
  775. * Requires:
  776. * "key" is a valid key.
  777. */
  778. isc_result_t
  779. dst_key_dump(dst_key_t *key, isc_mem_t *mctx, char **buffer, int *length);
  780. /*%<
  781. * Allocate 'buffer' and dump the key into it in base64 format. The buffer
  782. * is not NUL terminated. The length of the buffer is returned in *length.
  783. *
  784. * 'buffer' needs to be freed using isc_mem_put(mctx, buffer, length);
  785. *
  786. * Requires:
  787. * 'buffer' to be non NULL and *buffer to be NULL.
  788. * 'length' to be non NULL and *length to be zero.
  789. *
  790. * Returns:
  791. * ISC_R_SUCCESS
  792. * ISC_R_NOMEMORY
  793. * ISC_R_NOTIMPLEMENTED
  794. * others.
  795. */
  796. isc_result_t
  797. dst_key_restore(dns_name_t *name, unsigned int alg, unsigned int flags,
  798. unsigned int protocol, dns_rdataclass_t rdclass,
  799. isc_mem_t *mctx, const char *keystr, dst_key_t **keyp);
  800. ISC_LANG_ENDDECLS
  801. #endif /* DST_DST_H */