diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.am | 22 | ||||
| -rw-r--r-- | doc/cha-cert-auth.texi | 114 | ||||
| -rw-r--r-- | doc/cha-functions.texi | 10 | ||||
| -rw-r--r-- | doc/invoke-gnutls-cli.texi | 12 | ||||
| -rw-r--r-- | doc/manpages/Makefile.am | 17 | ||||
| -rwxr-xr-x | doc/scripts/getfuncs.pl | 2 |
6 files changed, 133 insertions, 44 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index b375353087..ac4ee64a8d 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -190,18 +190,21 @@ MAINTAINERCLEANFILES = gnutls_TEXINFOS += gnutls-api.texi x509-api.texi pgp-api.texi \ pkcs12-api.texi pkcs11-api.texi abstract-api.texi tpm-api.texi \ - compat-api.texi dtls-api.texi crypto-api.texi ocsp-api.texi + compat-api.texi dtls-api.texi crypto-api.texi ocsp-api.texi \ + dane-api.texi MAINTAINERCLEANFILES += gnutls-api.texi x509-api.texi pgp-api.texi \ pkcs12-api.texi pkcs11-api.texi abstract-api.texi tpm-api.texi \ - compat-api.texi dtls-api.texi crypto-api.texi ocsp-api.texi + compat-api.texi dtls-api.texi crypto-api.texi ocsp-api.texi \ + dane-api.texi HEADER_FILES = $(top_srcdir)/lib/includes/gnutls/gnutls.h.in \ $(top_srcdir)/lib/includes/gnutls/x509.h $(top_srcdir)/lib/includes/gnutls/openpgp.h \ $(top_srcdir)/lib/includes/gnutls/pkcs12.h $(top_srcdir)/lib/includes/gnutls/pkcs11.h \ $(top_srcdir)/lib/includes/gnutls/abstract.h $(top_srcdir)/lib/includes/gnutls/compat.h \ $(top_srcdir)/lib/includes/gnutls/dtls.h $(top_srcdir)/lib/includes/gnutls/crypto.h \ - $(top_srcdir)/lib/includes/gnutls/ocsp.h $(top_srcdir)/lib/includes/gnutls/tpm.h + $(top_srcdir)/lib/includes/gnutls/ocsp.h $(top_srcdir)/lib/includes/gnutls/tpm.h \ + $(top_srcdir)/libdane/includes/gnutls/dane.h gnutls-api.texi: $(top_srcdir)/lib/includes/gnutls/gnutls.h.in echo "" > $@-tmp @@ -214,6 +217,17 @@ gnutls-api.texi: $(top_srcdir)/lib/includes/gnutls/gnutls.h.in done mv -f $@-tmp $@ +dane-api.texi: $(top_srcdir)/libdane/includes/gnutls/dane.h + echo "" > $@-tmp + for i in `$(top_srcdir)/doc/scripts/getfuncs.pl <$^|sort|uniq`; do \ + echo -n "Creating documentation for $$i... " && \ + $(srcdir)/scripts/gdoc -texinfo \ + -function $$i \ + $(top_srcdir)/libdane/*.c >> $@-tmp 2>/dev/null && \ + echo "ok"; \ + done + mv -f $@-tmp $@ + x509-api.texi: $(top_srcdir)/lib/includes/gnutls/x509.h echo "" > $@-tmp for i in `$(top_srcdir)/doc/scripts/getfuncs.pl <$(top_srcdir)/lib/includes/gnutls/x509.h|sort|uniq`; do \ @@ -375,7 +389,7 @@ enums.texi: $(HEADER_FILES) gnutls_TEXINFOS += $(ENUMS) $(FUNCS) DISTCLEANFILES += $(ENUMS) stamp_enums stamp_functions -stamp_functions: gnutls-api.texi x509-api.texi pgp-api.texi pkcs12-api.texi tpm-api.texi pkcs11-api.texi abstract-api.texi compat-api.texi dtls-api.texi crypto-api.texi ocsp-api.texi tpm-api.texi +stamp_functions: gnutls-api.texi x509-api.texi pgp-api.texi pkcs12-api.texi tpm-api.texi pkcs11-api.texi abstract-api.texi compat-api.texi dtls-api.texi crypto-api.texi ocsp-api.texi tpm-api.texi dane-api.texi -mkdir functions for i in $^; do \ $(srcdir)/scripts/split-texi.pl functions < $$i; \ diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi index 46195f9fe0..05246e14ab 100644 --- a/doc/cha-cert-auth.texi +++ b/doc/cha-cert-auth.texi @@ -60,6 +60,7 @@ to use this key exchange algorithm. @menu * X.509 certificates:: * OpenPGP certificates:: +* Advanced certificate verification:: * Digital signatures:: @end menu @@ -88,7 +89,6 @@ acceptable. The framework is illustrated on @ref{fig:x509}. * X.509 distinguished names:: * Verifying X.509 certificate paths:: * Verifying a certificate in the context of TLS session:: -* Verifying a certificate using trust on first use authentication:: @end menu @node X.509 certificate structure @@ -301,42 +301,6 @@ about the peer's identity. It is required to verify if the certificate's owner is the one you expect. For more information consult @ref{gnutls_x509_crt_check_hostname}, section @ref{ex:verify} for an example, and @xcite{RFC2818}. -@node Verifying a certificate using trust on first use authentication -@subsection Verifying a certificate using trust on first use authentication -@cindex verifying certificate paths -@cindex SSH-style authentication -@cindex Trust on first use -@cindex Key pinning -@tindex gnutls_certificate_verify_flags - -It is possible to use a trust on first use (similar to SSH) authentication -method in GnuTLS. That is the concept used by the SSH programs, where the -public key of the peer is not verified, or verified in an out-of-bound way, -but subsequent connections to the same peer require the public key to -remain the same. Such a system in combination with the typical CA -verification of a certificate, and OCSP revocation checks, -can help to provide multiple factor verification, where a single point of -failure is not enough to compromise the system. For example a server compromise -may be detected using OCSP, and a CA compromise can be detected using -the trust on first use method. -Such a hybrid system with X.509 and trust on first use authentication is -shown in @ref{Simple client example with SSH-style certificate verification}. - -@showfuncdesc{gnutls_verify_stored_pubkey} -@showfuncdesc{gnutls_store_pubkey} - -In addition to the above the @funcref{gnutls_store_commitment} can be -used to implement a key-pinning architecture as in @xcite{KEYPIN}. -This provides a way for web server to commit on a public key that is -not yet active. - -@showfuncdesc{gnutls_store_commitment} - -The storage and verification functions may be used with the default -text file based back-end, or another back-end may be specified. That -should contain storage and retrieval functions and specified as below. - -@showfuncE{gnutls_tdb_init,gnutls_tdb_deinit,gnutls_tdb_set_verify_func,gnutls_tdb_set_store_func,gnutls_tdb_set_store_commitment_func} @node OpenPGP certificates @section @acronym{OpenPGP} certificates @@ -474,7 +438,83 @@ to verify the signatures in the certificate sent by the peer. @showfuncdesc{gnutls_certificate_set_openpgp_keyring_file} +@node Advanced certificate verification +@section Advanced certificate verification +@cindex Certificate verification + +@menu +* Verifying a certificate using trust on first use authentication:: +* Verifying a certificate using DANE (DNSSEC):: +@end menu + +@node Verifying a certificate using trust on first use authentication +@subsection Verifying a certificate using trust on first use authentication +@cindex verifying certificate paths +@cindex SSH-style authentication +@cindex Trust on first use +@cindex Key pinning +@tindex gnutls_certificate_verify_flags + +It is possible to use a trust on first use (TOFU) authentication +method in GnuTLS. That is the concept used by the SSH programs, where the +public key of the peer is not verified, or verified in an out-of-bound way, +but subsequent connections to the same peer require the public key to +remain the same. Such a system in combination with the typical CA +verification of a certificate, and OCSP revocation checks, +can help to provide multiple factor verification, where a single point of +failure is not enough to compromise the system. For example a server compromise +may be detected using OCSP, and a CA compromise can be detected using +the trust on first use method. +Such a hybrid system with X.509 and trust on first use authentication is +shown in @ref{Simple client example with SSH-style certificate verification}. + +@showfuncdesc{gnutls_verify_stored_pubkey} +@showfuncdesc{gnutls_store_pubkey} + +In addition to the above the @funcref{gnutls_store_commitment} can be +used to implement a key-pinning architecture as in @xcite{KEYPIN}. +This provides a way for web server to commit on a public key that is +not yet active. + +@showfuncdesc{gnutls_store_commitment} + +The storage and verification functions may be used with the default +text file based back-end, or another back-end may be specified. That +should contain storage and retrieval functions and specified as below. + +@showfuncE{gnutls_tdb_init,gnutls_tdb_deinit,gnutls_tdb_set_verify_func,gnutls_tdb_set_store_func,gnutls_tdb_set_store_commitment_func} + +@node Verifying a certificate using DANE (DNSSEC) +@subsection Verifying a certificate using DANE (DNSSEC) +@cindex verifying certificate paths +@cindex DANE +@cindex DNSSEC +@tindex gnutls_certificate_verify_flags + +The DANE protocol is a protocol that can be used to verify TLS certificates +using the DNS (or better DNSSEC) protocols. The DNS security extensions (DNSSEC) +provide an alternative public key infrastructure to the commercial CAs that +are typically used to sign TLS certificates. The DANE protocol takes advantage +of the DNSSEC infrastructure to verify TLS certificates. This can be +in addition to the verification by commercial CA infrastructure or +could even replace it where DNSSEC is deployed. + +The DANE functionality is provided by the @code{libdane} library that is shipped +with GnuTLS and the function prototypes are in @code{gnutls/dane.h}. The +high level verification functions are shown below. + +@showfuncdesc{dane_verify_crt} + +@showfuncB{dane_verify_session_crt,dane_strerror} + +The allowed flags for the verification function follow. + +@showenumdesc{dane_verify_flags_t,The DANE verification flags.} + +The following flags are returned by the verify functions to +indicate the status of the verification. +@showenumdesc{dane_verify_status_t,The DANE verification status flags.} @node Digital signatures diff --git a/doc/cha-functions.texi b/doc/cha-functions.texi index 786c2503e9..549767c84b 100644 --- a/doc/cha-functions.texi +++ b/doc/cha-functions.texi @@ -12,6 +12,7 @@ * PKCS 11 API:: * TPM API:: * Abstract key API:: +* DANE API:: * Cryptographic API:: * Compatibility API:: @end menu @@ -92,6 +93,15 @@ Their prototypes lie in @file{gnutls/abstract.h}. @include abstract-api.texi +@node DANE API +@section DANE API + +The following functions are to be used for DANE certificate verification. +Their prototypes lie in @file{gnutls/dane.h}. Note that you need to link +with the @code{libdane} library to use them. + +@include dane-api.texi + @node Cryptographic API @section Cryptographic API diff --git a/doc/invoke-gnutls-cli.texi b/doc/invoke-gnutls-cli.texi index dad4069c4f..91f597097b 100644 --- a/doc/invoke-gnutls-cli.texi +++ b/doc/invoke-gnutls-cli.texi @@ -7,7 +7,7 @@ # # DO NOT EDIT THIS FILE (invoke-gnutls-cli.texi) # -# It has been AutoGen-ed October 4, 2012 at 07:18:42 PM by AutoGen 5.16 +# It has been AutoGen-ed October 6, 2012 at 03:27:13 AM by AutoGen 5.16 # From the definitions ../src/cli-args.def # and the template file agtexi-cmd.tpl @end ignore @@ -45,6 +45,8 @@ USAGE: gnutls-cli [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... [hostname] - may appear multiple times --tofu Enable trust on first use authentication - disabled as --no-tofu + --dane Enable DANE certificate verification (DNSSEC) + - disabled as --no-dane --ocsp Enable OCSP certificate verification - disabled as --no-ocsp -r, --resume Establish a session and resume @@ -123,6 +125,14 @@ Specifies the debug level. This is the ``enable trust on first use authentication'' option. This option will, in addition to certificate authentication, perform authentication based on previously seen public keys, a model similar to SSH authentication. +@anchor{gnutls-cli dane} +@subheading dane option +@cindex gnutls-cli-dane + +This is the ``enable dane certificate verification (dnssec)'' option. +This option will, in addition to certificate authentication using +the trusted CAs, verify the server certificates using on the DANE information +available via DNSSEC. @anchor{gnutls-cli ocsp} @subheading ocsp option @cindex gnutls-cli-ocsp diff --git a/doc/manpages/Makefile.am b/doc/manpages/Makefile.am index fdf3587986..47dade5947 100644 --- a/doc/manpages/Makefile.am +++ b/doc/manpages/Makefile.am @@ -31,7 +31,8 @@ HEADER_FILES = $(top_srcdir)/lib/includes/gnutls/gnutls.h.in \ $(top_srcdir)/lib/includes/gnutls/pkcs12.h $(top_srcdir)/lib/includes/gnutls/pkcs11.h \ $(top_srcdir)/lib/includes/gnutls/abstract.h $(top_srcdir)/lib/includes/gnutls/compat.h \ $(top_srcdir)/lib/includes/gnutls/dtls.h $(top_srcdir)/lib/includes/gnutls/crypto.h \ - $(top_srcdir)/lib/includes/gnutls/ocsp.h $(top_srcdir)/lib/includes/gnutls/tpm.h + $(top_srcdir)/lib/includes/gnutls/ocsp.h $(top_srcdir)/lib/includes/gnutls/tpm.h \ + $(top_srcdir)/libdane/includes/gnutls/dane.h # Note that our .def files depend on autogen # supporting the @subheading texi keyword. This @@ -892,6 +893,20 @@ stamp_mans: $(HEADER_FILES) echo -n "."; \ done @echo "" + @echo -n "Creating man pages for dane.h..." && \ + for i in `$(top_srcdir)/doc/scripts/getfuncs.pl <$(top_srcdir)/libdane/includes/gnutls/dane.h`; do \ + $(top_srcdir)/doc/scripts/gdoc -man \ + -module $(PACKAGE) -sourceversion $(VERSION) \ + -bugsto $(PACKAGE_BUGREPORT) \ + -pkg-name "$(PACKAGE_NAME)" \ + -include "gnutls/dane.h" \ + -seeinfo $(PACKAGE) -verbatimcopying \ + -copyright "2012 Free Software Foundation, Inc." \ + -function $$i \ + $(top_srcdir)/libdane/*.c > $$i.3 2>/dev/null && \ + echo -n "."; \ + done + @echo "" @echo -n "Creating man pages for x509.h..." && \ for i in `$(top_srcdir)/doc/scripts/getfuncs.pl <$(top_srcdir)/lib/includes/gnutls/x509.h`; do \ $(top_srcdir)/doc/scripts/gdoc -man \ diff --git a/doc/scripts/getfuncs.pl b/doc/scripts/getfuncs.pl index 383924045f..9e7680558a 100755 --- a/doc/scripts/getfuncs.pl +++ b/doc/scripts/getfuncs.pl @@ -42,7 +42,7 @@ while ($line=<STDIN>) { $func = $1; } - if ($func ne '' && $func =~ m/gnutls_.*/) { + if ($func ne '' && ($func =~ m/gnutls_.*/ || $func =~ m/dane_.*/)) { print $func . "\n"; } } |