From f354ec786fe7caf8ec389b904ce681741ddb75a3 Mon Sep 17 00:00:00 2001 From: Glen Wiley Date: Thu, 24 Apr 2014 10:13:19 -0400 Subject: [PATCH] added man pages for some helper functions --- doc/Makefile.in | 4 +- doc/getdns_convert.3.in | 2 +- doc/getdns_dict.3.in | 5 +- doc/getdns_display_ip_address.3.in | 68 +++++++++++++++++++ doc/getdns_pretty_print_dict.3.in | 68 +++++++++++++++++++ doc/getdns_root_trust_anchor.3.in | 72 ++++++++++++++++++++ doc/getdns_validate_dnssec.3.in | 102 +++++++++++++++++++++++++++++ doc/libgetdns.3.in | 2 + 8 files changed, 318 insertions(+), 5 deletions(-) create mode 100644 doc/getdns_display_ip_address.3.in create mode 100644 doc/getdns_pretty_print_dict.3.in create mode 100644 doc/getdns_root_trust_anchor.3.in create mode 100644 doc/getdns_validate_dnssec.3.in diff --git a/doc/Makefile.in b/doc/Makefile.in index 92b6b12f..f24a8486 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -2,7 +2,7 @@ # @configure_input@ # # -# Copyright (c) 2013, Verisign, Inc., NLNet Labs +# Copyright (c) 2013, Verisign, Inc., NLnet Labs # All rights reserved. # # Redistribution and use in source and binary forms, with or without @@ -47,7 +47,7 @@ EDITS=-e 's/@''version@/$(version)/g' DOXYGEN = @DOXYGEN@ DOCDIRS = html latex man -MANPAGES3 = libgetdns.3 getdns_address.3 getdns_cancel_callback.3 getdns_context.3 getdns_context_create.3 getdns_context_set.3 getdns_convert.3 getdns_dict.3 getdns_dict_get.3 getdns_dict_set.3 getdns_free_sync_request_memory.3 getdns_general.3 getdns_hostname.3 getdns_list.3 getdns_list_get.3 getdns_list_set.3 getdns_service.3 +MANPAGES3 = libgetdns.3 getdns_address.3 getdns_cancel_callback.3 getdns_context.3 getdns_context_create.3 getdns_context_set.3 getdns_convert.3 getdns_dict.3 getdns_dict_get.3 getdns_dict_set.3 getdns_display_ip_address.3 getdns_free_sync_request_memory.3 getdns_general.3 getdns_hostname.3 getdns_list.3 getdns_list_get.3 getdns_list_set.3 getdns_pretty_print_dict.3 getdns_root_trust_anchor.3 getdns_service.3 getdns_validate_dnssec.3 default: all diff --git a/doc/getdns_convert.3.in b/doc/getdns_convert.3.in index 8434fd5e..7b5a0576 100644 --- a/doc/getdns_convert.3.in +++ b/doc/getdns_convert.3.in @@ -1,6 +1,6 @@ .\" The "BSD-New" License .\" -.\" Copyright (c) 2013, NLNet Labs, Verisign, Inc. +.\" Copyright (c) 2013, NLnet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without diff --git a/doc/getdns_dict.3.in b/doc/getdns_dict.3.in index 3d6adc96..efbb6c09 100644 --- a/doc/getdns_dict.3.in +++ b/doc/getdns_dict.3.in @@ -1,6 +1,6 @@ .\" The "BSD-New" License .\" -.\" Copyright (c) 2013, NLNet Labs, Verisign, Inc. +.\" Copyright (c) 2013, NLnet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -86,5 +86,6 @@ TBD .BR libgetdns (3), .BR getdns_dict_get (3), .BR getdns_dict_set (3), -.BR getdns_list (3). +.BR getdns_list (3), +.BR getdns_pretty_print_dict (3). diff --git a/doc/getdns_display_ip_address.3.in b/doc/getdns_display_ip_address.3.in new file mode 100644 index 00000000..71d6b1bb --- /dev/null +++ b/doc/getdns_display_ip_address.3.in @@ -0,0 +1,68 @@ +.\" The "BSD-New" License +.\" +.\" Copyright (c) 2013, NLnet Labs, Verisign, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are met: +.\" * Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" * Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" * Neither the names of the copyright holders nor the +.\" names of its contributors may be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +.\" DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +.\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" + +.TH getdns_display_ip_address 3 "@date@" "getdns @version@" getdns +.SH NAME +.B getdns_display_ip_address + +.SH LIBRARY +DNS Resolver library (libgetdns, -lgetdns) + +.SH SYNOPSIS +#include + +char * +.br +.B getdns_display_ip_address +(const getdns_bindata *ipv4_or_ipv6_addr) + +.SH DESCRIPTION + +.LP +This helper function returns a nicely formatted string representation of the IPv4 or +IPv6 address. The length of the bindata is used to determine whether the address +is IPv4 or IPv6. + +.HP 3 +.I ipv4_or_ipv6_addr +.RP +bindata of the address to print + +.HP +.SH "RETURN VALUES" + +Returns a string representation of the IP address (allocated using the system +allocator - malloc), the caller is responsible for freeing the storage using free(). + +.SH EXAMPLES + +TBD + +.SH SEE ALSO +.BR libgetdns (3) + diff --git a/doc/getdns_pretty_print_dict.3.in b/doc/getdns_pretty_print_dict.3.in new file mode 100644 index 00000000..786b342c --- /dev/null +++ b/doc/getdns_pretty_print_dict.3.in @@ -0,0 +1,68 @@ +.\" The "BSD-New" License +.\" +.\" Copyright (c) 2013, NLnet Labs, Verisign, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are met: +.\" * Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" * Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" * Neither the names of the copyright holders nor the +.\" names of its contributors may be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +.\" DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +.\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" + +.TH getdns_pretty_print_dict 3 "@date@" "getdns @version@" getdns +.SH NAME +.B getdns_pretty_print_dict + +.SH LIBRARY +DNS Resolver library (libgetdns, -lgetdns) + +.SH SYNOPSIS +#include + +getdns_list * +.br +.B getdns_pretty_print_dict +(const getdns_dict *this_dict) + +.SH DESCRIPTION + +.LP +Helper function that returns a string of nicely formatted data including all of the +elements in the dict. + +.HP 3 +.I this_dict +.RP +the dictionary to render as a string + +.HP +.SH "RETURN VALUES" + +Returns a string that the calling function must free (it is allocated using the +system allocator not the user defined allocator). Returns NULL if there is an error. + +.SH EXAMPLES + +TBD + +.SH SEE ALSO +.BR getdns_dict (3) +.BR libgetdns (3) + diff --git a/doc/getdns_root_trust_anchor.3.in b/doc/getdns_root_trust_anchor.3.in new file mode 100644 index 00000000..868af38b --- /dev/null +++ b/doc/getdns_root_trust_anchor.3.in @@ -0,0 +1,72 @@ +.\" The "BSD-New" License +.\" +.\" Copyright (c) 2013, NLnet Labs, Verisign, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are met: +.\" * Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" * Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" * Neither the names of the copyright holders nor the +.\" names of its contributors may be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +.\" DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +.\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" + +.TH getdns_root_trust_anchor 3 "@date@" "getdns @version@" getdns +.SH NAME +.B getdns_root_trust_anchor + +.SH LIBRARY +DNS Resolver library (libgetdns, -lgetdns) + +.SH SYNOPSIS +#include + +getdns_list * +.br +.B getdns_root_trust_anchor +(time_t *utc_date_of_anchor) + +.SH DESCRIPTION + +.LP +If an application wants the API to perform DNSSEC validation without using the +extensions, it can use the getdns_validate_dnssec() helper function. The API +will use the resource records in bundle_of_support_records to construct the +validation chain and the DNSKEY or DS records in trust_anchor_records as trust +anchors. The default list of trust anchor records that is used by the library +to validate DNSSEC can be retrieved by using the getdns_root_trust_anchor +helper function. + +.HP 3 +.I utc_date_of_anchor +.RP +time the trust anchors were obtained in epoch seconds (on success) + +.HP +.SH "RETURN VALUES" + +Returns the default list of trust anchor records used by the library to validate DNSSEC or NULL if no default trust anchors are available. + +.SH EXAMPLES + +TBD + +.SH SEE ALSO +.BR getdns_validate_dnssec (3) +.BR libgetdns (3) + diff --git a/doc/getdns_validate_dnssec.3.in b/doc/getdns_validate_dnssec.3.in new file mode 100644 index 00000000..b590a333 --- /dev/null +++ b/doc/getdns_validate_dnssec.3.in @@ -0,0 +1,102 @@ +.\" The "BSD-New" License +.\" +.\" Copyright (c) 2013, NLnet Labs, Verisign, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are met: +.\" * Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" * Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" * Neither the names of the copyright holders nor the +.\" names of its contributors may be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +.\" DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +.\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" + +.TH getdns_validate_dnssec 3 "@date@" "getdns @version@" getdns +.SH NAME +.B getdns_validate_dnssec + +.SH LIBRARY +DNS Resolver library (libgetdns, -lgetdns) + +.SH SYNOPSIS +#include + +getdns_return_t +.br +.B getdns_validate_dnssec +(getdns_list *record_to_validate, +.br +.RS 3 +getdns_list *bundle_of_support_records, +.br +getdns_list *trust_anchor_records) +.RE + +.SH DESCRIPTION + +.LP +If an application wants the API to perform DNSSEC validation without using the +extensions, it can use the getdns_validate_dnssec() helper function. The API +will use the resource records in bundle_of_support_records to construct the +validation chain and the DNSKEY or DS records in trust_anchor_records as trust +anchors. The default list of trust anchor records that is used by the library +to validate DNSSEC can be retrieved by using the getdns_root_trust_anchor +helper function. + +.HP 3 +.I record_to_validate +.RP +the resource record being validated + +.HP 3 +.I bundle_of_support_records +.RP +records used to construct the validation chain + +.HP 3 +.I trust_anchor_records +.RP +trust anchor records to use for the validation + +.HP +.SH "RETURN VALUES" + +.LP +.B GETDNS_DNSSEC_BOGUS +the DNSSEC signature is bogus +.LP +.B GETDNS_DNSSEC_INDETERMINATE +validation could not be completed +.LP +.B GETDNS_DNSSEC_INSECURE +one or more pieces of the validation chain are demonstrably incorrect +.LP +.B GETDNS_DNSSEC_SECURE +validation succeeded +.LP +.B GETDNS_RETURN_MEMORY_ERROR +an attempt to allocate memory failed + +.SH EXAMPLES + +TBD + +.SH SEE ALSO +.BR getdns_root_trust_anchor (3) +.BR libgetdns (3) + diff --git a/doc/libgetdns.3.in b/doc/libgetdns.3.in index 68ec72c0..2e93f1e6 100644 --- a/doc/libgetdns.3.in +++ b/doc/libgetdns.3.in @@ -808,7 +808,9 @@ TBD .BR getdns_general (3), .BR getdns_hostname (3), .BR getdns_list (3), +.BR getdns_root_trust_anchor (3) .BR getdns_service (3) +.BR getdns_validate_dnssec (3) .SH REPORTING PROBLEMS Bug reports should be sent to the getdns-bugs@getdns.net