@node Included programs @chapter 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:: @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 @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 @menu * Example client PSK connection:: @end menu @node Example client PSK connection @subsection Example client PSK connection @cindex PSK client To connect to a server using PSK authentication, you may use something like: @smallexample $ gnutls-cli -p 5556 test.gnutls.org --pskusername jas \ --pskkey 9e32cf7786321a828ef7668f09fb35db \ --priority NORMAL:-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK @end smallexample If your server only supports the PSK ciphersuite, connecting to it should be as simple as connecting to the server: @smallexample $ ./gnutls-cli -p 5556 localhost Resolving 'localhost'... Connecting to '127.0.0.1:5556'... - PSK client callback. Enter PSK identity: psk_identity Enter password: - PSK authentication. - Version: TLS1.1 - Key Exchange: PSK - Cipher: AES-128-CBC - MAC: SHA1 - Compression: NULL - Handshake was completed - Simple Client Mode: @end smallexample If the server supports several cipher suites, you may need to force it to chose PSK by using a cipher priority parameter such as in the example below: @smallexample $ ./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 smallexample 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 @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 @subsection 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: @smallexample gnutls-serv --http @end smallexample It will only support anonymous ciphersuites, which many TLS clients refuse to use. The next step is to add support for X.509. First we generate a CA: @smallexample $ 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 smallexample 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. @smallexample $ certtool --to-p12 --load-ca-certificate x509-ca.pem \ --load-privkey x509-client-key.pem --load-certificate x509-client.pem \ --outder --outfile x509-client.p12 @end smallexample For icing, we'll create a proxy certificate for the client too. @smallexample $ 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 smallexample Then start the server again: @smallexample $ gnutls-serv --http \ --x509cafile x509-ca.pem \ --x509keyfile x509-server-key.pem \ --x509certfile x509-server.pem @end smallexample 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. @smallexample $ certtool --generate-privkey --dsa > x509-server-key-dsa.pem $ certtool --generate-certificate --load-privkey x509-server-key-dsa.pem \ --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \ --template server.tmpl --outfile x509-server-dsa.pem ... @end smallexample The next step is to create OpenPGP credentials for the server. @smallexample gpg --gen-key ...enter whatever details you want, use 'test.gnutls.org' as name... @end smallexample Make a note of the OpenPGP key identifier of the newly generated key, here it was @code{5D1D14D8}. You will need to export the key for GnuTLS to be able to use it. @smallexample gpg -a --export 5D1D14D8 > openpgp-server.txt gpg --export 5D1D14D8 > openpgp-server.bin gpg --export-secret-keys 5D1D14D8 > openpgp-server-key.bin gpg -a --export-secret-keys 5D1D14D8 > openpgp-server-key.txt @end smallexample Let's start the server with support for OpenPGP credentials: @smallexample gnutls-serv --http \ --pgpkeyfile openpgp-server-key.txt \ --pgpcertfile openpgp-server.txt @end smallexample The next step is to add support for SRP authentication. @smallexample srptool --create-conf srp-tpasswd.conf srptool --passwd-conf srp-tpasswd.conf --username jas --passwd srp-passwd.txt Enter password: [TYPE "foo"] @end smallexample Start the server with SRP support: @smallexample gnutls-serv --http \ --srppasswdconf srp-tpasswd.conf \ --srppasswd srp-passwd.txt @end smallexample Let's also add support for PSK. @smallexample $ psktool --passwd psk-passwd.txt @end smallexample Start the server with PSK support: @smallexample gnutls-serv --http \ --pskpasswd psk-passwd.txt @end smallexample Finally, we start the server with all the earlier parameters and you get this command: @smallexample 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 smallexample @menu * Example server PSK connection:: @end menu @node Example server PSK connection @subsection Example server PSK connection @cindex PSK server To set up a PSK server with @code{gnutls-serv} you need to create PSK password file. This is illustrated in the example below, where a password is provided at 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 After this, start the server pointing to the password file. We disable DHE-PSK. @smallexample $ ./gnutls-serv --pskpasswd psks.txt --pskhint psk_identity_hint \ --priority NORMAL:-DHE-PSK Set static Diffie-Hellman parameters, consider --dhparams. Echo Server ready. Listening to port '5556'. @end smallexample You can now connect to the server using a PSK client as in @ref{Example client PSK connection}. @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 @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 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}. @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. @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