From: Nikos Mavrogiannopoulos Date: Mon, 26 Dec 2011 15:12:49 +0000 (+0200) Subject: smallexample is no longer used. It is intended only for typesetting with smaller... X-Git-Tag: gnutls_3_0_10~50 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=89ee549eb59e2d627548bb79e2ccfa589791d98c;p=thirdparty%2Fgnutls.git smallexample is no longer used. It is intended only for typesetting with smaller pages and had no relation to our usage. --- diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi index df9d388b6c..924b2b3563 100644 --- a/doc/cha-cert-auth.texi +++ b/doc/cha-cert-auth.texi @@ -372,10 +372,10 @@ certificate chain, you can call @end itemize as in the following example: -@smallexample +@example gnutls_certificate_set_verify_flags (x509cred, GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5); -@end smallexample +@end example This will tell the verifier algorithm to enable @code{RSA-MD5} when verifying the certificates. diff --git a/doc/cha-cert-auth2.texi b/doc/cha-cert-auth2.texi index 61fe854d90..b4f2fd0c49 100644 --- a/doc/cha-cert-auth2.texi +++ b/doc/cha-cert-auth2.texi @@ -281,18 +281,18 @@ example of a template file. @subheading Diffie-Hellman parameter generation To generate parameters for Diffie-Hellman key exchange, use the command: -@smallexample +@example $ certtool --generate-dh-params --outfile dh.pem -@end smallexample +@end example @subheading Self-signed certificate generation To create a self signed certificate, use the command: -@smallexample +@example $ certtool --generate-privkey --outfile ca-key.pem $ certtool --generate-self-signed --load-privkey ca-key.pem \ --outfile ca-cert.pem -@end smallexample +@end example Note that a self-signed certificate usually belongs to a certificate authority, that signs other certificates. @@ -300,9 +300,9 @@ authority, that signs other certificates. @subheading Private key generation To create a private key (RSA by default), run: -@smallexample +@example $ certtool --generate-privkey --outfile key.pem -@end smallexample +@end example To create a DSA or elliptic curves (ECDSA) private key use the above command combined with @code{--dsa} or @code{--ecc} options. @@ -310,63 +310,63 @@ above command combined with @code{--dsa} or @code{--ecc} options. @subheading Certificate generation To generate a certificate using the private key, use the command: -@smallexample +@example $ certtool --generate-certificate --load-privkey key.pem \ --outfile cert.pem --load-ca-certificate ca-cert.pem \ --load-ca-privkey ca-key.pem -@end smallexample +@end example Alternatively you may create a certificate request, which is needed when the certificate will be signed by a third party authority. -@smallexample +@example $ certtool --generate-request --load-privkey key.pem \ --outfile request.pem -@end smallexample +@end example If the private key is stored in a smart card you can generate a request by specifying the private key object URL (see @ref{The p11tool application} on how to obtain the URL). -@smallexample +@example $ certtool --generate-request --load-privkey pkcs11:(PRIVKEY URL) \ --load-pubkey pkcs11:(PUBKEY URL) --outfile request.pem -@end smallexample +@end example To generate a certificate using the previous request, use the command: -@smallexample +@example $ certtool --generate-certificate --load-request request.pem \ --outfile cert.pem \ --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem -@end smallexample +@end example @subheading Certificate information To view the certificate information, use: -@smallexample +@example $ certtool --certificate-info --infile cert.pem -@end smallexample +@end example @subheading @acronym{PKCS} #12 structure generation To generate a @acronym{PKCS} #12 structure using the previous key and certificate, use the command: -@smallexample +@example $ certtool --load-certificate cert.pem --load-privkey key.pem \ --to-p12 --outder --outfile key.p12 -@end smallexample +@end example Some tools (reportedly web browsers) have problems with that file because it does not contain the CA certificate for the certificate. To work around that problem in the tool, you can use the --load-ca-certificate parameter as follows: -@smallexample +@example $ certtool --load-ca-certificate ca.pem \ --load-certificate cert.pem --load-privkey key.pem \ --to-p12 --outder --outfile key.p12 -@end smallexample +@end example @subheading Proxy certificate generation Proxy certificate can be used to delegate your credential to a @@ -374,34 +374,34 @@ temporary, typically short-lived, certificate. To create one from the previously created certificate, first create a temporary key and then generate a proxy certificate for it, using the commands: -@smallexample +@example $ certtool --generate-privkey > proxy-key.pem $ certtool --generate-proxy --load-ca-privkey key.pem \ --load-privkey proxy-key.pem --load-certificate cert.pem \ --outfile proxy-cert.pem -@end smallexample +@end example @subheading Certificate revocation list generation To create an empty Certificate Revocation List (CRL) do: -@smallexample +@example $ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \ --load-ca-certificate x509-ca.pem -@end smallexample +@end example To create a CRL that contains some revoked certificates, place the certificates in a file and use @code{--load-certificate} as follows: -@smallexample +@example $ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \ --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem -@end smallexample +@end example To verify a Certificate Revocation List (CRL) do: -@smallexample +@example $ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem -@end smallexample +@end example @@ -410,11 +410,11 @@ A template file can be used to avoid the interactive questions of certtool. Initially create a file named 'cert.cfg' that contains the information about the certificate. The template can be used as below: -@smallexample +@example $ certtool --generate-certificate cert.pem --load-privkey key.pem \ --template cert.cfg \ --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem -@end smallexample +@end example An example certtool template file: @@ -571,9 +571,9 @@ These are the configuration files of @acronym{p11-kit}@footnote{@url{http://p11- For example a file that will load the @acronym{OpenSC} module, could be named @code{/etc/pkcs11/modules/opensc} and contain the following: -@smallexample +@example module: /usr/lib/opensc-pkcs11.so -@end smallexample +@end example If you use this file, then there is no need for other initialization in @acronym{GnuTLS}, except for the PIN and token functions. Those allow retrieving a PIN @@ -597,16 +597,16 @@ This allows for a consistent naming of objects across systems and applications in the same system. For example a public key on a smart card may be referenced as: -@smallexample +@example pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315; \ manufacturer=EnterSafe;object=test1;objecttype=public;\ id=32f153f3e37990b08624141077ca5dec2d15faed -@end smallexample +@end example while the smart card itself can be referenced as: -@smallexample +@example pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315;manufacturer=EnterSafe -@end smallexample +@end example Objects stored in a @acronym{PKCS} #11 token can be extracted if they are not marked as sensitive. Usually only private keys are marked as @@ -747,32 +747,32 @@ on them. Some examples on how to use p11tool are illustrated in the following paragraphs. @subsubheading List all tokens -@smallexample +@example $ p11tool --list-tokens -@end smallexample +@end example @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 +@example $ p11tool --login --list-all -@end smallexample +@end example @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. -@smallexample +@example $ p11tool --login --export [OBJECT URL] -@end smallexample +@end example @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 +@example $ p11tool --login --write [TOKEN URL] \ --load-certificate cert.pem --label "my_cert" -@end smallexample +@end example @node Abstract key types diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi index be12188529..1037038156 100644 --- a/doc/cha-gtls-app.texi +++ b/doc/cha-gtls-app.texi @@ -237,9 +237,9 @@ to be added to the compiler invocation at compile time are output by the @option{--cflags} option to @command{pkg-config gnutls}. The following example shows how it can be used at the command line: -@smallexample +@example gcc -c foo.c `pkg-config gnutls --cflags` -@end smallexample +@end example Adding the output of @samp{pkg-config gnutls --cflags} to the compilers command line will ensure that the compiler can find the @@ -255,16 +255,16 @@ required to link the program with the library (for instance, the @samp{-ltasn1} option). The example shows how to link @file{foo.o} with the library to a program @command{foo}. -@smallexample +@example gcc -o foo foo.o `pkg-config gnutls --libs` -@end smallexample +@end example Of course you can also combine both examples to a single command by specifying both options to @command{pkg-config}: -@smallexample +@example gcc -o foo foo.c `pkg-config gnutls --cflags --libs` -@end smallexample +@end example @node Session initialization @section Session initialization @@ -948,13 +948,13 @@ client or server random data first, you can set the For example, after establishing a TLS session using @funcref{gnutls_handshake}, you can invoke the TLS PRF with this call: -@smallexample +@example #define MYLABEL "EXPORTER-FOO" #define MYCONTEXT "some context data" char out[32]; rc = gnutls_prf (session, strlen (MYLABEL), MYLABEL, 0, strlen (MYCONTEXT), MYCONTEXT, 32, out); -@end smallexample +@end example If you don't want to mix in the client/server random, there is a more low-level TLS PRF interface called @funcref{gnutls_prf_raw}. @@ -979,7 +979,7 @@ the @code{tls-unique} channel binding for TLS defined in The following example describes how to print the channel binding data. Note that it must be run after a successful TLS handshake. -@smallexample +@example @{ gnutls_datum_t cb; int rc; @@ -999,7 +999,7 @@ Note that it must be run after a successful TLS handshake. printf ("\n"); @} @} -@end smallexample +@end example @node Interoperability @subsection Interoperability diff --git a/doc/cha-programs.texi b/doc/cha-programs.texi index 2327e85e85..42cb4a90ba 100644 --- a/doc/cha-programs.texi +++ b/doc/cha-programs.texi @@ -85,7 +85,7 @@ To connect to a server using PSK authentication, you need to enable the choice of PSK by using a cipher priority parameter such as in the example below. -@smallexample +@example $ ./gnutls-cli -p 5556 localhost --pskusername psk_identity \ --pskkey 88f3824b3e5659f52d00e959bacab954b6540344 \ --priority NORMAL:-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK @@ -100,7 +100,7 @@ Connecting to '127.0.0.1:5556'... - Handshake was completed - Simple Client Mode: -@end smallexample +@end example By keeping the @code{--pskusername} parameter and removing the @code{--pskkey} parameter, it will query only for the password during @@ -179,16 +179,16 @@ use @code{gnutls-serv} as a simple HTTPS server. The most basic server can be started as: -@smallexample +@example gnutls-serv --http -@end smallexample +@end example It will only support anonymous ciphersuites, which many TLS clients refuse to use. The next step is to add support for X.509. First we generate a CA: -@smallexample +@example $ certtool --generate-privkey > x509-ca-key.pem $ echo 'cn = GnuTLS test CA' > ca.tmpl $ echo 'ca' >> ca.tmpl @@ -196,7 +196,7 @@ $ echo 'cert_signing_key' >> ca.tmpl $ certtool --generate-self-signed --load-privkey x509-ca-key.pem \ --template ca.tmpl --outfile x509-ca.pem ... -@end smallexample +@end example Then generate a server certificate. Remember to change the dns_name value to the name of your server host, or skip that command to avoid @@ -235,15 +235,15 @@ To be able to import the client key/certificate into some applications, you will need to convert them into a PKCS#12 structure. This also encrypts the security sensitive key with a password. -@smallexample +@example $ certtool --to-p12 --load-ca-certificate x509-ca.pem \ --load-privkey x509-client-key.pem --load-certificate x509-client.pem \ --outder --outfile x509-client.p12 -@end smallexample +@end example For icing, we'll create a proxy certificate for the client too. -@smallexample +@example $ certtool --generate-privkey > x509-proxy-key.pem $ echo 'cn = GnuTLS test client proxy' > proxy.tmpl $ certtool --generate-proxy --load-privkey x509-proxy-key.pem \ @@ -251,16 +251,16 @@ $ certtool --generate-proxy --load-privkey x509-proxy-key.pem \ --load-certificate x509-client.pem --template proxy.tmpl \ --outfile x509-proxy.pem ... -@end smallexample +@end example Then start the server again: -@smallexample +@example $ gnutls-serv --http \ --x509cafile x509-ca.pem \ --x509keyfile x509-server-key.pem \ --x509certfile x509-server.pem -@end smallexample +@end example Try connecting to the server using your web browser. Note that the server listens to port 5556 by default. @@ -269,62 +269,62 @@ While you are at it, to allow connections using DSA, you can also create a DSA key and certificate for the server. These credentials will be used in the final example below. -@smallexample +@example $ certtool --generate-privkey --dsa > x509-server-key-dsa.pem $ certtool --generate-certificate --load-privkey x509-server-key-dsa.pem \ --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \ --template server.tmpl --outfile x509-server-dsa.pem ... -@end smallexample +@end example The next step is to create OpenPGP credentials for the server. -@smallexample +@example gpg --gen-key ...enter whatever details you want, use 'test.gnutls.org' as name... -@end smallexample +@end example Make a note of the OpenPGP key identifier of the newly generated key, here it was @code{5D1D14D8}. You will need to export the key for GnuTLS to be able to use it. -@smallexample +@example gpg -a --export 5D1D14D8 > openpgp-server.txt gpg --export 5D1D14D8 > openpgp-server.bin gpg --export-secret-keys 5D1D14D8 > openpgp-server-key.bin gpg -a --export-secret-keys 5D1D14D8 > openpgp-server-key.txt -@end smallexample +@end example Let's start the server with support for OpenPGP credentials: -@smallexample +@example gnutls-serv --http \ --pgpkeyfile openpgp-server-key.txt \ --pgpcertfile openpgp-server.txt -@end smallexample +@end example The next step is to add support for SRP authentication. This requires an SRP password file (see @ref{Invoking srptool}). To start the server with SRP support: -@smallexample +@example gnutls-serv --http \ --srppasswdconf srp-tpasswd.conf \ --srppasswd srp-passwd.txt -@end smallexample +@end example Let's also start a server with support for PSK. This would require a password file created with @code{psktool} (see @ref{Invoking psktool}). -@smallexample +@example gnutls-serv --http \ --pskpasswd psk-passwd.txt -@end smallexample +@end example Finally, we start the server with all the earlier parameters and you get this command: -@smallexample +@example gnutls-serv --http \ --x509cafile x509-ca.pem \ --x509keyfile x509-server-key.pem \ @@ -336,7 +336,7 @@ gnutls-serv --http \ --srppasswdconf srp-tpasswd.conf \ --srppasswd srp-passwd.txt \ --pskpasswd psk-passwd.txt -@end smallexample +@end example @node The gnutls-cli-debug tool diff --git a/doc/cha-shared-key.texi b/doc/cha-shared-key.texi index 50f4585e43..eb62959474 100644 --- a/doc/cha-shared-key.texi +++ b/doc/cha-shared-key.texi @@ -83,26 +83,26 @@ and @code{tpasswd.conf} which holds generators and primes. To create tpasswd.conf which holds the generator and prime values for the @acronym{SRP} protocol, run: -@smallexample +@example $ srptool --create-conf /etc/tpasswd.conf -@end smallexample +@end example This command will create /etc/tpasswd and will add user 'test' (you will also be prompted for a password). Verifiers are stored in a way that is compatible with libsrp. -@smallexample +@example $ srptool --passwd /etc/tpasswd \ --passwd-conf /etc/tpasswd.conf -u test -@end smallexample +@end example This command will check against a password. If the password matches the one in /etc/tpasswd you will get an ok. -@smallexample +@example $ srptool --passwd /etc/tpasswd \ --passwd-conf /etc/tpasswd.conf --verify -u test -@end smallexample +@end example @node PSK authentication @section PSK authentication @@ -153,7 +153,7 @@ This is a program to manage @acronym{PSK} username and keys. It will generate random keys for the indicated username, using a simple password file format. -@smallexample +@example PSKtool help Usage : psktool [options] -u, --username username @@ -162,19 +162,19 @@ Usage : psktool [options] -s, --keysize SIZE specify the key size in bytes. -v, --version prints the program's version number -h, --help shows this help text -@end smallexample +@end example The generation of a PSK password file is illustrated in the example below. The password is provided in the prompt. -@smallexample +@example $ ./psktool -u psk_identity -p psks.txt Generating a random key for user 'psk_identity' Key stored to psks.txt $ cat psks.txt psk_identity:88f3824b3e5659f52d00e959bacab954b6540344 $ -@end smallexample +@end example @node Anonymous authentication @section Anonymous authentication