From: Nikos Mavrogiannopoulos Date: Thu, 24 Nov 2011 16:54:11 +0000 (+0100) Subject: updates in texi and tex documentation. X-Git-Tag: gnutls_3_0_9~46 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=911d9fd67d3031036324187f9f8ed02f7bdca99d;p=thirdparty%2Fgnutls.git updates in texi and tex documentation. --- diff --git a/doc/cha-cert-auth2.texi b/doc/cha-cert-auth2.texi index 93a771a478..1a623c3b3f 100644 --- a/doc/cha-cert-auth2.texi +++ b/doc/cha-cert-auth2.texi @@ -710,19 +710,19 @@ on them. Some examples on how to use p11tool are illustrated in the following paragraphs. -@subsubsection List all tokens +@subsubheading List all tokens @smallexample $ p11tool --list-tokens @end smallexample -@subsubsection List all objects +@subsubheading List all objects The following command will list all objects in a token. The @code{--login} is required to show objects marked as private. @smallexample $ p11tool --login --list-all @end smallexample -@subsubsection Exporting an object +@subsubheading Exporting an object To retrieve an object stored in the card use the following command. Note however that objects marked as sensitive (typically PKCS #11 private keys) are not allowed to be extracted from the token. @@ -730,7 +730,7 @@ are not allowed to be extracted from the token. $ p11tool --login --export [OBJECT URL] @end smallexample -@subsubsection Copy an object to a token +@subsubheading Copy an object to a token To copy an object, such as a certificate or private key to a token use the following command. @smallexample @@ -778,6 +778,13 @@ gnutls_privkey_t abs_key; @} @end example +@menu +* Abstract public keys:: +* Abstract private keys:: +@end menu + + +@node Abstract public keys @subsection Public keys An abstract @code{gnutls_pubkey_t} can be initialized using the functions below. It can be imported through @@ -793,6 +800,7 @@ information over a public key. @showfuncC{gnutls_pubkey_get_pk_algorithm,gnutls_pubkey_get_preferred_hash_algorithm,gnutls_pubkey_get_key_id} +@node Abstract private keys @subsection Private keys An abstract @code{gnutls_privkey_t} can be initialized using the functions below. It can be imported through diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi index 0699c53ad3..1c73f4ba44 100644 --- a/doc/cha-gtls-app.texi +++ b/doc/cha-gtls-app.texi @@ -5,6 +5,7 @@ * Introduction to the library:: * Preparation:: * Session initialization:: +* Associating the credentials:: * Setting up the transport layer:: * TLS handshake:: * Data transfer and termination:: @@ -288,8 +289,18 @@ current session using @funcref{gnutls_credentials_set}. @showfuncdesc{gnutls_credentials_set} -@subsection Associating the credentials -@subsubsection Certificates +@node Associating the credentials +@section Associating the credentials + +@menu +* Certificate credentials:: +* SRP credentials:: +* PSK credentials:: +* Anonymous credentials:: +@end menu + +@node Certificate credentials +@subsection Certificates When using certificates the server is required to have at least one certificate and private key pair. A client may or may not have such a @@ -361,7 +372,8 @@ for the acceptable security levels.} than the elliptic curves counterpart requires parameters to be generated and associated with a credentials structure by the server (see @ref{Parameter generation}). -@subsubsection SRP +@node SRP credentials +@subsection SRP The initialization functions in SRP credentials differ between client and server. @@ -388,7 +400,8 @@ to set an appropriate callback. @showfuncdesc{gnutls_srp_set_server_credentials_function} -@subsubsection PSK +@node PSK credentials +@subsection PSK The initialization functions in PSK credentials differ between client and server. @@ -425,7 +438,8 @@ the hint, for example in the callback function, using @showfuncC{gnutls_psk_set_server_credentials_function,gnutls_psk_set_server_credentials_hint,gnutls_psk_client_get_hint} -@subsubsection Anonymous +@node Anonymous credentials +@subsection Anonymous The initialization functions for the credentials are shown below. @showfuncD{gnutls_anon_allocate_server_credentials,gnutls_anon_allocate_client_credentials,gnutls_anon_free_server_credentials,gnutls_anon_free_client_credentials} @@ -484,6 +498,12 @@ message. This requires the @funcref{gnutls_transport_set_pull_timeout_function} @showfuncdesc{gnutls_transport_set_pull_timeout_function} +@menu +* Asynchronous operation:: +* DTLS sessions:: +@end menu + +@node Asynchronous operation @subsection Asynchronous operation @acronym{GnuTLS} can be used with asynchronous socket or event-driven programming. During a TLS protocol session @acronym{GnuTLS} does not block for anything except @@ -513,6 +533,7 @@ required by the protocol. To prevent those timers from blocking a DTLS handshake the @funcref{gnutls_init} should be called with the @code{GNUTLS_NONBLOCK} flag (see @ref{Session initialization}). +@node DTLS sessions @subsection DTLS sessions Because datagram TLS can operate over connections where the peer diff --git a/doc/cha-internals.texi b/doc/cha-internals.texi index 2347efd843..81eb8e6c14 100644 --- a/doc/cha-internals.texi +++ b/doc/cha-internals.texi @@ -117,7 +117,12 @@ together with the extension number they handle, they have to be registered using @funcintref{_gnutls_ext_register} in @code{gnutls_extensions.c} typically within @funcintref{_gnutls_ext_init}. -@subsection Adding a New TLS Extension +@menu +* Adding a new TLS extension:: +@end menu + +@node Adding a new TLS extension +@subsection Adding a new TLS extension Adding support for a new TLS extension is done from time to time, and the process to do so is not difficult. Here are the steps you need to @@ -125,7 +130,7 @@ follow if you wish to do this yourself. For sake of discussion, let's consider adding support for the hypothetical TLS extension @code{foobar}. -@subsubsection Add @code{configure} option like @code{--enable-foobar} or @code{--disable-foobar}. +@subsubheading Add @code{configure} option like @code{--enable-foobar} or @code{--disable-foobar}. This step is useful when the extension code is large and it might be desirable to disable the extension under some circumstances. Otherwise it can be safely @@ -153,7 +158,7 @@ AM_CONDITIONAL(ENABLE_FOOBAR, test "$ac_enable_foobar" != "no") These lines should go in @code{lib/m4/hooks.m4}. -@subsubsection Add IANA extension value to @code{extensions_t} in @code{gnutls_int.h}. +@subsubheading Add IANA extension value to @code{extensions_t} in @code{gnutls_int.h}. A good name for the value would be GNUTLS_EXTENSION_FOOBAR. Check with @url{http://www.iana.org/assignments/tls-extensiontype-values} @@ -163,7 +168,7 @@ version since it will lead to interoperability problems in the future when the IANA allocates that number to someone else, or when the foobar protocol is allocated another number. -@subsubsection Add an entry to @code{_gnutls_extensions} in @code{gnutls_extensions.c}. +@subsubheading Add an entry to @code{_gnutls_extensions} in @code{gnutls_extensions.c}. A typical entry would be: @@ -203,7 +208,7 @@ will be called to deinitialize the extension's private parameters, if any. Note that the conditional @code{ENABLE_FOOBAR} definition should only be used if step 1 with the @code{configure} options has taken place. -@subsubsection Add new files that implement the extension. +@subsubheading Add new files that implement the extension. The functions you are responsible to add are those mentioned in the previous step. They should be added in a file such as @code{ext/@-foobar.c} @@ -304,7 +309,7 @@ libgnutls_ext_la_SOURCES += ext/foobar.c ext/foobar.h endif @end example -@subsubsection Add API functions to enable/disable the extension. +@subsubheading Add API functions to enable/disable the extension. It might be desirable to allow users of the extension to request use of the extension, or set extension specific data. @@ -370,7 +375,7 @@ The next section discusses the registration of a detected algorithm optimization. For more information please consult the @acronym{GnuTLS} source code in @code{lib/accelerated/}. -@subsubsection Overriding specific algorithms +@subsubheading Overriding specific algorithms When an optimized implementation of a single algorithm is available, say a hardware assisted version of @acronym{AES-CBC} then the following (internal) functions, from @code{crypto-backend.h}, can @@ -389,7 +394,7 @@ To register a hash (digest) or MAC algorithm. Those registration functions will only replace the specified algorithm and leave the rest of subsystem intact. -@subsubsection Overriding the cryptographic library +@subsubheading Overriding the cryptographic library In some systems, that might contain a broad acceleration engine, it might be desirable to override big parts of the cryptographic backend, or even all of them. T following functions are provided for this reason. diff --git a/doc/cha-intro-tls.texi b/doc/cha-intro-tls.texi index 64b4888f80..9bc63a0eea 100644 --- a/doc/cha-intro-tls.texi +++ b/doc/cha-intro-tls.texi @@ -558,6 +558,14 @@ in @acronym{GnuTLS} are: and they will be discussed in the subsections that follow. +@menu +* Maximum fragment length negotiation:: +* Server name indication:: +* Session tickets:: +* Safe renegotiation:: +@end menu + +@node Maximum fragment length negotiation @subsection Maximum fragment length negotiation @cindex TLS extensions @cindex maximum fragment length @@ -569,6 +577,7 @@ below can be used to control this extension. @showfuncB{gnutls_record_get_max_size,gnutls_record_set_max_size} +@node Server name indication @subsection Server name indication @anchor{serverind} @cindex TLS extensions @@ -588,6 +597,7 @@ client. @showfuncB{gnutls_server_name_set,gnutls_server_name_get} +@node Session tickets @subsection Session tickets @cindex TLS extensions @cindex session tickets @@ -607,6 +617,7 @@ Clients resume sessions using the normal session resumption procedure (see @ref{ @showfuncC{gnutls_session_ticket_key_generate,gnutls_session_ticket_enable_server,gnutls_session_ticket_enable_client} +@node Safe renegotiation @subsection Safe renegotiation @cindex renegotiation @cindex safe renegotiation diff --git a/doc/cha-library.texi b/doc/cha-library.texi index 2f751b3e9b..1ee6c5139f 100644 --- a/doc/cha-library.texi +++ b/doc/cha-library.texi @@ -1,6 +1,13 @@ @node Introduction to GnuTLS @chapter Introduction to GnuTLS +@menu +* GnuTLS introduction:: +* Downloading and installing:: +* Document overview:: +@end menu + +@node GnuTLS introduction @section Introduction In brief @acronym{GnuTLS} can be described as a library which offers an API @@ -42,6 +49,7 @@ libtasn1@footnote{@url{http://www.gnu.org/software/libtasn1/}} library. The ``Cryptographic back-end'' is provided by the nettle@footnote{@url{http://www.lysator.liu.se/~nisse/nettle/}} library. +@node Downloading and installing @section Downloading and installing @cindex installation @cindex download @@ -93,6 +101,7 @@ to create a smaller library with only the required features. For the complete list, refer to the output from @code{configure --help}. +@node Document overview @section Overview In this document we present an overview of the supported security protocols in @ref{Introduction to TLS}, and continue by providing more information on the certificate authentication in @ref{Certificate authentication}, diff --git a/doc/cha-programs.texi b/doc/cha-programs.texi index fda5f376d1..2327e85e85 100644 --- a/doc/cha-programs.texi +++ b/doc/cha-programs.texi @@ -164,6 +164,11 @@ Usage: gnutls-serv [options] -v, --version prints the program's version number @end example +@menu +* Setting up a test HTTPS server:: +@end menu + +@node Setting up a test HTTPS server @subsection Setting up a test HTTPS server @cindex HTTPS server @cindex debug server diff --git a/doc/scripts/gdoc b/doc/scripts/gdoc index 902829a508..be0621af52 100755 --- a/doc/scripts/gdoc +++ b/doc/scripts/gdoc @@ -158,10 +158,10 @@ $blankline_html = "

"; ); $blankline_texinfo = ""; -%highlights_tex = ( $type_param, '" {\bf $1}"', - $type_constant, '"{\it $1}"', - $type_func, '"{\bf $1}"', - $type_struct, '"{\it $1}"', +%highlights_tex = ( $type_param, '" {\\\bf $1}"', + $type_constant, '"{\\\it $1}"', + $type_func, '"{\\\bf $1}"', + $type_struct, '"{\\\it $1}"', ); $blankline_tex = "\\\\"; @@ -286,6 +286,7 @@ sub dump_section { $parameters{$name} = $contents; } else { # print STDERR "other section '$name' = '$contents'\n"; + $name =~ tr/ //d; $sections{$name} = $contents; push @sectionlist, $name; } @@ -504,7 +505,7 @@ sub output_tex { $sec =~ s/_/\\_/g; $sec =~ s/#([a-zA-Z\_]+)/{\\it $1}/g; - print "\n\\begin{function$sec}\n"; + print "\n\\begin{function${sec}}\n"; $out = $args{'sections'}{$section}; $out =~ s/\#([a-zA-Z\_]+)/{\\it $1}/g; @@ -518,7 +519,7 @@ sub output_tex { $out =~ s/([0-9]+)\^([0-9]+)/\$\{$1\}\^\{$2\}\$/g; print $out; - print "\\end{function$sec}\n"; + print "\\end{function${sec}}\n"; } print "\\end{function}\n\n"; } diff --git a/doc/scripts/mytexi2latex b/doc/scripts/mytexi2latex index cdb8964541..1500ff1f39 100755 --- a/doc/scripts/mytexi2latex +++ b/doc/scripts/mytexi2latex @@ -222,6 +222,8 @@ multitable: } } + $line =~ s/\@subsubheading (.+)/\\paragraph{$1}/g; + if ($line =~ s/\@section (.+)/\\section{$1}/g) { if ($label ne '') { $line .= "\\label{$label}\n";