diff options
| -rw-r--r-- | doc/cha-auth.texi | 88 | ||||
| -rw-r--r-- | doc/cha-cert-auth.texi | 455 | ||||
| -rw-r--r-- | doc/cha-programs.texi | 611 | ||||
| -rw-r--r-- | doc/gnutls.texi | 2 |
4 files changed, 590 insertions, 566 deletions
diff --git a/doc/cha-auth.texi b/doc/cha-auth.texi index fcbe26bce1..7315389dd8 100644 --- a/doc/cha-auth.texi +++ b/doc/cha-auth.texi @@ -32,8 +32,8 @@ we elaborate on supported authentication methods. @menu * Certificate authentication:: * Anonymous authentication:: -* Authentication using SRP:: -* Authentication using PSK:: +* SRP authentication:: +* PSK authentication:: * Authentication and credentials:: @end menu @@ -219,8 +219,16 @@ efficient than ANON_DH on equivalent security levels. @end table +@node SRP authentication +@section SRP authentication + +@menu +* Authentication using SRP:: +* Invoking srptool:: +@end menu + @node Authentication using SRP -@section Authentication using @acronym{SRP} +@subsection Authentication using @acronym{SRP} @cindex SRP authentication @acronym{GnuTLS} supported authentication via the Secure Remote Password @@ -300,9 +308,51 @@ also included. See @ref{srptool}, for more information. @showfuncB{gnutls_srp_base64_encode,gnutls_srp_base64_decode} +@node Invoking srptool +@subsection Invoking srptool +@anchor{srptool} +@cindex srptool + +The @file{srptool} is a very simple program that emulates the programs +in the @emph{Stanford SRP libraries}@footnote{See +@url{http://srp.stanford.edu/}.}. It requires two files, +one called @code{tpasswd} which holds usernames and verifiers, +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 +$ srptool --create-conf /etc/tpasswd.conf +@end smallexample + +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 +$ srptool --passwd /etc/tpasswd \ + --passwd-conf /etc/tpasswd.conf -u test +@end smallexample + +This command will check against a password. If the password matches +the one in /etc/tpasswd you will get an ok. + +@smallexample +$ srptool --passwd /etc/tpasswd \ + --passwd-conf /etc/tpasswd.conf --verify -u test +@end smallexample + +@node PSK authentication +@section PSK authentication + +@menu +* Authentication using PSK:: +* Invoking psktool:: +@end menu @node Authentication using PSK -@section Authentication using @acronym{PSK} +@subsection Authentication using @acronym{PSK} @cindex PSK authentication Authentication using Pre-shared keys is a method to authenticate using @@ -369,6 +419,36 @@ in @acronym{GnuTLS}. @showfuncC{gnutls_key_generate,gnutls_hex_encode,gnutls_hex_decode} +@node Invoking psktool +@subsection Invoking psktool +@cindex psktool + +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 +PSKtool help +Usage : psktool [options] + -u, --username username + specify username. + -p, --passwd FILE specify a password file. + -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 + +The generation of a PSK password file is illustrated in the example below. +The password is provided in the prompt. + +@smallexample +$ ./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 @node Authentication and credentials @section Authentication and credentials diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi index 4cc3ab3cbc..7af169f72f 100644 --- a/doc/cha-cert-auth.texi +++ b/doc/cha-cert-auth.texi @@ -5,6 +5,7 @@ @menu * X.509 certificates:: * OpenPGP certificates:: +* The certtool application:: * Hardware tokens:: * Abstract key types:: * Digital signatures:: @@ -353,6 +354,7 @@ of their usage is also shown. @verbatiminclude examples/ex-pkcs12.c + @node OpenPGP certificates @section @acronym{OpenPGP} certificates @cindex OpenPGP certificates @@ -426,12 +428,364 @@ to verify the signatures in the certificate sent by the peer. @showfuncdesc{gnutls_certificate_set_openpgp_keyring_file} +@node The certtool application +@section The certtool application +@cindex certtool + +This is a program to generate @acronym{X.509} certificates, certificate +requests, CRLs and private keys. + +@example +Certtool help +Usage: certtool [options] + -s, --generate-self-signed + Generate a self-signed certificate. + -c, --generate-certificate + Generate a signed certificate. + --generate-proxy Generate a proxy certificate. + --generate-crl Generate a CRL. + -u, --update-certificate + Update a signed certificate. + -p, --generate-privkey Generate a private key. + -q, --generate-request Generate a PKCS #10 certificate + request. + -e, --verify-chain Verify a PEM encoded certificate chain. + The last certificate in the chain must + be a self signed one. + --verify Verify a PEM encoded certificate chain. + CA certificates must be loaded with + --load-ca-certificate. + --verify-crl Verify a CRL. + --generate-dh-params Generate PKCS #3 encoded Diffie-Hellman + parameters. + --get-dh-params Get the included PKCS #3 encoded + Diffie-Hellman parameters. + --load-privkey FILE Private key file to use. + --load-pubkey FILE Public key file to use. + --load-request FILE Certificate request file to use. + --load-certificate FILE + Certificate file to use. + --load-ca-privkey FILE Certificate authority's private key + file to use. + --load-ca-certificate FILE + Certificate authority's certificate + file to use. + --password PASSWORD Password to use. + -i, --certificate-info Print information on a certificate. + --certificate-pubkey Print certificate public key. + --pgp-certificate-info Print information on a OpenPGP + certificate. + --pgp-ring-info Print information on a keyring + structure. + -l, --crl-info Print information on a CRL. + --crq-info Print information on a Certificate + Request. + --no-crq-extensions Do not use extensions in certificate + requests. + --p12-info Print information on a PKCS #12 + structure. + --p7-info Print information on a PKCS #7 + structure. + --smime-to-p7 Convert S/MIME to PKCS #7 structure. + -k, --key-info Print information on a private key. + --pgp-key-info Print information on a OpenPGP private + key. + --pubkey-info Print information on a public key. + --fix-key Regenerate the parameters in a private + key. + --v1 Generate an X.509 version 1 certificate + (no extensions). + --to-p12 Generate a PKCS #12 structure. + --to-p8 Generate a PKCS #8 key structure. + -8, --pkcs8 Use PKCS #8 format for private keys. + --dsa Use DSA keys. + --ecc Use ECC (ECDSA) keys. + --hash STR Hash algorithm to use for signing + (MD5,SHA1,RMD160,SHA256,SHA384,SHA512). + --export-ciphers Use weak encryption algorithms. + --inder Use DER format for input certificates + and private keys. + --inraw Use RAW/DER format for input + certificates and private keys. + --outder Use DER format for output certificates + and private keys. + --outraw Use RAW/DER format for output + certificates and private keys. + --bits BITS specify the number of bits for key + generation. + --sec-param PARAM specify the security level + [low|normal|high|ultra]. + --disable-quick-random Use /dev/random for key generationg, + thus increasing the quality of + randomness used. + --outfile FILE Output file. + --infile FILE Input file. + --template FILE Template file to use for non + interactive operation. + --pkcs-cipher CIPHER Cipher to use for pkcs operations + (3des,3des-pkcs12,aes-128,aes-192,aes-25 + 6,rc2-40,arcfour). + -d, --debug LEVEL specify the debug level. Default is 1. + -h, --help shows this help text + -v, --version shows the program's version +@end example + +The program can be used interactively or non interactively by +specifying the @code{--template} command line option. See below for an +example of a template file. + +@subsection Diffie-Hellman parameter generation +To generate parameters for Diffie-Hellman key exchange, use the command: +@smallexample +$ certtool --generate-dh-params --outfile dh.pem +@end smallexample + +@subsection Self-signed certificate generation + +To create a self signed certificate, use the command: +@smallexample +$ certtool --generate-privkey --outfile ca-key.pem +$ certtool --generate-self-signed --load-privkey ca-key.pem \ + --outfile ca-cert.pem +@end smallexample + +Note that a self-signed certificate usually belongs to a certificate +authority, that signs other certificates. + +@subsection Private key generation +To create a private key (RSA by default), run: + +@smallexample +$ certtool --generate-privkey --outfile key.pem +@end smallexample + +To create a DSA or elliptic curves (ECDSA) private key use the +above command combined with @code{--dsa} or @code{--ecc} options. + +@subsection Certificate generation +To generate a certificate using the private key, use the command: + +@smallexample +$ certtool --generate-certificate --load-privkey key.pem \ + --outfile cert.pem --load-ca-certificate ca-cert.pem \ + --load-ca-privkey ca-key.pem +@end smallexample + +Alternatively you may create a certificate request, which is needed +when the certificate will be signed by a third party authority. + +@smallexample +$ certtool --generate-request --load-privkey key.pem \ + --outfile request.pem +@end smallexample + +If the private key is stored in a smart card you can generate +a request by specifying the private key object URL (see @ref{Invoking p11tool} +on how to obtain the URL). + +@smallexample +$ certtool --generate-request --load-privkey pkcs11:(PRIVKEY URL) \ + --load-pubkey pkcs11:(PUBKEY URL) --outfile request.pem +@end smallexample + +To generate a certificate using the previous request, use the command: + +@smallexample +$ certtool --generate-certificate --load-request request.pem \ + --outfile cert.pem \ + --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem +@end smallexample + +@subsection Certificate information +To view the certificate information, use: + +@smallexample +$ certtool --certificate-info --infile cert.pem +@end smallexample + +@subsection @acronym{PKCS} #12 structure generation +To generate a @acronym{PKCS} #12 structure using the previous key and +certificate, use the command: + +@smallexample +$ certtool --load-certificate cert.pem --load-privkey key.pem \ + --to-p12 --outder --outfile key.p12 +@end smallexample + +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 +$ certtool --load-ca-certificate ca.pem \ + --load-certificate cert.pem --load-privkey key.pem \ + --to-p12 --outder --outfile key.p12 +@end smallexample + +@subsection Proxy certificate generation +Proxy certificate can be used to delegate your credential to a +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 +$ 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 + +@subsection Certificate revocation list generation +To create an empty Certificate Revocation List (CRL) do: + +@smallexample +$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \ + --load-ca-certificate x509-ca.pem +@end smallexample + +To create a CRL that contains some revoked certificates, place the +certificates in a file and use @code{--load-certificate} as follows: + +@smallexample +$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \ + --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem +@end smallexample + +To verify a Certificate Revocation List (CRL) do: + +@smallexample +$ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem +@end smallexample + + + +@subsection Certtool's template file format: +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 +$ 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 + +An example certtool template file: + +@example +# X.509 Certificate options +# +# DN options + +# The organization of the subject. +organization = "Koko inc." + +# The organizational unit of the subject. +unit = "sleeping dept." + +# The locality of the subject. +# locality = + +# The state of the certificate owner. +state = "Attiki" + +# The country of the subject. Two letter code. +country = GR + +# The common name of the certificate owner. +cn = "Cindy Lauper" + +# A user id of the certificate owner. +#uid = "clauper" + +# If the supported DN OIDs are not adequate you can set +# any OID here. +# For example set the X.520 Title and the X.520 Pseudonym +# by using OID and string pairs. +#dn_oid = "2.5.4.12" "Dr." "2.5.4.65" "jackal" + +# This is deprecated and should not be used in new +# certificates. +# pkcs9_email = "none@@none.org" + +# The serial number of the certificate +serial = 007 + +# In how many days, counting from today, this certificate will expire. +expiration_days = 700 + +# X.509 v3 extensions + +# A dnsname in case of a WWW server. +#dns_name = "www.none.org" +#dns_name = "www.morethanone.org" + +# An IP address in case of a server. +#ip_address = "192.168.1.1" + +# An email in case of a person +email = "none@@none.org" + +# An URL that has CRLs (certificate revocation lists) +# available. Needed in CA certificates. +#crl_dist_points = "http://www.getcrl.crl/getcrl/" + +# Whether this is a CA certificate or not +#ca + +# Whether this certificate will be used for a TLS client +#tls_www_client + +# Whether this certificate will be used for a TLS server +#tls_www_server + +# Whether this certificate will be used to sign data (needed +# in TLS DHE ciphersuites). +signing_key + +# Whether this certificate will be used to encrypt data (needed +# in TLS RSA ciphersuites). Note that it is preferred to use different +# keys for encryption and signing. +#encryption_key + +# Whether this key will be used to sign other certificates. +#cert_signing_key + +# Whether this key will be used to sign CRLs. +#crl_signing_key + +# Whether this key will be used to sign code. +#code_signing_key + +# Whether this key will be used to sign OCSP data. +#ocsp_signing_key + +# Whether this key will be used for time stamping. +#time_stamping_key + +# Whether this key will be used for IPsec IKE operations. +#ipsec_ike_key +@end example + + + @node Hardware tokens @section Hardware tokens @cindex PKCS #11 tokens @cindex hardware tokens @cindex smart cards +@menu +* Introduction:: +* PKCS11 Initialization:: +* Reading objects:: +* Writing objects:: +* Using a PKCS11 token with TLS:: +* The p11tool application:: +@end menu + +@node Introduction @subsection Introduction This section copes with hardware token support in @acronym{GnuTLS} using @acronym{PKCS} #11 @xcite{PKCS11}. @@ -461,6 +815,7 @@ system, being the @acronym{Gnome Keyring}. @caption{PKCS #11 module usage.} @end float +@node PKCS11 Initialization @subsection Initialization To allow all the @acronym{GnuTLS} applications to access @acronym{PKCS} #11 tokens you can use a configuration per module, stored in @code{/etc/pkcs11/modules/}. @@ -489,6 +844,7 @@ are sharing a module. To avoid this problem GnuTLS uses @acronym{p11-kit} that provides a middleware to control access to resources over the multiple users. +@node Reading objects @subsection Reading objects All @acronym{PKCS} #11 objects are referenced by @acronym{GnuTLS} functions by @@ -561,6 +917,7 @@ gnutls_global_deinit(); @verbatiminclude examples/ex-pkcs11-list.c +@node Writing objects @subsection Writing objects With @acronym{GnuTLS} you can copy existing private keys and certificates @@ -576,6 +933,7 @@ entered before accessing the object (for operations or otherwise). @showfuncdesc{gnutls_pkcs11_delete_url} +@node Using a PKCS11 token with TLS @subsection Using a @acronym{PKCS} #11 token with TLS It is possible to use a @acronym{PKCS} #11 token to a TLS @@ -585,6 +943,103 @@ certificates by specifying a PKCS #11 URL instead of a filename. @showfuncB{gnutls_certificate_set_x509_trust_file,gnutls_certificate_set_x509_key_file} +@node The p11tool application +@subsection The p11tool application +@anchor{p11tool} +@cindex p11tool + +p11tool is a program that is used to access tokens +and security modules that support the PKCS #11 API. It requires +individual PKCS #11 modules to be loaded either with the +@code{--provider} option, or by setting up the GnuTLS configuration +file for PKCS #11 as in @ref{Hardware tokens}. + +@example +p11tool help +Usage: p11tool [options] +Usage: p11tool --list-tokens +Usage: p11tool --list-all +Usage: p11tool --export 'pkcs11:...' + + --export URL Export an object specified by a pkcs11 + URL + --list-tokens List all available tokens + --list-mechanisms URL List all available mechanisms in token. + --list-all List all objects specified by a PKCS#11 + URL + --list-all-certs List all certificates specified by a + PKCS#11 URL + --list-certs List certificates that have a private + key specified by a PKCS#11 URL + --list-privkeys List private keys specified by a + PKCS#11 URL + --list-trusted List certificates marked as trusted, + specified by a PKCS#11 URL + --initialize URL Initializes a PKCS11 token. + --write URL Writes loaded certificates, private or + secret keys to a PKCS11 token. + --delete URL Deletes objects matching the URL. + --label label Sets a label for the write operation. + --trusted Marks the certificate to be written as + trusted. + --private Marks the object to be written as + private (requires PIN). + --no-private Marks the object to be written as not + private. + --login Force login to token + --detailed-url Export detailed URLs. + --no-detailed-url Export less detailed URLs. + --secret-key HEX_KEY Provide a hex encoded secret key. + --load-privkey FILE Private key file to use. + --load-pubkey FILE Private key file to use. + --load-certificate FILE + Certificate file to use. + -8, --pkcs8 Use PKCS #8 format for private keys. + --inder Use DER format for input certificates + and private keys. + --inraw Use RAW/DER format for input + certificates and private keys. + --provider Library Specify the pkcs11 provider library + --outfile FILE Output file. + -d, --debug LEVEL specify the debug level. Default is 1. + -h, --help shows this help text +@end example + +After being provided the available PKCS #11 modules, it can list all tokens +available in your system, the objects on the tokens, and perform operations +on them. + +Some examples on how to use p11tool are illustrated in the following paragraphs. + +@subsubsection List all tokens +@smallexample +$ p11tool --list-tokens +@end smallexample + +@subsubsection 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 +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 +$ p11tool --login --export [OBJECT URL] +@end smallexample + +@subsubsection 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 +$ p11tool --login --write [TOKEN URL] \ + --load-certificate cert.pem --label "my_cert" +@end smallexample + + @node Abstract key types @section Abstract key types diff --git a/doc/cha-programs.texi b/doc/cha-programs.texi index 7bb39acfb9..fda5f376d1 100644 --- a/doc/cha-programs.texi +++ b/doc/cha-programs.texi @@ -1,362 +1,18 @@ -@node Included programs -@chapter Included programs +@node Other included programs +@chapter Other included programs Included with @acronym{GnuTLS} are also a few command line tools that let you use the library for common tasks without writing an application. The applications are discussed in this chapter. @menu -* Invoking certtool:: -* Invoking gnutls-cli:: -* Invoking gnutls-cli-debug:: -* Invoking gnutls-serv:: -* Invoking psktool:: -* Invoking srptool:: -* Invoking p11tool:: +* The gnutls-cli tool:: +* The gnutls-serv tool:: +* The gnutls-cli-debug tool:: @end menu -@node Invoking certtool -@section Invoking certtool -@cindex certtool - -This is a program to generate @acronym{X.509} certificates, certificate -requests, CRLs and private keys. - -@example -Certtool help -Usage: certtool [options] - -s, --generate-self-signed - Generate a self-signed certificate. - -c, --generate-certificate - Generate a signed certificate. - --generate-proxy Generate a proxy certificate. - --generate-crl Generate a CRL. - -u, --update-certificate - Update a signed certificate. - -p, --generate-privkey Generate a private key. - -q, --generate-request Generate a PKCS #10 certificate - request. - -e, --verify-chain Verify a PEM encoded certificate chain. - The last certificate in the chain must - be a self signed one. - --verify Verify a PEM encoded certificate chain. - CA certificates must be loaded with - --load-ca-certificate. - --verify-crl Verify a CRL. - --generate-dh-params Generate PKCS #3 encoded Diffie-Hellman - parameters. - --get-dh-params Get the included PKCS #3 encoded - Diffie-Hellman parameters. - --load-privkey FILE Private key file to use. - --load-pubkey FILE Public key file to use. - --load-request FILE Certificate request file to use. - --load-certificate FILE - Certificate file to use. - --load-ca-privkey FILE Certificate authority's private key - file to use. - --load-ca-certificate FILE - Certificate authority's certificate - file to use. - --password PASSWORD Password to use. - -i, --certificate-info Print information on a certificate. - --certificate-pubkey Print certificate public key. - --pgp-certificate-info Print information on a OpenPGP - certificate. - --pgp-ring-info Print information on a keyring - structure. - -l, --crl-info Print information on a CRL. - --crq-info Print information on a Certificate - Request. - --no-crq-extensions Do not use extensions in certificate - requests. - --p12-info Print information on a PKCS #12 - structure. - --p7-info Print information on a PKCS #7 - structure. - --smime-to-p7 Convert S/MIME to PKCS #7 structure. - -k, --key-info Print information on a private key. - --pgp-key-info Print information on a OpenPGP private - key. - --pubkey-info Print information on a public key. - --fix-key Regenerate the parameters in a private - key. - --v1 Generate an X.509 version 1 certificate - (no extensions). - --to-p12 Generate a PKCS #12 structure. - --to-p8 Generate a PKCS #8 key structure. - -8, --pkcs8 Use PKCS #8 format for private keys. - --dsa Use DSA keys. - --ecc Use ECC (ECDSA) keys. - --hash STR Hash algorithm to use for signing - (MD5,SHA1,RMD160,SHA256,SHA384,SHA512). - --export-ciphers Use weak encryption algorithms. - --inder Use DER format for input certificates - and private keys. - --inraw Use RAW/DER format for input - certificates and private keys. - --outder Use DER format for output certificates - and private keys. - --outraw Use RAW/DER format for output - certificates and private keys. - --bits BITS specify the number of bits for key - generation. - --sec-param PARAM specify the security level - [low|normal|high|ultra]. - --disable-quick-random Use /dev/random for key generationg, - thus increasing the quality of - randomness used. - --outfile FILE Output file. - --infile FILE Input file. - --template FILE Template file to use for non - interactive operation. - --pkcs-cipher CIPHER Cipher to use for pkcs operations - (3des,3des-pkcs12,aes-128,aes-192,aes-25 - 6,rc2-40,arcfour). - -d, --debug LEVEL specify the debug level. Default is 1. - -h, --help shows this help text - -v, --version shows the program's version -@end example - -The program can be used interactively or non interactively by -specifying the @code{--template} command line option. See below for an -example of a template file. - -@subsection Diffie-Hellman parameter generation -To generate parameters for Diffie-Hellman key exchange, use the command: -@smallexample -$ certtool --generate-dh-params --outfile dh.pem -@end smallexample - -@subsection Self-signed certificate generation - -To create a self signed certificate, use the command: -@smallexample -$ certtool --generate-privkey --outfile ca-key.pem -$ certtool --generate-self-signed --load-privkey ca-key.pem \ - --outfile ca-cert.pem -@end smallexample - -Note that a self-signed certificate usually belongs to a certificate -authority, that signs other certificates. - -@subsection Private key generation -To create a private key (RSA by default), run: - -@smallexample -$ certtool --generate-privkey --outfile key.pem -@end smallexample - -To create a DSA or elliptic curves (ECDSA) private key use the -above command combined with @code{--dsa} or @code{--ecc} options. - -@subsection Certificate generation -To generate a certificate using the private key, use the command: - -@smallexample -$ certtool --generate-certificate --load-privkey key.pem \ - --outfile cert.pem --load-ca-certificate ca-cert.pem \ - --load-ca-privkey ca-key.pem -@end smallexample - -Alternatively you may create a certificate request, which is needed -when the certificate will be signed by a third party authority. - -@smallexample -$ certtool --generate-request --load-privkey key.pem \ - --outfile request.pem -@end smallexample - -If the private key is stored in a smart card you can generate -a request by specifying the private key object URL (see @ref{Invoking p11tool} -on how to obtain the URL). - -@smallexample -$ certtool --generate-request --load-privkey pkcs11:(PRIVKEY URL) \ - --load-pubkey pkcs11:(PUBKEY URL) --outfile request.pem -@end smallexample - -To generate a certificate using the previous request, use the command: - -@smallexample -$ certtool --generate-certificate --load-request request.pem \ - --outfile cert.pem \ - --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem -@end smallexample - -@subsection Certificate information -To view the certificate information, use: - -@smallexample -$ certtool --certificate-info --infile cert.pem -@end smallexample - -@subsection @acronym{PKCS} #12 structure generation -To generate a @acronym{PKCS} #12 structure using the previous key and -certificate, use the command: - -@smallexample -$ certtool --load-certificate cert.pem --load-privkey key.pem \ - --to-p12 --outder --outfile key.p12 -@end smallexample - -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 -$ certtool --load-ca-certificate ca.pem \ - --load-certificate cert.pem --load-privkey key.pem \ - --to-p12 --outder --outfile key.p12 -@end smallexample - -@subsection Proxy certificate generation -Proxy certificate can be used to delegate your credential to a -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 -$ 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 - -@subsection Certificate revocation list generation -To create an empty Certificate Revocation List (CRL) do: - -@smallexample -$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \ - --load-ca-certificate x509-ca.pem -@end smallexample - -To create a CRL that contains some revoked certificates, place the -certificates in a file and use @code{--load-certificate} as follows: - -@smallexample -$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \ - --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem -@end smallexample - -To verify a Certificate Revocation List (CRL) do: - -@smallexample -$ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem -@end smallexample - - - -@subsection Certtool's template file format: -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 -$ 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 - -An example certtool template file: - -@example -# X.509 Certificate options -# -# DN options - -# The organization of the subject. -organization = "Koko inc." - -# The organizational unit of the subject. -unit = "sleeping dept." - -# The locality of the subject. -# locality = - -# The state of the certificate owner. -state = "Attiki" - -# The country of the subject. Two letter code. -country = GR - -# The common name of the certificate owner. -cn = "Cindy Lauper" - -# A user id of the certificate owner. -#uid = "clauper" - -# If the supported DN OIDs are not adequate you can set -# any OID here. -# For example set the X.520 Title and the X.520 Pseudonym -# by using OID and string pairs. -#dn_oid = "2.5.4.12" "Dr." "2.5.4.65" "jackal" - -# This is deprecated and should not be used in new -# certificates. -# pkcs9_email = "none@@none.org" - -# The serial number of the certificate -serial = 007 - -# In how many days, counting from today, this certificate will expire. -expiration_days = 700 - -# X.509 v3 extensions - -# A dnsname in case of a WWW server. -#dns_name = "www.none.org" -#dns_name = "www.morethanone.org" - -# An IP address in case of a server. -#ip_address = "192.168.1.1" - -# An email in case of a person -email = "none@@none.org" - -# An URL that has CRLs (certificate revocation lists) -# available. Needed in CA certificates. -#crl_dist_points = "http://www.getcrl.crl/getcrl/" - -# Whether this is a CA certificate or not -#ca - -# Whether this certificate will be used for a TLS client -#tls_www_client - -# Whether this certificate will be used for a TLS server -#tls_www_server - -# Whether this certificate will be used to sign data (needed -# in TLS DHE ciphersuites). -signing_key - -# Whether this certificate will be used to encrypt data (needed -# in TLS RSA ciphersuites). Note that it is preferred to use different -# keys for encryption and signing. -#encryption_key - -# Whether this key will be used to sign other certificates. -#cert_signing_key - -# Whether this key will be used to sign CRLs. -#crl_signing_key - -# Whether this key will be used to sign code. -#code_signing_key - -# Whether this key will be used to sign OCSP data. -#ocsp_signing_key - -# Whether this key will be used for time stamping. -#time_stamping_key - -# Whether this key will be used for IPsec IKE operations. -#ipsec_ike_key -@end example - -@node Invoking gnutls-cli -@section Invoking gnutls-cli +@node The gnutls-cli tool +@section The gnutls-cli tool @cindex gnutls-cli Simple client program to set up a TLS connection to some other @@ -450,54 +106,8 @@ By keeping the @code{--pskusername} parameter and removing the @code{--pskkey} parameter, it will query only for the password during the handshake. -@node Invoking gnutls-cli-debug -@section Invoking gnutls-cli-debug -@cindex gnutls-cli-debug - -This program was created to assist in debugging @acronym{GnuTLS}, but -it might be useful to extract a @acronym{TLS} server's capabilities. -It's purpose is to connect onto a @acronym{TLS} server, perform some -tests and print the server's capabilities. If called with the `-v' -parameter more checks will be performed. An example output is: - -@example -crystal:/cvs/gnutls/src$ ./gnutls-cli-debug localhost -p 5556 -Resolving 'localhost'... -Connecting to '127.0.0.1:5556'... -Checking for TLS 1.1 support... yes -Checking fallback from TLS 1.1 to... N/A -Checking for TLS 1.0 support... yes -Checking for SSL 3.0 support... yes -Checking for version rollback bug in RSA PMS... no -Checking for version rollback bug in Client Hello... no -Checking whether we need to disable TLS 1.0... N/A -Checking whether the server ignores the RSA PMS version... no -Checking whether the server can accept Hello Extensions... yes -Checking whether the server can accept cipher suites not in SSL 3.0 spec... yes -Checking for certificate information... N/A -Checking for trusted CAs... N/A -Checking whether the server understands TLS closure alerts... yes -Checking whether the server supports session resumption... yes -Checking for export-grade ciphersuite support... no -Checking RSA-export ciphersuite info... N/A -Checking for anonymous authentication support... no -Checking anonymous Diffie-Hellman group info... N/A -Checking for ephemeral Diffie-Hellman support... no -Checking ephemeral Diffie-Hellman group info... N/A -Checking for AES cipher support (TLS extension)... yes -Checking for 3DES cipher support... yes -Checking for ARCFOUR 128 cipher support... yes -Checking for ARCFOUR 40 cipher support... no -Checking for MD5 MAC support... yes -Checking for SHA1 MAC support... yes -Checking for ZLIB compression support (TLS extension)... yes -Checking for max record size (TLS extension)... yes -Checking for SRP authentication support (TLS extension)... yes -Checking for OpenPGP authentication support (TLS extension)... no -@end example - -@node Invoking gnutls-serv -@section Invoking gnutls-serv +@node The gnutls-serv tool +@section The gnutls-serv tool @cindex gnutls-serv Simple server program that listens to incoming TLS connections. @@ -723,171 +333,50 @@ gnutls-serv --http \ --pskpasswd psk-passwd.txt @end smallexample -@node Invoking psktool -@section Invoking psktool -@cindex psktool - -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 -PSKtool help -Usage : psktool [options] - -u, --username username - specify username. - -p, --passwd FILE specify a password file. - -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 - -The generation of a PSK password file is illustrated in the example below. -The password is provided in the prompt. - -@smallexample -$ ./psktool -u psk_identity -p psks.txt -Enter password: -Key stored to psks.txt -$ cat psks.txt -psk_identity:88f3824b3e5659f52d00e959bacab954b6540344 -$ -@end smallexample - -@node Invoking srptool -@section Invoking srptool -@anchor{srptool} -@cindex srptool - -The @file{srptool} is a very simple program that emulates the programs -in the @emph{Stanford SRP libraries}@footnote{See -@url{http://srp.stanford.edu/}.}. It is intended for use in places -where you don't expect @acronym{SRP} authentication to be the used for -system users. - -Traditionally @emph{libsrp} used two files. One called @code{tpasswd} -which holds usernames and verifiers, and @code{tpasswd.conf} which -holds generators and primes. - -@subsection How to use srptool - -To create tpasswd.conf which holds the g and n values for -@acronym{SRP} protocol (generator and a large prime), run: - -@smallexample -$ srptool --create-conf /etc/tpasswd.conf -@end smallexample - -This command will create /etc/tpasswd and will add user 'test' (you -will also be prompted for a password). Verifiers are stored by -default in the way libsrp expects. - -@smallexample -$ srptool --passwd /etc/tpasswd \ - --passwd-conf /etc/tpasswd.conf -u test -@end smallexample - -This command will check against a password. If the password matches -the one in /etc/tpasswd you will get an ok. - -@smallexample -$ srptool --passwd /etc/tpasswd \ - --passwd-conf /etc/tpasswd.conf --verify -u test -@end smallexample -@node Invoking p11tool -@section Invoking p11tool -@anchor{p11tool} -@cindex p11tool +@node The gnutls-cli-debug tool +@section The gnutls-cli-debug tool +@cindex gnutls-cli-debug -The @file{p11tool} is a program that helps with accessing tokens -and security modules that support the PKCS #11 API. It requires -the individual PKCS #11 modules to be loaded either with the -@code{--provider} option, or by setting up the GnuTLS configuration -file for PKCS #11 as in @ref{Hardware tokens}. +This program was created to assist in debugging @acronym{GnuTLS}, but +it might be useful to extract a @acronym{TLS} server's capabilities. +It's purpose is to connect onto a @acronym{TLS} server, perform some +tests and print the server's capabilities. If called with the `-v' +parameter more checks will be performed. An example output is: @example -p11tool help -Usage: p11tool [options] -Usage: p11tool --list-tokens -Usage: p11tool --list-all -Usage: p11tool --export 'pkcs11:...' - - --export URL Export an object specified by a pkcs11 - URL - --list-tokens List all available tokens - --list-mechanisms URL List all available mechanisms in token. - --list-all List all objects specified by a PKCS#11 - URL - --list-all-certs List all certificates specified by a - PKCS#11 URL - --list-certs List certificates that have a private - key specified by a PKCS#11 URL - --list-privkeys List private keys specified by a - PKCS#11 URL - --list-trusted List certificates marked as trusted, - specified by a PKCS#11 URL - --initialize URL Initializes a PKCS11 token. - --write URL Writes loaded certificates, private or - secret keys to a PKCS11 token. - --delete URL Deletes objects matching the URL. - --label label Sets a label for the write operation. - --trusted Marks the certificate to be written as - trusted. - --private Marks the object to be written as - private (requires PIN). - --no-private Marks the object to be written as not - private. - --login Force login to token - --detailed-url Export detailed URLs. - --no-detailed-url Export less detailed URLs. - --secret-key HEX_KEY Provide a hex encoded secret key. - --load-privkey FILE Private key file to use. - --load-pubkey FILE Private key file to use. - --load-certificate FILE - Certificate file to use. - -8, --pkcs8 Use PKCS #8 format for private keys. - --inder Use DER format for input certificates - and private keys. - --inraw Use RAW/DER format for input - certificates and private keys. - --provider Library Specify the pkcs11 provider library - --outfile FILE Output file. - -d, --debug LEVEL specify the debug level. Default is 1. - -h, --help shows this help text +crystal:/cvs/gnutls/src$ ./gnutls-cli-debug localhost -p 5556 +Resolving 'localhost'... +Connecting to '127.0.0.1:5556'... +Checking for TLS 1.1 support... yes +Checking fallback from TLS 1.1 to... N/A +Checking for TLS 1.0 support... yes +Checking for SSL 3.0 support... yes +Checking for version rollback bug in RSA PMS... no +Checking for version rollback bug in Client Hello... no +Checking whether we need to disable TLS 1.0... N/A +Checking whether the server ignores the RSA PMS version... no +Checking whether the server can accept Hello Extensions... yes +Checking whether the server can accept cipher suites not in SSL 3.0 spec... yes +Checking for certificate information... N/A +Checking for trusted CAs... N/A +Checking whether the server understands TLS closure alerts... yes +Checking whether the server supports session resumption... yes +Checking for export-grade ciphersuite support... no +Checking RSA-export ciphersuite info... N/A +Checking for anonymous authentication support... no +Checking anonymous Diffie-Hellman group info... N/A +Checking for ephemeral Diffie-Hellman support... no +Checking ephemeral Diffie-Hellman group info... N/A +Checking for AES cipher support (TLS extension)... yes +Checking for 3DES cipher support... yes +Checking for ARCFOUR 128 cipher support... yes +Checking for ARCFOUR 40 cipher support... no +Checking for MD5 MAC support... yes +Checking for SHA1 MAC support... yes +Checking for ZLIB compression support (TLS extension)... yes +Checking for max record size (TLS extension)... yes +Checking for SRP authentication support (TLS extension)... yes +Checking for OpenPGP authentication support (TLS extension)... no @end example -After being provided the available PKCS #11 modules, it can list all tokens -available in your system, the objects on the tokens, and perform operations -on them. - -Some examples on how to use p11tool are illustrated in the following paragraphs. - -@subsection List all tokens -@smallexample -$ p11tool --list-tokens -@end smallexample - -@subsection 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 - -@subsection 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 -$ p11tool --login --export pkcs11:(OBJECT URL) -@end smallexample - -@subsection 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 -$ p11tool --login --write pkcs11:(TOKEN URL) \ - --load-certificate cert.pem --label "my_cert" -@end smallexample - diff --git a/doc/gnutls.texi b/doc/gnutls.texi index fa27d27566..fd4bf1f9ce 100644 --- a/doc/gnutls.texi +++ b/doc/gnutls.texi @@ -152,7 +152,7 @@ Documentation License''. * Authentication methods:: * More on certificate authentication:: * How to use GnuTLS in applications:: -* Included programs:: +* Other included programs:: * Internal architecture of GnuTLS:: * Support:: * Error codes:: |