@node certtool Invocation @section Invoking certtool @pindex certtool @cindex GnuTLS PKCS #11 tool @ignore # -*- buffer-read-only: t -*- vi: set ro: # # DO NOT EDIT THIS FILE (invoke-certtool.texi) # # It has been AutoGen-ed August 4, 2012 at 01:15:27 PM by AutoGen 5.16 # From the definitions ../src/certtool-args.def # and the template file agtexi-cmd.tpl @end ignore 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. This section was generated by @strong{AutoGen}, using the @code{agtexi-cmd} template and the option descriptions for the @code{certtool} program. This software is released under the GNU General Public License, version 3 or later. @anchor{certtool usage} @subheading certtool help/usage (-h) @cindex certtool help This is the automatically generated usage text for certtool. The text printed is the same whether for the @code{help} option (-h) or the @code{more-help} option (-!). @code{more-help} will print the usage text by passing it through a pager program. @code{more-help} is disabled on platforms without a working @code{fork(2)} function. The @code{PAGER} environment variable is used to select the program, defaulting to @file{more}. Both will exit with a status code of 0. @exampleindent 0 @example certtool - GnuTLS PKCS #11 tool - Ver. @@VERSION@@ USAGE: certtool [ - [] | --[@{=| @}] ]... -d, --debug=num Enable debugging. - It must be in the range: 0 to 9999 --infile=file Input file - file must pre-exist --outfile=str Output file -s, --generate-self-signed Generate a self-signed certificate -c, --generate-certificate Generate a signed certificate --generate-proxy Generates 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. --verify Verify a PEM encoded certificate chain using a trusted list. - requires these options: load-ca-certificate --verify-crl Verify a CRL using a trusted list. - requires these options: load-ca-certificate --generate-dh-params Generate PKCS #3 encoded Diffie-Hellman parameters. --get-dh-params Get the included PKCS #3 encoded Diffie-Hellman parameters. --dh-info Print information PKCS #3 encoded Diffie-Hellman parameters --load-privkey=str Loads a private key file --load-pubkey=str Loads a public key file --load-request=file Loads a certificate request file - file must pre-exist --load-certificate=str Loads a certificate file --load-ca-privkey=str Loads the certificate authority's private key file --load-ca-certificate=str Loads the certificate authority's certificate file --password=str Password to use --null-password Enforce a NULL password -i, --certificate-info Print information on the given certificate --certificate-pubkey Print certificate's public key --pgp-certificate-info Print information on the given OpenPGP certificate --pgp-ring-info Print information on the given OpenPGP keyring structure -l, --crl-info Print information on the given CRL structure --crq-info Print information on the given 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 an OpenPGP private key --pubkey-info Print information on a public key --v1 Generate an X.509 version 1 certificate (with no extensions) --to-p12 Generate a PKCS #12 structure - requires these options: load-certificate --to-p8 Generate a PKCS #8 structure -8, --pkcs8 Use PKCS #8 format for private keys --rsa Generate RSA key --dsa Generate DSA key --ecc Generate ECC (ECDSA) key --hash=str Hash algorithm to use for signing. --inder Use DER format for input certificates and private keys. - disabled as --no-inder --inraw This is an alias for 'inder' --outder Use DER format for output certificates and private keys - disabled as --no-outder --outraw This is an alias for 'outder' --bits=num Specify the number of bits for key generate --sec-param=str Specify the security level [low, legacy, normal, high, ultra]. --disable-quick-random No effect --template=file Template file to use for non-interactive operation - file must pre-exist --pkcs-cipher=str Cipher to use for PKCS #8 and #12 operations -v, --version[=arg] Output version information and exit -h, --help Display extended usage information and exit -!, --more-help Extended usage information passed thru pager Options are specified by doubled hyphens and their name or by a single hyphen and the flag character. 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. please send bug reports to: bug-gnutls@@gnu.org @end example @exampleindent 4 @anchor{certtool debug} @subheading debug option (-d) @cindex certtool-debug This is the ``enable debugging.'' option. This option takes an argument number. Specifies the debug level. @anchor{certtool verify-chain} @subheading verify-chain option (-e) @cindex certtool-verify-chain This is the ``verify a pem encoded certificate chain.'' option. The last certificate in the chain must be a self signed one. @anchor{certtool verify} @subheading verify option @cindex certtool-verify This is the ``verify a pem encoded certificate chain using a trusted list.'' option. @noindent This option has some usage constraints. It: @itemize @bullet @item must appear in combination with the following options: load-ca-certificate. @end itemize The trusted certificate list must be loaded with --load-ca-certificate. @anchor{certtool verify-crl} @subheading verify-crl option @cindex certtool-verify-crl This is the ``verify a crl using a trusted list.'' option. @noindent This option has some usage constraints. It: @itemize @bullet @item must appear in combination with the following options: load-ca-certificate. @end itemize The trusted certificate list must be loaded with --load-ca-certificate. @anchor{certtool get-dh-params} @subheading get-dh-params option @cindex certtool-get-dh-params This is the ``get the included pkcs #3 encoded diffie-hellman parameters.'' option. Returns stored DH parameters in GnuTLS. Those parameters are used in the SRP protocol. The parameters returned by fresh generation are more efficient since GnuTLS 3.0.9. @anchor{certtool load-privkey} @subheading load-privkey option @cindex certtool-load-privkey This is the ``loads a private key file'' option. This option takes an argument string. This can be either a file or a PKCS #11 URL @anchor{certtool load-pubkey} @subheading load-pubkey option @cindex certtool-load-pubkey This is the ``loads a public key file'' option. This option takes an argument string. This can be either a file or a PKCS #11 URL @anchor{certtool load-certificate} @subheading load-certificate option @cindex certtool-load-certificate This is the ``loads a certificate file'' option. This option takes an argument string. This can be either a file or a PKCS #11 URL @anchor{certtool load-ca-privkey} @subheading load-ca-privkey option @cindex certtool-load-ca-privkey This is the ``loads the certificate authority's private key file'' option. This option takes an argument string. This can be either a file or a PKCS #11 URL @anchor{certtool load-ca-certificate} @subheading load-ca-certificate option @cindex certtool-load-ca-certificate This is the ``loads the certificate authority's certificate file'' option. This option takes an argument string. This can be either a file or a PKCS #11 URL @anchor{certtool null-password} @subheading null-password option @cindex certtool-null-password This is the ``enforce a null password'' option. This option enforces a NULL password. This may be different than the empty password in some schemas. @anchor{certtool to-p12} @subheading to-p12 option @cindex certtool-to-p12 This is the ``generate a pkcs #12 structure'' option. @noindent This option has some usage constraints. It: @itemize @bullet @item must appear in combination with the following options: load-certificate. @end itemize It requires a certificate, a private key and possibly a CA certificate to be specified. @anchor{certtool hash} @subheading hash option @cindex certtool-hash This is the ``hash algorithm to use for signing.'' option. This option takes an argument string. Available hash functions are SHA1, RMD160, SHA256, SHA384, SHA512. @anchor{certtool inder} @subheading inder option @cindex certtool-inder This is the ``use der format for input certificates and private keys.'' option. The input files will be assumed to be in DER or RAW format. Unlike options that in PEM input would allow multiple input data (e.g. multiple certificates), when reading in DER format a single data structure is read. @anchor{certtool inraw} @subheading inraw option @cindex certtool-inraw This is an alias for the inder option, @pxref{certtool inder, the inder option documentation}. @anchor{certtool outder} @subheading outder option @cindex certtool-outder This is the ``use der format for output certificates and private keys'' option. The output will be in DER or RAW format. @anchor{certtool outraw} @subheading outraw option @cindex certtool-outraw This is an alias for the outder option, @pxref{certtool outder, the outder option documentation}. @anchor{certtool sec-param} @subheading sec-param option @cindex certtool-sec-param This is the ``specify the security level [low, legacy, normal, high, ultra].'' option. This option takes an argument string @file{Security parameter}. This is alternative to the bits option. @anchor{certtool pkcs-cipher} @subheading pkcs-cipher option @cindex certtool-pkcs-cipher This is the ``cipher to use for pkcs #8 and #12 operations'' option. This option takes an argument string @file{Cipher}. Cipher may be one of 3des, 3des-pkcs12, aes-128, aes-192, aes-256, rc2-40, arcfour. @anchor{certtool exit status} @subheading certtool exit status One of the following exit values will be returned: @table @samp @item 0 (EXIT_SUCCESS) Successful program execution. @item 1 (EXIT_FAILURE) The operation failed or the command syntax was not valid. @end table @anchor{certtool See Also} @subheading certtool See Also p11tool (1) @anchor{certtool Examples} @subheading certtool Examples @subheading Generating private keys To create an RSA private key, run: @example $ 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 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. @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 \ --outfile cert.pem --load-ca-certificate ca-cert.pem \ --load-ca-privkey ca-key.pem @end example To generate a certificate using the private key only, 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 @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 $ 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 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 @anchor{certtool Files} @subheading certtool Files @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" # Set domain components #dc = "name" #dc = "domain" # 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" # A subject alternative name URI #uri = "http://www.example.com" # 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 # 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 # for microsoft smart card logon # key_purpose_oid = 1.3.6.1.4.1.311.20.2.2 ### Other predefined key purpose OIDs # 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 of key purpose OIDs # 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 # OCSP URI # ocsp_uri = http://my.ocsp.server/ocsp # CA issuers URI # ca_issuers_uri = http://my.ca.issuer # 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