@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.
@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.
@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.
@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
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
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:
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
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
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
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
@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
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}.
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;
printf ("\n");
@}
@}
-@end smallexample
+@end example
@node Interoperability
@subsection Interoperability
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
- 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
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
$ 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
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 \
--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.
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 \
--srppasswdconf srp-tpasswd.conf \
--srppasswd srp-passwd.txt \
--pskpasswd psk-passwd.txt
-@end smallexample
+@end example
@node The gnutls-cli-debug tool
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
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
-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
projects / thirdparty / gnutls.git / commitdiff
