_gnutls_strdatum_to_buf() will account for NULL input.
[gnutls.git] / src / certtool-args.def
blob07afadc8bd0d696a2ca6c3cda387dff90fe03303
1 AutoGen Definitions options;
2 prog-name = certtool;
3 prog-title = "GnuTLS certificate tool";
4 prog-desc = "Manipulate certificates and private keys.";
5 detail = "Tool to parse and generate X.509 certificates, requests and private keys.
6 It can be used interactively or non interactively by
7 specifying the template command line option.";
8 short-usage = "certtool [options]\ncerttool --help for usage instructions.\n";
9 explain = "";
11 #define INFILE_OPT 1
12 #define OUTFILE_OPT 1
13 #define VERBOSE_OPT 1
14 #include args-std.def
16 flag = {
17 name = generate-self-signed;
18 value = s;
19 descrip = "Generate a self-signed certificate";
20 doc = "";
23 flag = {
24 name = generate-certificate;
25 value = c;
26 descrip = "Generate a signed certificate";
27 doc = "";
30 flag = {
31 name = generate-proxy;
32 descrip = "Generates a proxy certificate";
33 doc = "";
36 flag = {
37 name = generate-crl;
38 descrip = "Generate a CRL";
39 doc = "";
42 flag = {
43 name = update-certificate;
44 value = u;
45 descrip = "Update a signed certificate";
46 doc = "";
49 flag = {
50 name = generate-privkey;
51 value = p;
52 descrip = "Generate a private key";
53 doc = "";
56 flag = {
57 name = generate-request;
58 value = q;
59 descrip = "Generate a PKCS #10 certificate request";
60 doc = "";
63 flag = {
64 name = verify-chain;
65 value = e;
66 descrip = "Verify a PEM encoded certificate chain.";
67 doc = "The last certificate in the chain must be a self signed one.";
70 flag = {
71 name = verify;
72 descrip = "Verify a PEM encoded certificate chain using a trusted list.";
73 doc = "The trusted certificate list must be loaded with --load-ca-certificate.";
74 flags-must = load-ca-certificate;
77 flag = {
78 name = verify-crl;
79 descrip = "Verify a CRL using a trusted list.";
80 doc = "The trusted certificate list must be loaded with --load-ca-certificate.";
81 flags-must = load-ca-certificate;
84 flag = {
85 name = generate-dh-params;
86 descrip = "Generate PKCS #3 encoded Diffie-Hellman parameters.";
87 doc = "";
90 flag = {
91 name = get-dh-params;
92 descrip = "Get the included PKCS #3 encoded Diffie-Hellman parameters.";
93 doc = "Returns stored DH parameters in GnuTLS. Those parameters are used in the SRP protocol. The parameters returned by fresh generation
94 are more efficient since GnuTLS 3.0.9.";
97 flag = {
98 name = dh-info;
99 descrip = "Print information PKCS #3 encoded Diffie-Hellman parameters";
100 doc = "";
103 flag = {
104 name = load-privkey;
105 descrip = "Loads a private key file";
106 arg-type = string;
107 doc = "This can be either a file or a PKCS #11 URL";
110 flag = {
111 name = load-pubkey;
112 descrip = "Loads a public key file";
113 arg-type = string;
114 doc = "This can be either a file or a PKCS #11 URL";
117 flag = {
118 name = load-request;
119 descrip = "Loads a certificate request file";
120 arg-type = file;
121 file-exists = yes;
122 doc = "";
125 flag = {
126 name = load-certificate;
127 descrip = "Loads a certificate file";
128 arg-type = string;
129 doc = "This can be either a file or a PKCS #11 URL";
132 flag = {
133 name = load-ca-privkey;
134 descrip = "Loads the certificate authority's private key file";
135 arg-type = string;
136 doc = "This can be either a file or a PKCS #11 URL";
139 flag = {
140 name = load-ca-certificate;
141 descrip = "Loads the certificate authority's certificate file";
142 arg-type = string;
143 doc = "This can be either a file or a PKCS #11 URL";
146 flag = {
147 name = password;
148 arg-type = string;
149 descrip = "Password to use";
150 doc = "";
153 flag = {
154 name = hex-numbers;
155 descrip = "Print big number in an easier format to parse";
156 doc = "";
159 flag = {
160 name = null-password;
161 descrip = "Enforce a NULL password";
162 doc = "This option enforces a NULL password. This may be different than the empty password in some schemas.";
165 flag = {
166 name = certificate-info;
167 value = i;
168 descrip = "Print information on the given certificate";
169 doc = "";
172 flag = {
173 name = certificate-pubkey;
174 descrip = "Print certificate's public key";
175 doc = "";
178 flag = {
179 name = pgp-certificate-info;
180 descrip = "Print information on the given OpenPGP certificate";
181 doc = "";
184 flag = {
185 name = pgp-ring-info;
186 descrip = "Print information on the given OpenPGP keyring structure";
187 doc = "";
190 flag = {
191 name = crl-info;
192 value = l;
193 descrip = "Print information on the given CRL structure";
194 doc = "";
197 flag = {
198 name = crq-info;
199 descrip = "Print information on the given certificate request";
200 doc = "";
204 flag = {
205 name = no-crq-extensions;
206 descrip = "Do not use extensions in certificate requests";
207 doc = "";
210 flag = {
211 name = p12-info;
212 descrip = "Print information on a PKCS #12 structure";
213 doc = "";
216 flag = {
217 name = p7-info;
218 descrip = "Print information on a PKCS #7 structure";
219 doc = "";
222 flag = {
223 name = smime-to-p7;
224 descrip = "Convert S/MIME to PKCS #7 structure";
225 doc = "";
228 flag = {
229 name = key-info;
230 value = k;
231 descrip = "Print information on a private key";
232 doc = "";
235 flag = {
236 name = pgp-key-info;
237 descrip = "Print information on an OpenPGP private key";
238 doc = "";
241 flag = {
242 name = pubkey-info;
243 descrip = "Print information on a public key";
244 doc = "The option combined with --load-request, --load-pubkey, --load-privkey and --load-certificate will extract the public key of the object in question.";
247 flag = {
248 name = v1;
249 descrip = "Generate an X.509 version 1 certificate (with no extensions)";
250 doc = "";
253 flag = {
254 name = to-p12;
255 descrip = "Generate a PKCS #12 structure";
256 doc = "It requires a certificate, a private key and possibly a CA certificate to be specified.";
257 flags-must = load-certificate;
260 flag = {
261 name = to-p8;
262 descrip = "Generate a PKCS #8 structure";
263 doc = "";
266 flag = {
267 name = pkcs8;
268 value = 8;
269 descrip = "Use PKCS #8 format for private keys";
270 doc = "";
273 flag = {
274 name = rsa;
275 descrip = "Generate RSA key";
276 doc = "When combined with --generate-privkey generates an RSA private key.";
279 flag = {
280 name = dsa;
281 descrip = "Generate DSA key";
282 doc = "When combined with --generate-privkey generates a DSA private key.";
285 flag = {
286 name = ecc;
287 descrip = "Generate ECC (ECDSA) key";
288 doc = "When combined with --generate-privkey generates an elliptic curve private key to be used with ECDSA.";
291 flag = {
292 name = ecdsa;
293 aliases = ecc;
296 flag = {
297 name = hash;
298 arg-type = string;
299 descrip = "Hash algorithm to use for signing.";
300 doc = "Available hash functions are SHA1, RMD160, SHA256, SHA384, SHA512.";
303 flag = {
304 name = inder;
305 descrip = "Use DER format for input certificates and private keys.";
306 disabled;
307 disable = "no";
308 doc = "The input files will be assumed to be in DER or RAW format.
309 Unlike options that in PEM input would allow multiple input data (e.g. multiple
310 certificates), when reading in DER format a single data structure is read.";
313 flag = {
314 name = inraw;
315 aliases = inder;
318 flag = {
319 name = outder;
320 descrip = "Use DER format for output certificates and private keys";
321 disabled;
322 disable = "no";
323 doc = "The output will be in DER or RAW format.";
326 flag = {
327 name = outraw;
328 aliases = outder;
331 flag = {
332 name = bits;
333 arg-type = number;
334 descrip = "Specify the number of bits for key generate";
335 doc = "";
338 flag = {
339 name = sec-param;
340 arg-type = string;
341 arg-name = "Security parameter";
342 descrip = "Specify the security level [low, legacy, normal, high, ultra].";
343 doc = "This is alternative to the bits option.";
346 flag = {
347 name = disable-quick-random;
348 descrip = "No effect";
349 doc = "";
352 flag = {
353 name = template;
354 arg-type = file;
355 file-exists = yes;
356 descrip = "Template file to use for non-interactive operation";
357 doc = "";
360 flag = {
361 name = pkcs-cipher;
362 arg-type = string;
363 arg-name = "Cipher";
364 descrip = "Cipher to use for PKCS #8 and #12 operations";
365 doc = "Cipher may be one of 3des, 3des-pkcs12, aes-128, aes-192, aes-256, rc2-40, arcfour.";
368 doc-section = {
369 ds-type = 'SEE ALSO';
370 ds-format = 'texi';
371 ds-text = <<-_EOT_
372 p11tool (1)
373 _EOT_;
376 doc-section = {
377 ds-type = 'EXAMPLES';
378 ds-format = 'texi';
379 ds-text = <<-_EOT_
380 @subheading Generating private keys
381 To create an RSA private key, run:
382 @example
383 $ certtool --generate-privkey --outfile key.pem --rsa
384 @end example
386 To create a DSA or elliptic curves (ECDSA) private key use the
387 above command combined with 'dsa' or 'ecc' options.
389 @subheading Generating certificate requests
390 To create a certificate request (needed when the certificate is issued by
391 another party), run:
392 @example
393 certtool --generate-request --load-privkey key.pem \
394 --outfile request.pem
395 @end example
397 If the private key is stored in a smart card you can generate
398 a request by specifying the private key object URL.
399 @example
400 $ ./certtool --generate-request --load-privkey "pkcs11:..." \
401 --load-pubkey "pkcs11:..." --outfile request.pem
402 @end example
405 @subheading Generating a self-signed certificate
406 To create a self signed certificate, use the command:
407 @example
408 $ certtool --generate-privkey --outfile ca-key.pem
409 $ certtool --generate-self-signed --load-privkey ca-key.pem \
410 --outfile ca-cert.pem
411 @end example
413 Note that a self-signed certificate usually belongs to a certificate
414 authority, that signs other certificates.
416 @subheading Generating a certificate
417 To generate a certificate using the previous request, use the command:
418 @example
419 $ certtool --generate-certificate --load-request request.pem \
420 --outfile cert.pem --load-ca-certificate ca-cert.pem \
421 --load-ca-privkey ca-key.pem
422 @end example
424 To generate a certificate using the private key only, use the command:
425 @example
426 $ certtool --generate-certificate --load-privkey key.pem \
427 --outfile cert.pem --load-ca-certificate ca-cert.pem \
428 --load-ca-privkey ca-key.pem
429 @end example
431 @subheading Certificate information
432 To view the certificate information, use:
433 @example
434 $ certtool --certificate-info --infile cert.pem
435 @end example
437 @subheading PKCS #12 structure generation
438 To generate a PKCS #12 structure using the previous key and certificate,
439 use the command:
440 @example
441 $ certtool --load-certificate cert.pem --load-privkey key.pem \
442 --to-p12 --outder --outfile key.p12
443 @end example
445 Some tools (reportedly web browsers) have problems with that file
446 because it does not contain the CA certificate for the certificate.
447 To work around that problem in the tool, you can use the
448 --load-ca-certificate parameter as follows:
450 @example
451 $ certtool --load-ca-certificate ca.pem \
452 --load-certificate cert.pem --load-privkey key.pem \
453 --to-p12 --outder --outfile key.p12
454 @end example
456 @subheading Diffie-Hellman parameter generation
457 To generate parameters for Diffie-Hellman key exchange, use the command:
458 @example
459 $ certtool --generate-dh-params --outfile dh.pem --sec-param normal
460 @end example
462 @subheading Proxy certificate generation
463 Proxy certificate can be used to delegate your credential to a
464 temporary, typically short-lived, certificate. To create one from the
465 previously created certificate, first create a temporary key and then
466 generate a proxy certificate for it, using the commands:
468 @example
469 $ certtool --generate-privkey > proxy-key.pem
470 $ certtool --generate-proxy --load-ca-privkey key.pem \
471 --load-privkey proxy-key.pem --load-certificate cert.pem \
472 --outfile proxy-cert.pem
473 @end example
475 @subheading Certificate revocation list generation
476 To create an empty Certificate Revocation List (CRL) do:
478 @example
479 $ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
480 --load-ca-certificate x509-ca.pem
481 @end example
483 To create a CRL that contains some revoked certificates, place the
484 certificates in a file and use @code{--load-certificate} as follows:
486 @example
487 $ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
488 --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem
489 @end example
491 To verify a Certificate Revocation List (CRL) do:
493 @example
494 $ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem
495 @end example
496 _EOT_;
500 doc-section = {
501 ds-type = 'FILES';
502 ds-format = 'texi';
503 ds-text = <<-_EOT_
504 @subheading Certtool's template file format
505 A template file can be used to avoid the interactive questions of
506 certtool. Initially create a file named 'cert.cfg' that contains the information
507 about the certificate. The template can be used as below:
509 @example
510 $ certtool --generate-certificate cert.pem --load-privkey key.pem \
511 --template cert.cfg \
512 --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem
513 @end example
515 An example certtool template file that can be used to generate a certificate
516 request or a self signed certificate follows.
518 @example
519 # X.509 Certificate options
521 # DN options
523 # The organization of the subject.
524 organization = "Koko inc."
526 # The organizational unit of the subject.
527 unit = "sleeping dept."
529 # The locality of the subject.
530 # locality =
532 # The state of the certificate owner.
533 state = "Attiki"
535 # The country of the subject. Two letter code.
536 country = GR
538 # The common name of the certificate owner.
539 cn = "Cindy Lauper"
541 # A user id of the certificate owner.
542 #uid = "clauper"
544 # Set domain components
545 #dc = "name"
546 #dc = "domain"
548 # If the supported DN OIDs are not adequate you can set
549 # any OID here.
550 # For example set the X.520 Title and the X.520 Pseudonym
551 # by using OID and string pairs.
552 #dn_oid = 2.5.4.12 Dr.
553 #dn_oid = 2.5.4.65 jackal
555 # This is deprecated and should not be used in new
556 # certificates.
557 # pkcs9_email = "none@@none.org"
559 # The serial number of the certificate
560 serial = 007
562 # In how many days, counting from today, this certificate will expire.
563 expiration_days = 700
565 # X.509 v3 extensions
567 # A dnsname in case of a WWW server.
568 #dns_name = "www.none.org"
569 #dns_name = "www.morethanone.org"
571 # A subject alternative name URI
572 #uri = "http://www.example.com"
574 # An IP address in case of a server.
575 #ip_address = "192.168.1.1"
577 # An email in case of a person
578 email = "none@@none.org"
580 # Challenge password used in certificate requests
581 challenge_passwd = 123456
583 # An URL that has CRLs (certificate revocation lists)
584 # available. Needed in CA certificates.
585 #crl_dist_points = "http://www.getcrl.crl/getcrl/"
587 # Whether this is a CA certificate or not
590 # for microsoft smart card logon
591 # key_purpose_oid = 1.3.6.1.4.1.311.20.2.2
593 ### Other predefined key purpose OIDs
595 # Whether this certificate will be used for a TLS client
596 #tls_www_client
598 # Whether this certificate will be used for a TLS server
599 #tls_www_server
601 # Whether this certificate will be used to sign data (needed
602 # in TLS DHE ciphersuites).
603 signing_key
605 # Whether this certificate will be used to encrypt data (needed
606 # in TLS RSA ciphersuites). Note that it is preferred to use different
607 # keys for encryption and signing.
608 #encryption_key
610 # Whether this key will be used to sign other certificates.
611 #cert_signing_key
613 # Whether this key will be used to sign CRLs.
614 #crl_signing_key
616 # Whether this key will be used to sign code.
617 #code_signing_key
619 # Whether this key will be used to sign OCSP data.
620 #ocsp_signing_key
622 # Whether this key will be used for time stamping.
623 #time_stamping_key
625 # Whether this key will be used for IPsec IKE operations.
626 #ipsec_ike_key
628 ### end of key purpose OIDs
630 # When generating a certificate from a certificate
631 # request, then honor the extensions stored in the request
632 # and store them in the real certificate.
633 #honor_crq_extensions
635 # Path length contraint. Sets the maximum number of
636 # certificates that can be used to certify this certificate.
637 # (i.e. the certificate chain length)
638 #path_len = -1
639 #path_len = 2
641 # OCSP URI
642 # ocsp_uri = http://my.ocsp.server/ocsp
644 # CA issuers URI
645 # ca_issuers_uri = http://my.ca.issuer
647 # Certificate policies
648 # policy1 = 1.3.6.1.4.1.5484.1.10.99.1.0
649 # policy1_txt = "This is a long policy to summarize"
650 # policy1_url = http://www.example.com/a-policy-to-read
652 # policy2 = 1.3.6.1.4.1.5484.1.10.99.1.1
653 # policy2_txt = "This is a short policy"
654 # policy2_url = http://www.example.com/another-policy-to-read
657 # Options for proxy certificates
658 # proxy_policy_language = 1.3.6.1.5.5.7.21.1
661 # Options for generating a CRL
663 # next CRL update will be in 43 days (wow)
664 #crl_next_update = 43
666 # this is the 5th CRL by this CA
667 #crl_number = 5
669 @end example
671 _EOT_;