SUBDIRS += reference
endif
+invoke-gnutls-cli.texi: ../src/cli-args.def
+ cd ../src/ && autogen -Tagtexi-cmd.tpl $<
+ mv ../src/$@ .
+
+invoke-gnutls-cli-debug.texi: ../src/cli-debug-args.def
+ cd ../src/ && autogen -Tagtexi-cmd.tpl $<
+ mv ../src/$@ .
+
+invoke-gnutls-serv.texi: ../src/serv-args.def
+ cd ../src/ && autogen -Tagtexi-cmd.tpl $<
+ mv ../src/$@ .
+
+invoke-certtool.texi: ../src/certtool-args.def
+ cd ../src/ && autogen -Tagtexi-cmd.tpl $<
+ mv ../src/$@ .
+
+invoke-srptool.texi: ../src/srptool-args.def
+ cd ../src/ && autogen -Tagtexi-cmd.tpl $<
+ mv ../src/$@ .
+ sed -i 's/@subsection/@subsubsection/' $@
+ sed -i 's/@section/@subsection/' $@
+
+invoke-ocsptool.texi: ../src/ocsptool-args.def
+ cd ../src/ && autogen -Tagtexi-cmd.tpl $<
+ mv ../src/$@ .
+
+invoke-psktool.texi: ../src/psk-args.def
+ cd ../src/ && autogen -Tagtexi-cmd.tpl $<
+ mv ../src/$@ .
+ sed -i 's/@subsection/@subsubsection/' $@
+ sed -i 's/@section/@subsection/' $@
+
+invoke-p11tool.texi: ../src/p11tool-args.def
+ cd ../src/ && autogen -Tagtexi-cmd.tpl $<
+ mv ../src/$@ .
+ sed -i 's/@subsection/@subsubsection/' $@
+ sed -i 's/@section/@subsection/' $@
+
info_TEXINFOS = gnutls.texi gnutls-guile.texi
gnutls_TEXINFOS = gnutls.texi fdl-1.3.texi \
cha-bib.texi cha-cert-auth.texi cha-cert-auth2.texi \
sec-tls-app.texi cha-errors.texi cha-support.texi \
cha-shared-key.texi cha-gtls-examples.texi
+gnutls_TEXINFOS += invoke-gnutls-cli.texi invoke-gnutls-cli-debug.texi \
+ invoke-gnutls-serv.texi invoke-certtool.texi invoke-srptool.texi \
+ invoke-ocsptool.texi invoke-psktool.texi invoke-p11tool.texi
+
# Examples.
gnutls_TEXINFOS += examples/ex-client-anon.c \
examples/ex-session-info.c examples/ex-verify.c \
* PKIX certificate revocation lists::
* OCSP certificate status checking::
* Managing encrypted keys::
-* The certtool application::
-* The ocsptool application::
+* certtool Invocation:: Invoking certtool
+* ocsptool Invocation:: Invoking ocsptool
* Smart cards and HSMs::
* Abstract key types::
@end menu
@verbatiminclude examples/ex-pkcs12.c
-@node The certtool application
-@section The certtool application
-@cindex certtool
+@include invoke-certtool.texi
-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.
-
-@subheading Diffie-Hellman parameter generation
-To generate parameters for Diffie-Hellman key exchange, use the command:
-@example
-$ certtool --generate-dh-params --outfile dh.pem --sec-param normal
-@end example
-
-@subheading Self-signed certificate generation
-
-To create a self signed certificate, use the command:
-@example
-$ certtool --generate-privkey --outfile ca-key.pem
-$ certtool --generate-self-signed --load-privkey ca-key.pem \
- --outfile ca-cert.pem
-@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:
-
-@example
-$ certtool --generate-privkey --outfile key.pem
-@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:
-
-@example
-$ certtool --generate-certificate --load-privkey key.pem \
- --outfile cert.pem --load-ca-certificate ca-cert.pem \
- --load-ca-privkey ca-key.pem
-@end example
-
-Alternatively you may create a certificate request, which is needed
-when the certificate will be signed by a third party authority.
-
-@example
-$ certtool --generate-request --load-privkey key.pem \
- --outfile request.pem
-@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).
-
-@example
-$ certtool --generate-request --load-privkey pkcs11:(PRIVKEY URL) \
- --load-pubkey pkcs11:(PUBKEY URL) --outfile request.pem
-@end example
-
-To generate a certificate using the previous request, use the command:
-
-@example
-$ certtool --generate-certificate --load-request request.pem \
- --outfile cert.pem \
- --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem
-@end example
-
-@subheading Certificate information
-To view the certificate information, use:
-
-@example
-$ certtool --certificate-info --infile cert.pem
-@end example
-
-@subheading @acronym{PKCS} #12 structure generation
-To generate a @acronym{PKCS} #12 structure using the previous key and
-certificate, use the command:
-
-@example
-$ certtool --load-certificate cert.pem --load-privkey key.pem \
- --to-p12 --outder --outfile key.p12
-@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:
-
-@example
-$ certtool --load-ca-certificate ca.pem \
- --load-certificate cert.pem --load-privkey key.pem \
- --to-p12 --outder --outfile key.p12
-@end example
-
-@subheading 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:
-
-@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 example
-
-@subheading Certificate revocation list generation
-To create an empty Certificate Revocation List (CRL) do:
-
-@example
-$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
- --load-ca-certificate x509-ca.pem
-@end example
-
-To create a CRL that contains some revoked certificates, place the
-certificates in a file and use @code{--load-certificate} as follows:
-
-@example
-$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
- --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem
-@end example
-
-To verify a Certificate Revocation List (CRL) do:
-
-@example
-$ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem
-@end example
-
-
-
-@subheading 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:
-
-@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 example
-
-An example certtool template file that can be used to generate a certificate
-request or a self signed certificate follows.
-
-@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.
-#dn_oid = 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"
-
-# Challenge password used in certificate requests
-challenge_passwd = 123456
-
-# key_purpose_oid = 1.2.3.4.5.6.7
-# key_purpose_oid = 1.2.3.4.5.6.7.9
-
-# 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
-
-# When generating a certificate from a certificate
-# request, then honor the extensions stored in the request
-# and store them in the real certificate.
-#honor_crq_extensions
-
-# Path length contraint. Sets the maximum number of
-# certificates that can be used to certify this certificate.
-# (i.e. the certificate chain length)
-#path_len = -1
-#path_len = 2
-
-# Options for proxy certificates
-# proxy_policy_language = 1.3.6.1.5.5.7.21.1
-
-# Options for generating a CRL
-
-# next CRL update will be in 43 days (wow)
-#crl_next_update = 43
-
-# this is the 5th CRL by this CA
-#crl_number = 5
-
-@end example
-
-@node The ocsptool application
-@section The ocsptool application
-@cindex ocsptool
-
-This is a program that can parse and print information about
-@acronym{OCSP} requests/responses, generate requests and verify
-responses.
-
-@example
-Ocsptool help
-Usage : ocsptool [options]
- -e, --verify-response Verify response.
- -i, --request-info Print information on a OCSP request.
- -j, --response-info Print information on a OCSP response.
- -q, --generate-request Generate a OCSP request.
- --no-nonce don't add nonce to OCSP request.
- --load-issuer FILE read issuer certificate from FILE.
- --load-cert FILE read certificate to check from FILE.
- --load-trust FILE read trust anchors from FILE.
- --inder Use DER format for input certificates.
- -Q, --load-request FILE
- read DER encoded OCSP request from
- FILE.
- -S, --load-response FILE
- read DER encoded OCSP response from
- FILE.
- --outfile FILE Output file.
- --infile FILE Input file.
- -V, --verbose More verbose output.
- -d, --debug integer Enable debugging
- -v, --version prints the program's version number
- -h, --help shows this help text
-@end example
-
-@subheading Print information about an OCSP request
-
-To parse an OCSP request and print information about the content, the
-@code{-i} or @code{--request-info} parameter may be used as follows.
-The @code{-Q} parameter specify the name of the file containing the
-OCSP request, and it should contain the OCSP request in binary DER
-format.
-
-@example
-$ ocsptool -i -Q ocsp-request.der
-@end example
-
-The input file may also be sent to standard input like this:
-
-@example
-$ cat ocsp-request.der | ocsptool --request-info
-@end example
-
-@subheading Print information about an OCSP response
-
-Similar to parsing OCSP requests, OCSP responses can be parsed using
-the @code{-j} or @code{--response-info} as follows.
-
-@example
-$ ocsptool -j -Q ocsp-response.der
-$ cat ocsp-response.der | ocsptool --response-info
-@end example
-
-@subheading Generate an OCSP request
-
-The @code{-q} or @code{--generate-request} parameters are used to
-generate an OCSP request. By default the OCSP request is written to
-standard output in binary DER format, but can be stored in a file
-using @code{--outfile}. To generate an OCSP request the issuer of the
-certificate to check needs to be specified with @code{--load-issuer}
-and the certificate to check with @code{--load-cert}. By default PEM
-format is used for these files, although @code{--inder} can be used to
-specify that the input files are in DER format.
-
-@example
-$ ocsptool -q --load-issuer issuer.pem --load-cert client.pem --outfile ocsp-request.der
-@end example
-
-When generating OCSP requests, the tool will add an OCSP extension
-containing a nonce. This behaviour can be disabled by specifying
-@code{--no-nonce}.
-
-@subheading Verify signature in OCSP response
-
-To verify the signature in an OCSP response the @code{-e} or
-@code{--verify-response} parameter is used. The tool will read an
-OCSP response in DER format from standard input, or from the file
-specified by @code{--load-response}. The OCSP response is verified
-against a set of trust anchors, which are specified using
-@code{--load-trust}. The trust anchors are concatenated certificates
-in PEM format. The certificate that signed the OCSP response needs to
-be in the set of trust anchors, or the issuer of the signer
-certificate needs to be in the set of trust anchors and the OCSP
-Extended Key Usage bit has to be asserted in the signer certificate.
-
-@example
-$ ocsptool -e --load-trust issuer.pem --load-response ocsp-response.der
-@end example
-
-The tool will print status of verification.
-
-@subheading Verify signature in OCSP response against given certificate
-
-It is possible to override the normal trust logic if you know that a
-certain certificate is supposed to have signed the OCSP response, and
-you want to use it to check the signature. This is achieved using
-@code{--load-signer} instead of @code{--load-trust}. This will load
-one certificate and it will be used to verify the signature in the
-OCSP response. It will not check the Extended Key Usage bit.
-
-@example
-$ ocsptool -e --load-signer ocsp-signer.pem --load-response ocsp-response.der
-@end example
-
-This approach is normally only relevant in two situations. The first
-is when the OCSP response does not contain a copy of the signer
-certificate, so the @code{--load-trust} code would fail. The second
-is if you want to avoid the indirect mode where the OCSP response
-signer certificate is signed by a trust anchor.
-
-@subheading Real-world example
-
-Here is an example of how to generate an OCSP request for a
-certificate and to verify the response. For illustration we'll use
-the @code{blog.josefsson.org} host, which (as of writing) uses a
-certificate from CACert. First we'll use @code{gnutls-cli} to get a
-copy of the server certificate chain. The server is not required to
-send this information, but this particular one is configured to do so.
-
-@example
-$ echo | gnutls-cli -p 443 blog.josefsson.org --print-cert > chain.pem
-@end example
-
-Use a text editor on @code{chain.pem} to create three files for each
-separate certificates, called @code{cert.pem} for the first
-certificate for the domain itself, secondly @code{issuer.pem} for the
-intermediate certificate and @code{root.pem} for the final root
-certificate.
-
-The domain certificate normally contains a pointer to where the OCSP
-responder is located, in the Authority Information Access Information
-extension. For example, from @code{certtool -i < cert.pem} there is
-this information:
-
-@example
- Authority Information Access Information (not critical):
- Access Method: 1.3.6.1.5.5.7.48.1 (id-ad-ocsp)
- Access Location URI: http://ocsp.CAcert.org/
-@end example
-
-This means the CA support OCSP queries over HTTP. We are now ready to
-create a OCSP request for the certificate.
-
-@example
-$ ocsptool --generate-request --load-issuer issuer.pem --load-cert cert.pem --outfile ocsp-request.der
-@end example
-
-The request is sent base64 encoded via HTTP to the address indicated
-by the id-ad-ocsp extension, as follows.
-
-@example
-$ wget -O ocsp-response.der http://ocsp.CAcert.org/$(base64 -w0 ocsp-request.der)
-@end example
-
-The OCSP response is now in the file @code{ocsp-response.der} and you
-can view it using @code{ocsptool -j < ocsp-response.der}. To verify
-the signature you need to load the issuer as the trust anchor.
-
-@example
-$ ocsptool --verify-response --load-trust issuer.pem --load-response ocsp-response.der
-Verifying OCSP Response: Success.
-$
-@end example
-
-This particular OCSP responder includes its signer certificate in the
-OCSP respnose, so you may extract it and use it together with
-@code{--load-signer} for verifying the signature directly against the
-certificate.
-
-@example
-$ ocsptool -j < ocsp-response.der > signer.pem
-$ ocsptool --verify-response --load-signer signer.pem --load-response ocsp-response.der
-Verifying OCSP Response: Success.
-$
-@end example
-
-You may experiment passing different certificates to
-@code{--load-trust} and @code{--load-signer} to find common error
-conditions for OCSP response verification failures.
+@include invoke-ocsptool.texi
@node Smart cards and HSMs
@section Smart cards and HSMs
* Reading objects::
* Writing objects::
* Using a PKCS11 token with TLS::
-* The p11tool application::
+* p11tool Invocation:: Invoking p11tool
@end menu
@node PKCS11 Initialization
@showfuncC{gnutls_certificate_set_x509_trust_file,gnutls_certificate_set_x509_key_file,gnutls_certificate_set_x509_simple_pkcs12_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{Smart cards and HSMs}.
-
-@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.
-
-@subsubheading List all tokens
-@example
-$ p11tool --list-tokens
-@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.
-@example
-$ p11tool --login --list-all
-@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.
-@example
-$ p11tool --login --export [OBJECT URL]
-@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.
-@example
-$ p11tool --login --write [TOKEN URL] \
- --load-certificate cert.pem --label "my_cert"
-@end example
-
+@include invoke-p11tool.texi
@node Abstract key types
@section Abstract key types
@end float
Finally the ciphersuites enabled by any priority string can be
-listed using the @code{gnutls-cli} application (see @ref{The gnutls-cli tool}),
+listed using the @code{gnutls-cli} application (see @ref{gnutls-cli Invocation}),
or by using the priority functions as in @ref{Listing the ciphersuites in a priority string}.
Example priority strings are:
application. The applications are discussed in this chapter.
@menu
-* The gnutls-cli tool::
-* The gnutls-serv tool::
-* The gnutls-cli-debug tool::
+* gnutls-cli Invocation:: Invoking gnutls-cli
+* gnutls-serv Invocation:: Invoking gnutls-serv
+* gnutls-cli-debug Invocation:: Invoking gnutls-cli-debug
@end menu
+@c @include invoke-gnutls-cli.menu
+@c @include invoke-gnutls-serv.menu
+@c @include invoke-gnutls-cli-debug.menu
-@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
-computer. It sets up a TLS connection and forwards data from the
-standard input to the secured socket and vice versa.
-
-@example
-GnuTLS test client
-Usage: gnutls-cli [options] hostname
-
- -d, --debug integer Enable debugging
- -r, --resume Connect, establish a session. Connect
- again and resume this session.
- -s, --starttls Connect, establish a plain session and
- start TLS when EOF or a SIGALRM is
- received.
- --crlf Send CR LF instead of LF.
- --x509fmtder Use DER format for certificates to read
- from.
- -f, --fingerprint Send the openpgp fingerprint, instead
- of the key.
- --disable-extensions Disable all the TLS extensions.
- --print-cert Print the certificate in PEM format.
- --recordsize integer The maximum record size to advertize.
- -V, --verbose More verbose output.
- --ciphers cipher1 cipher2...
- Ciphers to enable.
- --protocols protocol1 protocol2...
- Protocols to enable.
- --comp comp1 comp2... Compression methods to enable.
- --macs mac1 mac2... MACs to enable.
- --kx kx1 kx2... Key exchange methods to enable.
- --ctypes certType1 certType2...
- Certificate types to enable.
- --priority PRIORITY STRING
- Priorities string.
- --x509cafile FILE Certificate file to use.
- --x509crlfile FILE CRL file to use.
- --pgpkeyfile FILE PGP Key file to use.
- --pgpkeyring FILE PGP Key ring file to use.
- --pgpcertfile FILE PGP Public Key (certificate) file to
- use.
- --pgpsubkey HEX|auto PGP subkey to use.
- --x509keyfile FILE X.509 key file to use.
- --x509certfile FILE X.509 Certificate file to use.
- --srpusername NAME SRP username to use.
- --srppasswd PASSWD SRP password to use.
- --pskusername NAME PSK username to use.
- --pskkey KEY PSK key (in hex) to use.
- --opaque-prf-input DATA
- Use Opaque PRF Input DATA.
- -p, --port PORT The port to connect to.
- --insecure Don't abort program if server
- certificate can't be validated.
- -l, --list Print a list of the supported
- algorithms and modes.
- -h, --help prints this help
- -v, --version prints the program's version number
-@end example
-
-@subheading Example client PSK connection
-@cindex PSK client
-
-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.
-
-@example
-$ ./gnutls-cli -p 5556 localhost --pskusername psk_identity \
- --pskkey 88f3824b3e5659f52d00e959bacab954b6540344 \
- --priority NORMAL:-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK
-Resolving 'localhost'...
-Connecting to '127.0.0.1:5556'...
-- PSK authentication.
-- Version: TLS1.1
-- Key Exchange: PSK
-- Cipher: AES-128-CBC
-- MAC: SHA1
-- Compression: NULL
-- Handshake was completed
-
-- Simple Client Mode:
-@end example
-
-By keeping the @code{--pskusername} parameter and removing the
-@code{--pskkey} parameter, it will query only for the password during
-the handshake.
-
-@subheading Listing the ciphersuites in a priority string
-@cindex Priority strings
-
-@example
-$ ./gnutls-cli --priority SECURE192 -l
-Cipher suites for SECURE192
-TLS_ECDHE_ECDSA_AES_256_CBC_SHA384 0xc0, 0x24 TLS1.2
-TLS_ECDHE_ECDSA_AES_256_GCM_SHA384 0xc0, 0x2e TLS1.2
-TLS_ECDHE_RSA_AES_256_GCM_SHA384 0xc0, 0x30 TLS1.2
-TLS_DHE_RSA_AES_256_CBC_SHA256 0x00, 0x6b TLS1.2
-TLS_DHE_DSS_AES_256_CBC_SHA256 0x00, 0x6a TLS1.2
-TLS_RSA_AES_256_CBC_SHA256 0x00, 0x3d TLS1.2
-
-Certificate types: CTYPE-X.509
-Protocols: VERS-TLS1.2, VERS-TLS1.1, VERS-TLS1.0, VERS-SSL3.0, VERS-DTLS1.0
-Compression: COMP-NULL
-Elliptic curves: CURVE-SECP384R1, CURVE-SECP521R1
-PK-signatures: SIGN-RSA-SHA384, SIGN-ECDSA-SHA384, SIGN-RSA-SHA512, SIGN-ECDSA-SHA512
-@end example
-
-
-@node The gnutls-serv tool
-@section The gnutls-serv tool
-@cindex gnutls-serv
-
-Simple server program that listens to incoming TLS connections.
-
-@example
-GnuTLS test server
-Usage: gnutls-serv [options]
-
- -d, --debug integer Enable debugging
- -g, --generate Generate Diffie-Hellman Parameters.
- -p, --port integer The port to connect to.
- -q, --quiet Suppress some messages.
- --nodb Does not use the resume database.
- --http Act as an HTTP Server.
- --echo Act as an Echo Server.
- --dhparams FILE DH params file to use.
- --x509fmtder Use DER format for certificates
- --x509cafile FILE Certificate file to use.
- --x509crlfile FILE CRL file to use.
- --pgpkeyring FILE PGP Key ring file to use.
- --pgpkeyfile FILE PGP Key file to use.
- --pgpcertfile FILE PGP Public Key (certificate) file to
- use.
- --pgpsubkey HEX|auto PGP subkey to use.
- --x509keyfile FILE X.509 key file to use.
- --x509certfile FILE X.509 Certificate file to use.
- --x509dsakeyfile FILE Alternative X.509 key file to use.
- --x509dsacertfile FILE Alternative X.509 certificate file to
- use.
- -r, --require-cert Require a valid certificate.
- -a, --disable-client-cert
- Disable request for a client
- certificate.
- --pskpasswd FILE PSK password file to use.
- --pskhint HINT PSK identity hint to use.
- --srppasswd FILE SRP password file to use.
- --srppasswdconf FILE SRP password conf file to use.
- --opaque-prf-input DATA
- Use Opaque PRF Input DATA.
- --ciphers cipher1 cipher2...
- Ciphers to enable.
- --protocols protocol1 protocol2...
- Protocols to enable.
- --comp comp1 comp2... Compression methods to enable.
- --macs mac1 mac2... MACs to enable.
- --kx kx1 kx2... Key exchange methods to enable.
- --ctypes certType1 certType2...
- Certificate types to enable.
- --priority PRIORITY STRING
- Priorities string.
- -l, --list Print a list of the supported
- algorithms and modes.
- -h, --help prints this help
- -v, --version prints the program's version number
-@end example
-
-@subheading Setting up a test HTTPS server
-@cindex HTTPS server
-@cindex debug server
-
-Running your own TLS server based on GnuTLS can be useful when
-debugging clients and/or GnuTLS itself. This section describes how to
-use @code{gnutls-serv} as a simple HTTPS server.
-
-The most basic server can be started as:
-
-@example
-gnutls-serv --http
-@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:
-
-@example
-$ certtool --generate-privkey > x509-ca-key.pem
-$ echo 'cn = GnuTLS test CA' > ca.tmpl
-$ echo 'ca' >> ca.tmpl
-$ echo 'cert_signing_key' >> ca.tmpl
-$ certtool --generate-self-signed --load-privkey x509-ca-key.pem \
- --template ca.tmpl --outfile x509-ca.pem
-...
-@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
-the field.
-
-@example
-$ certtool --generate-privkey > x509-server-key.pem
-$ echo 'organization = GnuTLS test server' > server.tmpl
-$ echo 'cn = test.gnutls.org' >> server.tmpl
-$ echo 'tls_www_server' >> server.tmpl
-$ echo 'encryption_key' >> server.tmpl
-$ echo 'signing_key' >> server.tmpl
-$ echo 'dns_name = test.gnutls.org' >> server.tmpl
-$ certtool --generate-certificate --load-privkey x509-server-key.pem \
- --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
- --template server.tmpl --outfile x509-server.pem
-...
-@end example
-
-For use in the client, you may want to generate a client certificate
-as well.
-
-@example
-$ certtool --generate-privkey > x509-client-key.pem
-$ echo 'cn = GnuTLS test client' > client.tmpl
-$ echo 'tls_www_client' >> client.tmpl
-$ echo 'encryption_key' >> client.tmpl
-$ echo 'signing_key' >> client.tmpl
-$ certtool --generate-certificate --load-privkey x509-client-key.pem \
- --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
- --template client.tmpl --outfile x509-client.pem
-...
-@end example
-
-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.
-
-@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 example
-
-For icing, we'll create a proxy certificate for the client too.
-
-@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-ca-certificate x509-client.pem --load-ca-privkey x509-client-key.pem \
- --load-certificate x509-client.pem --template proxy.tmpl \
- --outfile x509-proxy.pem
-...
-@end example
-
-Then start the server again:
-
-@example
-$ gnutls-serv --http \
- --x509cafile x509-ca.pem \
- --x509keyfile x509-server-key.pem \
- --x509certfile x509-server.pem
-@end example
-
-Try connecting to the server using your web browser. Note that the
-server listens to port 5556 by default.
-
-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.
-
-@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 example
-
-The next step is to create OpenPGP credentials for the server.
-
-@example
-gpg --gen-key
-...enter whatever details you want, use 'test.gnutls.org' as name...
-@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.
-
-@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 example
-
-Let's start the server with support for OpenPGP credentials:
-
-@example
-gnutls-serv --http \
- --pgpkeyfile openpgp-server-key.txt \
- --pgpcertfile openpgp-server.txt
-@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:
-
-@example
-gnutls-serv --http \
- --srppasswdconf srp-tpasswd.conf \
- --srppasswd srp-passwd.txt
-@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}).
-
-@example
-gnutls-serv --http \
- --pskpasswd psk-passwd.txt
-@end example
-
-Finally, we start the server with all the earlier parameters and you
-get this command:
-
-@example
-gnutls-serv --http \
- --x509cafile x509-ca.pem \
- --x509keyfile x509-server-key.pem \
- --x509certfile x509-server.pem \
- --x509dsakeyfile x509-server-key-dsa.pem \
- --x509dsacertfile x509-server-dsa.pem \
- --pgpkeyfile openpgp-server-key.txt \
- --pgpcertfile openpgp-server.txt \
- --srppasswdconf srp-tpasswd.conf \
- --srppasswd srp-passwd.txt \
- --pskpasswd psk-passwd.txt
-@end example
-
-
-@node The gnutls-cli-debug tool
-@section The gnutls-cli-debug tool
-@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
-
+@include invoke-gnutls-cli.texi
+@include invoke-gnutls-serv.texi
+@include invoke-gnutls-cli-debug.texi
@menu
* Authentication using SRP::
-* Invoking srptool::
+* srptool Invocation:: Invoking srptool
@end menu
@node Authentication using SRP
Helper functions are included in @acronym{GnuTLS}, used to generate and
maintain @acronym{SRP} verifiers and password files. A program to
manipulate the required parameters for @acronym{SRP} authentication is
-also included. See @ref{srptool}, for more information.
+also included. See @ref{srptool Invocation}, for more information.
@showfuncdesc{gnutls_srp_verifier}
@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:
-
-@example
-$ srptool --create-conf /etc/tpasswd.conf
-@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.
-
-@example
-$ srptool --passwd /etc/tpasswd \
- --passwd-conf /etc/tpasswd.conf -u test
-@end example
-
-This command will check against a password. If the password matches
-the one in /etc/tpasswd you will get an ok.
-
-@example
-$ srptool --passwd /etc/tpasswd \
- --passwd-conf /etc/tpasswd.conf --verify -u test
-@end example
+@include invoke-srptool.texi
@node PSK authentication
@section PSK authentication
@menu
* Authentication using PSK::
-* Invoking psktool::
+* psktool Invocation:: Invoking psktool
@end menu
@node Authentication using PSK
@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.
-
-@example
-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 example
-
-The generation of a PSK password file is illustrated in the example below.
-The password is provided in the prompt.
-
-@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 example
+@include invoke-psktool.texi
@node Anonymous authentication
@section Anonymous authentication
prog-name = certtool;
prog-title = "GnuTLS PKCS #11 tool";
prog-desc = "Manipulate certificates and private keys.";
-detail = "Tool to parse and generate X.509 certificates, requests and private keys.";
+detail = "Tool to parse and generate X.509 certificates, requests and private keys.
+It can be used interactively or non interactively by
+specifying the template command line option.";
help-value = "h";
short-usage = "certtool [options] [url]\ncerttool --help for usage instructions.\n";
prog-group = "GnuTLS";
doc-section = {
ds-type = 'SEE ALSO';
- ds-format = 'man';
+ ds-format = 'texi';
ds-text = <<-_EOT_
p11tool (1)
_EOT_;
ds-type = 'EXAMPLES';
ds-format = 'texi';
ds-text = <<-_EOT_
-To create a private key, run:
+@subheading Generating private keys
+To create an RSA private key, run:
@example
-$ certtool --generate-privkey --outfile key.pem
+$ certtool --generate-privkey --outfile key.pem --rsa
@end example
+To create a DSA or elliptic curves (ECDSA) private key use the
+above command combined with 'dsa' or 'ecc' options.
+
+@subheading Generating certificate requests
To create a certificate request (needed when the certificate is issued by
another party), run:
@example
--outfile request.pem
@end example
-To create a certificate request using a key stored in a PKCS #11 token, run:
+If the private key is stored in a smart card you can generate
+a request by specifying the private key object URL.
@example
$ ./certtool --generate-request --load-privkey "pkcs11:..." \
--load-pubkey "pkcs11:..." --outfile request.pem
@end example
+
+@subheading Generating a self-signed certificate
+To create a self signed certificate, use the command:
+@example
+$ certtool --generate-privkey --outfile ca-key.pem
+$ certtool --generate-self-signed --load-privkey ca-key.pem \
+ --outfile ca-cert.pem
+@end example
+
+Note that a self-signed certificate usually belongs to a certificate
+authority, that signs other certificates.
+
+@subheading Generating a certificate
To generate a certificate using the previous request, use the command:
@example
$ certtool --generate-certificate --load-request request.pem \
--load-ca-privkey ca-key.pem
@end example
+@subheading Certificate information
To view the certificate information, use:
@example
$ certtool --certificate-info --infile cert.pem
@end example
+@subheading PKCS #12 structure generation
To generate a PKCS #12 structure using the previous key and certificate,
use the command:
@example
--to-p12 --outder --outfile key.p12
@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:
+
+@example
+$ certtool --load-ca-certificate ca.pem \
+ --load-certificate cert.pem --load-privkey key.pem \
+ --to-p12 --outder --outfile key.p12
+@end example
+
+@subheading Diffie-Hellman parameter generation
+To generate parameters for Diffie-Hellman key exchange, use the command:
+@example
+$ certtool --generate-dh-params --outfile dh.pem --sec-param normal
+@end example
+
+@subheading 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:
+
+@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 example
+
+@subheading Certificate revocation list generation
+To create an empty Certificate Revocation List (CRL) do:
+
+@example
+$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
+ --load-ca-certificate x509-ca.pem
+@end example
+
+To create a CRL that contains some revoked certificates, place the
+certificates in a file and use @code{--load-certificate} as follows:
+
+@example
+$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
+ --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem
+@end example
+
+To verify a Certificate Revocation List (CRL) do:
+
+@example
+$ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem
+@end example
+_EOT_;
+};
+
+
+doc-section = {
+ ds-type = 'FILES';
+ ds-format = 'texi';
+ ds-text = <<-_EOT_
+@subheading 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:
+
+@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 example
+
+An example certtool template file that can be used to generate a certificate
+request or a self signed certificate follows.
+
+@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.
+#dn_oid = 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"
+
+# Challenge password used in certificate requests
+challenge_passwd = 123456
+
+# key_purpose_oid = 1.2.3.4.5.6.7
+# key_purpose_oid = 1.2.3.4.5.6.7.9
+
+# 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
+
+# When generating a certificate from a certificate
+# request, then honor the extensions stored in the request
+# and store them in the real certificate.
+#honor_crq_extensions
+
+# Path length contraint. Sets the maximum number of
+# certificates that can be used to certify this certificate.
+# (i.e. the certificate chain length)
+#path_len = -1
+#path_len = 2
+
+# Options for proxy certificates
+# proxy_policy_language = 1.3.6.1.5.5.7.21.1
+
+# Options for generating a CRL
+
+# next CRL update will be in 43 days (wow)
+#crl_next_update = 43
+
+# this is the 5th CRL by this CA
+#crl_number = 5
+
+@end example
+
_EOT_;
};
TLS_DHE_RSA_AES_256_CBC_SHA256 0x00, 0x6b TLS1.2
TLS_DHE_DSS_AES_256_CBC_SHA256 0x00, 0x6a TLS1.2
TLS_RSA_AES_256_CBC_SHA256 0x00, 0x3d TLS1.2
+
+Certificate types: CTYPE-X.509
+Protocols: VERS-TLS1.2, VERS-TLS1.1, VERS-TLS1.0, VERS-SSL3.0, VERS-DTLS1.0
+Compression: COMP-NULL
+Elliptic curves: CURVE-SECP384R1, CURVE-SECP521R1
+PK-signatures: SIGN-RSA-SHA384, SIGN-ECDSA-SHA384, SIGN-RSA-SHA512, SIGN-ECDSA-SHA512
@end example
_EOF_;
};
prog-group = "GnuTLS";
explain = "";
detail = "TLS debug client. It sets up multiple TLS connections to
-a server and queries its capabilities. Can be used to check for servers with
-special needs or bugs.";
+a server and queries its capabilities. It was created to assist in debugging
+GnuTLS, but it might be useful to extract a TLS server's capabilities.
+It connects to a TLS server, performs tests and print the server's
+capabilities. If called with the `-v' parameter more checks will be performed.
+Can be used to check for servers with special needs or bugs.";
gnu-usage;
no-xlate = opt;
no-misuse-usage;
_EOText_;
};
+doc-section = {
+ ds-type = 'EXAMPLES';
+ ds-format = 'texi';
+ ds-text = <<-_EOF_
+@example
+$ ../src/gnutls-cli-debug localhost
+Resolving 'localhost'...
+Connecting to '127.0.0.1:443'...
+Checking for SSL 3.0 support... yes
+Checking whether %COMPAT is required... no
+Checking for TLS 1.0 support... yes
+Checking for TLS 1.1 support... no
+Checking fallback from TLS 1.1 to... TLS 1.0
+Checking for TLS 1.2 support... no
+Checking whether we need to disable TLS 1.0... N/A
+Checking for Safe renegotiation support... yes
+Checking for Safe renegotiation support (SCSV)... yes
+Checking for HTTPS server name... not checked
+Checking for version rollback bug in RSA PMS... no
+Checking for version rollback bug in Client Hello... no
+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 small records (512 bytes)... yes
+Checking whether the server can accept cipher suites not in SSL 3.0 spec... yes
+Checking whether the server can accept a bogus TLS record version in the client hello... yes
+Checking for certificate information... N/A
+Checking for trusted CAs... N/A
+Checking whether the server understands TLS closure alerts... partially
+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 ephemeral EC Diffie-Hellman support... yes
+Checking ephemeral EC Diffie-Hellman group info...
+ Curve SECP256R1
+Checking for AES-GCM cipher support... no
+Checking for AES-CBC cipher support... yes
+Checking for CAMELLIA cipher support... no
+Checking for 3DES-CBC 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 SHA256 MAC support... no
+Checking for ZLIB compression support... no
+Checking for max record size... no
+Checking for OpenPGP authentication support... no
+@end example
+_EOF_;
+};
+
prog-title = "GnuTLS OCSP tool";
prog-desc = "Program to handle OCSP request/responses.";
help-value = "h";
-detail = "Ocsptool can parse OCSP request/responses, generate OCSP requests and verify OCSP responses.";
-
+detail = "Ocsptool is a program that can parse and print information about
+OCSP requests/responses, generate requests and verify responses.
+";
short-usage = "ocsptool [options]\nocsptool --help for usage instructions.\n";
prog-group = "GnuTLS";
explain = "";
doc-section = {
ds-type = 'SEE ALSO';
- ds-format = 'man';
+ ds-format = 'texi';
ds-text = <<-_EOT_
certtool (1)
_EOT_;
};
+doc-section = {
+ ds-type = 'EXAMPLES';
+ ds-format = 'texi';
+ ds-text = <<-_EOF_
+@subheading Print information about an OCSP request
+
+To parse an OCSP request and print information about the content, the
+@code{-i} or @code{--request-info} parameter may be used as follows.
+The @code{-Q} parameter specify the name of the file containing the
+OCSP request, and it should contain the OCSP request in binary DER
+format.
+
+@example
+$ ocsptool -i -Q ocsp-request.der
+@end example
+
+The input file may also be sent to standard input like this:
+
+@example
+$ cat ocsp-request.der | ocsptool --request-info
+@end example
+
+@subheading Print information about an OCSP response
+
+Similar to parsing OCSP requests, OCSP responses can be parsed using
+the @code{-j} or @code{--response-info} as follows.
+
+@example
+$ ocsptool -j -Q ocsp-response.der
+$ cat ocsp-response.der | ocsptool --response-info
+@end example
+
+@subheading Generate an OCSP request
+
+The @code{-q} or @code{--generate-request} parameters are used to
+generate an OCSP request. By default the OCSP request is written to
+standard output in binary DER format, but can be stored in a file
+using @code{--outfile}. To generate an OCSP request the issuer of the
+certificate to check needs to be specified with @code{--load-issuer}
+and the certificate to check with @code{--load-cert}. By default PEM
+format is used for these files, although @code{--inder} can be used to
+specify that the input files are in DER format.
+
+@example
+$ ocsptool -q --load-issuer issuer.pem --load-cert client.pem --outfile ocsp-request.der
+@end example
+
+When generating OCSP requests, the tool will add an OCSP extension
+containing a nonce. This behaviour can be disabled by specifying
+@code{--no-nonce}.
+
+@subheading Verify signature in OCSP response
+
+To verify the signature in an OCSP response the @code{-e} or
+@code{--verify-response} parameter is used. The tool will read an
+OCSP response in DER format from standard input, or from the file
+specified by @code{--load-response}. The OCSP response is verified
+against a set of trust anchors, which are specified using
+@code{--load-trust}. The trust anchors are concatenated certificates
+in PEM format. The certificate that signed the OCSP response needs to
+be in the set of trust anchors, or the issuer of the signer
+certificate needs to be in the set of trust anchors and the OCSP
+Extended Key Usage bit has to be asserted in the signer certificate.
+
+@example
+$ ocsptool -e --load-trust issuer.pem --load-response ocsp-response.der
+@end example
+
+The tool will print status of verification.
+
+@subheading Verify signature in OCSP response against given certificate
+
+It is possible to override the normal trust logic if you know that a
+certain certificate is supposed to have signed the OCSP response, and
+you want to use it to check the signature. This is achieved using
+@code{--load-signer} instead of @code{--load-trust}. This will load
+one certificate and it will be used to verify the signature in the
+OCSP response. It will not check the Extended Key Usage bit.
+
+@example
+$ ocsptool -e --load-signer ocsp-signer.pem --load-response ocsp-response.der
+@end example
+
+This approach is normally only relevant in two situations. The first
+is when the OCSP response does not contain a copy of the signer
+certificate, so the @code{--load-trust} code would fail. The second
+is if you want to avoid the indirect mode where the OCSP response
+signer certificate is signed by a trust anchor.
+
+@subheading Real-world example
+
+Here is an example of how to generate an OCSP request for a
+certificate and to verify the response. For illustration we'll use
+the @code{blog.josefsson.org} host, which (as of writing) uses a
+certificate from CACert. First we'll use @code{gnutls-cli} to get a
+copy of the server certificate chain. The server is not required to
+send this information, but this particular one is configured to do so.
+
+@example
+$ echo | gnutls-cli -p 443 blog.josefsson.org --print-cert > chain.pem
+@end example
+
+Use a text editor on @code{chain.pem} to create three files for each
+separate certificates, called @code{cert.pem} for the first
+certificate for the domain itself, secondly @code{issuer.pem} for the
+intermediate certificate and @code{root.pem} for the final root
+certificate.
+
+The domain certificate normally contains a pointer to where the OCSP
+responder is located, in the Authority Information Access Information
+extension. For example, from @code{certtool -i < cert.pem} there is
+this information:
+
+@example
+ Authority Information Access Information (not critical):
+ Access Method: 1.3.6.1.5.5.7.48.1 (id-ad-ocsp)
+ Access Location URI: http://ocsp.CAcert.org/
+@end example
+
+This means the CA support OCSP queries over HTTP. We are now ready to
+create a OCSP request for the certificate.
+
+@example
+$ ocsptool --generate-request --load-issuer issuer.pem --load-cert cert.pem --outfile ocsp-request.der
+@end example
+
+The request is sent base64 encoded via HTTP to the address indicated
+by the id-ad-ocsp extension, as follows.
+
+@example
+$ wget -O ocsp-response.der http://ocsp.CAcert.org/$(base64 -w0 ocsp-request.der)
+@end example
+
+The OCSP response is now in the file @code{ocsp-response.der} and you
+can view it using @code{ocsptool -j < ocsp-response.der}. To verify
+the signature you need to load the issuer as the trust anchor.
+
+@example
+$ ocsptool --verify-response --load-trust issuer.pem --load-response ocsp-response.der
+Verifying OCSP Response: Success.
+$
+@end example
+
+This particular OCSP responder includes its signer certificate in the
+OCSP respnose, so you may extract it and use it together with
+@code{--load-signer} for verifying the signature directly against the
+certificate.
+
+@example
+$ ocsptool -j < ocsp-response.der > signer.pem
+$ ocsptool --verify-response --load-signer signer.pem --load-response ocsp-response.der
+Verifying OCSP Response: Success.
+$
+@end example
+
+You may experiment passing different certificates to
+@code{--load-trust} and @code{--load-signer} to find common error
+conditions for OCSP response verification failures.
+
+_EOF_;
+};
+
doc-section = {
ds-type = 'SEE ALSO';
- ds-format = 'man';
+ ds-format = 'texi';
ds-text = <<-_EOT_
certtool (1)
_EOT_;
doc-section = {
ds-type = 'SEE ALSO';
- ds-format = 'man';
+ ds-format = 'texi';
ds-text = <<-_EOT_
gnutls-cli-debug (1), gnutls-serv (1), srptool (1), certtool (1)
_EOT_;
ds-type = 'EXAMPLES';
ds-format = 'texi';
ds-text = <<-_EOT_
-To add a user 'test' in @file{passwd.psk} for use with GnuTLS run:
+To add a user 'psk_identity' in @file{passwd.psk} for use with GnuTLS run:
@example
-$ psktool --passwd /etc/passwd.psk -u test
+$ ./psktool -u psk_identity -p passwd.psk
+Generating a random key for user 'psk_identity'
+Key stored to passwd.psk
+$ cat psks.txt
+psk_identity:88f3824b3e5659f52d00e959bacab954b6540344
+$
@end example
This command will create @file{/etc/passwd.psk} if it does not exist
doc-section = {
ds-type = 'SEE ALSO'; // or anything else
- ds-format = 'man'; // or texi or mdoc format
+ ds-format = 'texi'; // or texi or mdoc format
ds-text = <<-_EOText_
gnutls-cli-debug(1), gnutls-cli(1)
_EOText_;
};
+
+doc-section = {
+ ds-type = 'EXAMPLES';
+ ds-format = 'texi';
+ ds-text = <<-_EOF_
+Running your own TLS server based on GnuTLS can be useful when
+debugging clients and/or GnuTLS itself. This section describes how to
+use @code{gnutls-serv} as a simple HTTPS server.
+
+The most basic server can be started as:
+
+@example
+gnutls-serv --http
+@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:
+
+@example
+$ certtool --generate-privkey > x509-ca-key.pem
+$ echo 'cn = GnuTLS test CA' > ca.tmpl
+$ echo 'ca' >> ca.tmpl
+$ echo 'cert_signing_key' >> ca.tmpl
+$ certtool --generate-self-signed --load-privkey x509-ca-key.pem \
+ --template ca.tmpl --outfile x509-ca.pem
+...
+@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
+the field.
+
+@example
+$ certtool --generate-privkey > x509-server-key.pem
+$ echo 'organization = GnuTLS test server' > server.tmpl
+$ echo 'cn = test.gnutls.org' >> server.tmpl
+$ echo 'tls_www_server' >> server.tmpl
+$ echo 'encryption_key' >> server.tmpl
+$ echo 'signing_key' >> server.tmpl
+$ echo 'dns_name = test.gnutls.org' >> server.tmpl
+$ certtool --generate-certificate --load-privkey x509-server-key.pem \
+ --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
+ --template server.tmpl --outfile x509-server.pem
+...
+@end example
+
+For use in the client, you may want to generate a client certificate
+as well.
+
+@example
+$ certtool --generate-privkey > x509-client-key.pem
+$ echo 'cn = GnuTLS test client' > client.tmpl
+$ echo 'tls_www_client' >> client.tmpl
+$ echo 'encryption_key' >> client.tmpl
+$ echo 'signing_key' >> client.tmpl
+$ certtool --generate-certificate --load-privkey x509-client-key.pem \
+ --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
+ --template client.tmpl --outfile x509-client.pem
+...
+@end example
+
+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.
+
+@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 example
+
+For icing, we'll create a proxy certificate for the client too.
+
+@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-ca-certificate x509-client.pem --load-ca-privkey x509-client-key.pem \
+ --load-certificate x509-client.pem --template proxy.tmpl \
+ --outfile x509-proxy.pem
+...
+@end example
+
+Then start the server again:
+
+@example
+$ gnutls-serv --http \
+ --x509cafile x509-ca.pem \
+ --x509keyfile x509-server-key.pem \
+ --x509certfile x509-server.pem
+@end example
+
+Try connecting to the server using your web browser. Note that the
+server listens to port 5556 by default.
+
+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.
+
+@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 example
+
+The next step is to create OpenPGP credentials for the server.
+
+@example
+gpg --gen-key
+...enter whatever details you want, use 'test.gnutls.org' as name...
+@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.
+
+@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 example
+
+Let's start the server with support for OpenPGP credentials:
+
+@example
+gnutls-serv --http \
+ --pgpkeyfile openpgp-server-key.txt \
+ --pgpcertfile openpgp-server.txt
+@end example
+
+The next step is to add support for SRP authentication. This requires
+an SRP password file created with @code{srptool}.
+To start the server with SRP support:
+
+@example
+gnutls-serv --http \
+ --srppasswdconf srp-tpasswd.conf \
+ --srppasswd srp-passwd.txt
+@end example
+
+Let's also start a server with support for PSK. This would require
+a password file created with @code{psktool}.
+
+@example
+gnutls-serv --http \
+ --pskpasswd psk-passwd.txt
+@end example
+
+Finally, we start the server with all the earlier parameters and you
+get this command:
+
+@example
+gnutls-serv --http \
+ --x509cafile x509-ca.pem \
+ --x509keyfile x509-server-key.pem \
+ --x509certfile x509-server.pem \
+ --x509dsakeyfile x509-server-key-dsa.pem \
+ --x509dsacertfile x509-server-dsa.pem \
+ --pgpkeyfile openpgp-server-key.txt \
+ --pgpcertfile openpgp-server.txt \
+ --srppasswdconf srp-tpasswd.conf \
+ --srppasswd srp-passwd.txt \
+ --pskpasswd psk-passwd.txt
+@end example
+_EOF_;
+};
+
doc-section = {
ds-type = 'SEE ALSO';
- ds-format = 'man';
+ ds-format = 'texi';
ds-text = <<-_EOT_
gnutls-cli-debug (1), gnutls-serv (1), srptool (1), psktool (1), certtool (1)
_EOT_;
projects / thirdparty / gnutls.git / commitdiff
