added man pages for some helper functions

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
 

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

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).
 

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 <getdns.h>
+
+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)
+

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.h>
+
+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)
+

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.h>
+
+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)
+

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.h>
+
+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)
+

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