certtool: group together common options

Signed-off-by: Nikos Mavrogiannopoulos <nmav@redhat.com>

1 files changed, 279 insertions, 202 deletions

diff --git a/src/certtool-args.def b/src/certtool-args.def
index f83738ef20..2d045d1123 100644
--- a/src/certtool-args.def
+++ b/src/certtool-args.def
@@ -18,6 +18,27 @@ explain       = "";
 #define  VERBOSE_OPT 1
 #include args-std.def
 
+//----------------------------------------
+flag = {
+    name = cert_options;
+    documentation;
+    descrip = "Certificate related options";
+};
+//----------------------------------------
+
+flag = {
+    name      = certificate-info;
+    value     = i;
+    descrip   = "Print information on the given certificate";
+    doc       = "";
+};
+
+flag = {
+    name      = pubkey-info;
+    descrip   = "Print information on a public key";
+    doc = "The option combined with --load-request, --load-pubkey, --load-privkey and --load-certificate will extract the public key of the object in question.";
+};
+
 flag = {
     name      = generate-self-signed;
     value     = s;
@@ -39,12 +60,6 @@ flag = {
 };
 
 flag = {
-    name      = generate-crl;
-    descrip   = "Generate a CRL";
-    doc = "This option generates a Certificate Revocation List. When combined with --load-crl it would use the loaded CRL as base for the generated (i.e., all revoked certificates in the base will be copied to the new CRL).";
-};
-
-flag = {
     name      = update-certificate;
     value     = u;
     descrip   = "Update a signed certificate";
@@ -52,32 +67,54 @@ flag = {
 };
 
 flag = {
-    name      = generate-privkey;
-    value     = p;
-    descrip   = "Generate a private key";
-    doc = "";
+    name      = fingerprint;
+    descrip   = "Print the fingerprint of the given certificate";
+    doc       = "This is a simple hash of the DER encoding of the certificate. It can be combined with the --hash parameter. However, it is recommended for identification to use the key-id which depends only on the certificate's key.";
 };
 
 flag = {
-    name      = provable;
-    descrip   = "Generate a private key or parameters from a seed using a provable method";
-    doc = "This will use the FIPS-186-4 algorithms (i.e., Shawe-Taylor) for provable key generation. When specified the private keys or parameters will be generated from a seed, and can be proven to be correctly generated from the seed. You may specify --seed or allow GnuTLS to generate one (recommended). This option can be combined with --generate-privkey or --generate-dh-params.";
+    name      = key-id;
+    descrip   = "Print the key ID of the given certificate";
+    doc       = "This is a hash of the public key of the given certificate. It identifies the key uniquely, remains the same on a certificate renewal and depends only on signed fields of the certificate.";
 };
 
 flag = {
-    name      = verify-provable-privkey;
-    descrip   = "Verify a private key generated from a seed using a provable method";
-    doc = "This will use the FIPS-186-4 algorithms for provable key generation. You may specify --seed or use the seed stored in the private key structure.";
+    name      = certificate-pubkey;
+    descrip   = "Print certificate's public key";
+    doc       = "";
 };
 
 flag = {
-    name      = seed;
-    descrip   = "When generating a private key use the given hex-encoded seed";
-    arg-type  = string;
+    name      = v1;
+    descrip   = "Generate an X.509 version 1 certificate (with no extensions)";
     doc = "";
 };
 
 flag = {
+    name      = sign-params;
+    arg-type  = string;
+    descrip   = "Sign a certificate with a specific signature algorithm";
+    doc = "This option can be combined with --generate-certificate, to sign the certificate with
+a specific signature algorithm variant. The only option supported is
+'RSA-PSS', and should be specified when the signer does not have a certificate which is marked for RSA-PSS use only.";
+};
+
+
+//----------------------------------------
+flag = {
+    name = crq_options;
+    documentation;
+    descrip = "Certificate request related options";
+};
+//----------------------------------------
+
+flag = {
+    name      = crq-info;
+    descrip   = "Print information on the given certificate request";
+    doc       = "";
+};
+
+flag = {
     name      = generate-request;
     value     = q;
     descrip   = "Generate a PKCS #10 certificate request";
@@ -86,227 +123,214 @@ flag = {
 };
 
 flag = {
-    name      = verify-chain;
-    value     = e;
-    descrip   = "Verify a PEM encoded certificate chain";
-    doc = "Verifies the validity of a certificate chain. That is, an ordered set of
-    certificates where each one is the issuer of the previous, and the first is
-    the end-certificate to be validated. In a proper chain the last certificate
-    is a self signed one. It can be combined with --verify-purpose or --verify-hostname.";
+    name      = no-crq-extensions;
+    descrip   = "Do not use extensions in certificate requests";
+    doc       = "";
 };
 
+//----------------------------------------
 flag = {
-    name      = verify;
-    descrip   = "Verify a PEM encoded certificate (chain) against a trusted set";
-    doc = "The trusted certificate list can be loaded with --load-ca-certificate. If no
-certificate list is provided, then the system's trusted certificate list is used. Note that
-during verification multiple paths may be explored. On a successful verification
-the successful path will be the last one. It can be combined with --verify-purpose or --verify-hostname.";
+    name = pkcs12_options;
+    documentation;
+    descrip = "PKCS#12 file related options";
 };
+//----------------------------------------
 
 flag = {
-    name      = verify-crl;
-    descrip   = "Verify a Certificate Revocation List using a trusted list";
-    doc = "The trusted certificate list must be loaded with --load-ca-certificate.";
-    flags-must = load-ca-certificate;
+    name      = p12-info;
+    descrip   = "Print information on a PKCS #12 structure";
+    doc       = "This option will dump the contents and print the metadata of the provided PKCS #12 structure.";
 };
 
 flag = {
-    name      = verify-hostname;
-    descrip   = "Specify a hostname to be used for certificate chain verification";
+    name      = p12-name;
     arg-type  = string;
-    doc = "This is to be combined with one of the verify certificate options.";
+    descrip   = "The PKCS #12 friendly name to use";
+    doc = "The name to be used for the primary certificate and private key in a PKCS #12 file.";
 };
 
 flag = {
-    name      = verify-email;
-    descrip   = "Specify a email to be used for certificate chain verification";
-    arg-type  = string;
-    doc = "This is to be combined with one of the verify certificate options.";
-    flags-cant = verify-hostname;
+    name      = to-p12;
+    descrip   = "Generate a PKCS #12 structure";
+    doc = "It requires a certificate, a private key and possibly a CA certificate to be specified.";
 };
 
-flag = {
-    name      = verify-purpose;
-    descrip   = "Specify a purpose OID to be used for certificate chain verification";
-    arg-type  = string;
-    doc = "This object identifier restricts the purpose of the certificates to be verified. Example purposes are 1.3.6.1.5.5.7.3.1 (TLS WWW), 1.3.6.1.5.5.7.3.4 (EMAIL) etc. Note that a CA certificate without a purpose set (extended key usage) is valid for any purpose.";
-};
 
+//----------------------------------------
 flag = {
-    name      = verify-allow-broken;
-    descrip   = "Allow broken algorithms, such as MD5 for verification";
-    doc = "This can be combined with --p7-verify, --verify or --verify-chain.";
+    name = key_options;
+    documentation;
+    descrip = "Private key related options";
 };
+//----------------------------------------
 
 flag = {
-    name      = generate-dh-params;
-    descrip   = "Generate PKCS #3 encoded Diffie-Hellman parameters";
-    doc = "The will generate random parameters to be used with
-Diffie-Hellman key exchange. The output parameters will be in PKCS #3
-format. Note that it is recommended to use the --get-dh-params option
-instead.";
+    name      = key-info;
+    value     = k;
+    descrip   = "Print information on a private key";
+    doc = "";
 };
 
 flag = {
-    name      = get-dh-params;
-    descrip   = "Get the included PKCS #3 encoded Diffie-Hellman parameters";
-    doc = "Returns stored DH parameters in GnuTLS. Those parameters returned
-are defined in RFC7919, and can be considered standard parameters for a TLS
-key exchange.";
+    name      = p8-info;
+    descrip   = "Print information on a PKCS #8 structure";
+    doc       = "This option will print information about encrypted PKCS #8 structures. That option does not require the decryption of the structure.";
 };
 
 flag = {
-    name      = dh-info;
-    descrip   = "Print information PKCS #3 encoded Diffie-Hellman parameters";
+    name      = generate-privkey;
+    value     = p;
+    descrip   = "Generate a private key";
     doc = "";
 };
 
 flag = {
-    name      = load-privkey;
-    descrip   = "Loads a private key file";
-    arg-type  = string;
-    doc = "This can be either a file or a PKCS #11 URL";
+    name      = bits;
+    arg-type  = number;
+    descrip   = "Specify the number of bits for key generation";
+    doc      = "";
 };
 
 flag = {
-    name      = load-pubkey;
-    descrip   = "Loads a public key file";
+    name      = curve;
     arg-type  = string;
-    doc = "This can be either a file or a PKCS #11 URL";
+    descrip   = "Specify the curve used for EC key generation";
+    doc      = "Supported values are secp192r1, secp224r1, secp256r1, secp384r1 and secp521r1.";
 };
 
 flag = {
-    name      = load-request;
-    descrip   = "Loads a certificate request file";
+    name      = sec-param;
     arg-type  = string;
-    doc = "This option can be used with a file";
+    arg-name  = "Security parameter";
+    descrip   = "Specify the security level [low, legacy, medium, high, ultra]";
+    doc      = "This is alternative to the bits option.";
 };
 
 flag = {
-    name      = load-certificate;
-    descrip   = "Loads a certificate file";
-    arg-type  = string;
-    doc = "This option can be used with a file";
+    name      = to-p8;
+    descrip   = "Convert a given key to a PKCS #8 structure";
+    doc = "This needs to be combined with --load-privkey.";
 };
 
 flag = {
-    name      = load-ca-privkey;
-    descrip   = "Loads the certificate authority's private key file";
-    arg-type  = string;
-    doc = "This can be either a file or a PKCS #11 URL";
+    name      = pkcs8;
+    value     = 8;
+    descrip   = "Use PKCS #8 format for private keys";
+    doc = "";
 };
 
 flag = {
-    name      = load-ca-certificate;
-    descrip   = "Loads the certificate authority's certificate file";
-    arg-type  = string;
-    doc = "This can be either a file or a PKCS #11 URL";
+    name      = provable;
+    descrip   = "Generate a private key or parameters from a seed using a provable method";
+    doc = "This will use the FIPS-186-4 algorithms (i.e., Shawe-Taylor) for provable key generation. When specified the private keys or parameters will be generated from a seed, and can be proven to be correctly generated from the seed. You may specify --seed or allow GnuTLS to generate one (recommended). This option can be combined with --generate-privkey or --generate-dh-params.";
 };
 
 flag = {
-    name      = load-crl;
-    descrip   = "Loads the provided CRL";
-    arg-type  = string;
-    doc = "This option can be used with a file";
+    name      = verify-provable-privkey;
+    descrip   = "Verify a private key generated from a seed using a provable method";
+    doc = "This will use the FIPS-186-4 algorithms for provable key generation. You may specify --seed or use the seed stored in the private key structure.";
 };
 
 flag = {
-    name      = load-data;
-    descrip   = "Loads auxiliary data";
+    name      = seed;
+    descrip   = "When generating a private key use the given hex-encoded seed";
     arg-type  = string;
-    doc = "This option can be used with a file";
+    doc = "";
 };
 
-flag = {
-    name      = password;
-    arg-type  = string;
-    descrip   = "Password to use";
-    doc   = "You can use this option to specify the password in the command line instead of reading it from the tty. Note, that the command line arguments are available for view in others in the system. Specifying password as '' is the same as specifying no password.";
-};
 
+//----------------------------------------
 flag = {
-    name      = null-password;
-    descrip   = "Enforce a NULL password";
-    doc   = "This option enforces a NULL password. This is different than the empty or no password in schemas like PKCS #8.";
+    name = crl_options;
+    documentation;
+    descrip = "CRL related options";
 };
+//----------------------------------------
 
 flag = {
-    name      = empty-password;
-    descrip   = "Enforce an empty password";
-    doc   = "This option enforces an empty password. This is different than the NULL or no password in schemas like PKCS #8.";
+    name      = crl-info;
+    value     = l;
+    descrip   = "Print information on the given CRL structure";
+    doc       = "";
 };
 
 
 flag = {
-    name      = hex-numbers;
-    descrip   = "Print big number in an easier format to parse";
-    doc   = "";
+    name      = generate-crl;
+    descrip   = "Generate a CRL";
+    doc = "This option generates a Certificate Revocation List. When combined with --load-crl it would use the loaded CRL as base for the generated (i.e., all revoked certificates in the base will be copied to the new CRL).";
 };
 
-flag = {
-    name      = cprint;
-    descrip   = "In certain operations it prints the information in C-friendly format";
-    doc   = "In certain operations it prints the information in C-friendly format, suitable for including into C programs.";
-};
 
 flag = {
-    name      = certificate-info;
-    value     = i;
-    descrip   = "Print information on the given certificate";
-    doc       = "";
+    name      = verify-crl;
+    descrip   = "Verify a Certificate Revocation List using a trusted list";
+    doc = "The trusted certificate list must be loaded with --load-ca-certificate.";
+    flags-must = load-ca-certificate;
 };
 
+//----------------------------------------
 flag = {
-    name      = fingerprint;
-    descrip   = "Print the fingerprint of the given certificate";
-    doc       = "This is a simple hash of the DER encoding of the certificate. It can be combined with the --hash parameter. However, it is recommended for identification to use the key-id which depends only on the certificate's key.";
+    name = cert_verify_options;
+    documentation;
+    descrip = "Certificate verification related options";
 };
+//----------------------------------------
 
 flag = {
-    name      = key-id;
-    descrip   = "Print the key ID of the given certificate";
-    doc       = "This is a hash of the public key of the given certificate. It identifies the key uniquely, remains the same on a certificate renewal and depends only on signed fields of the certificate.";
+    name      = verify-chain;
+    value     = e;
+    descrip   = "Verify a PEM encoded certificate chain";
+    doc = "Verifies the validity of a certificate chain. That is, an ordered set of
+    certificates where each one is the issuer of the previous, and the first is
+    the end-certificate to be validated. In a proper chain the last certificate
+    is a self signed one. It can be combined with --verify-purpose or --verify-hostname.";
 };
 
 flag = {
-    name      = certificate-pubkey;
-    descrip   = "Print certificate's public key";
-    doc       = "";
+    name      = verify;
+    descrip   = "Verify a PEM encoded certificate (chain) against a trusted set";
+    doc = "The trusted certificate list can be loaded with --load-ca-certificate. If no
+certificate list is provided, then the system's trusted certificate list is used. Note that
+during verification multiple paths may be explored. On a successful verification
+the successful path will be the last one. It can be combined with --verify-purpose or --verify-hostname.";
 };
 
 flag = {
-    name      = crl-info;
-    value     = l;
-    descrip   = "Print information on the given CRL structure";
-    doc       = "";
+    name      = verify-hostname;
+    descrip   = "Specify a hostname to be used for certificate chain verification";
+    arg-type  = string;
+    doc = "This is to be combined with one of the verify certificate options.";
 };
 
 flag = {
-    name      = crq-info;
-    descrip   = "Print information on the given certificate request";
-    doc       = "";
+    name      = verify-email;
+    descrip   = "Specify a email to be used for certificate chain verification";
+    arg-type  = string;
+    doc = "This is to be combined with one of the verify certificate options.";
+    flags-cant = verify-hostname;
 };
 
-
 flag = {
-    name      = no-crq-extensions;
-    descrip   = "Do not use extensions in certificate requests";
-    doc       = "";
+    name      = verify-purpose;
+    descrip   = "Specify a purpose OID to be used for certificate chain verification";
+    arg-type  = string;
+    doc = "This object identifier restricts the purpose of the certificates to be verified. Example purposes are 1.3.6.1.5.5.7.3.1 (TLS WWW), 1.3.6.1.5.5.7.3.4 (EMAIL) etc. Note that a CA certificate without a purpose set (extended key usage) is valid for any purpose.";
 };
 
 flag = {
-    name      = p12-info;
-    descrip   = "Print information on a PKCS #12 structure";
-    doc       = "This option will dump the contents and print the metadata of the provided PKCS #12 structure.";
+    name      = verify-allow-broken;
+    descrip   = "Allow broken algorithms, such as MD5 for verification";
+    doc = "This can be combined with --p7-verify, --verify or --verify-chain.";
 };
 
+//----------------------------------------
 flag = {
-    name      = p12-name;
-    arg-type  = string;
-    descrip   = "The PKCS #12 friendly name to use";
-    doc = "The name to be used for the primary certificate and private key in a PKCS #12 file.";
+    name = pkcs7_options;
+    documentation;
+    descrip = "PKCS#7 structure options";
 };
+//----------------------------------------
 
 flag = {
     name      = p7-generate;
@@ -364,53 +388,133 @@ flag = {
 };
 
 flag = {
-    name      = p8-info;
-    descrip   = "Print information on a PKCS #8 structure";
-    doc       = "This option will print information about encrypted PKCS #8 structures. That option does not require the decryption of the structure.";
-};
-
-flag = {
     name      = smime-to-p7;
     descrip   = "Convert S/MIME to PKCS #7 structure";
     doc       = "";
 };
 
+
+
+//----------------------------------------
 flag = {
-    name      = key-info;
-    value     = k;
-    descrip   = "Print information on a private key";
-    doc = "";
+    name = other_options;
+    documentation;
+    descrip = "Other options";
 };
+//----------------------------------------
 
 flag = {
-    name      = pubkey-info;
-    descrip   = "Print information on a public key";
-    doc = "The option combined with --load-request, --load-pubkey, --load-privkey and --load-certificate will extract the public key of the object in question.";
+    name      = generate-dh-params;
+    descrip   = "Generate PKCS #3 encoded Diffie-Hellman parameters";
+    doc = "The will generate random parameters to be used with
+Diffie-Hellman key exchange. The output parameters will be in PKCS #3
+format. Note that it is recommended to use the --get-dh-params option
+instead.";
+    deprecated;
 };
 
 flag = {
-    name      = v1;
-    descrip   = "Generate an X.509 version 1 certificate (with no extensions)";
+    name      = get-dh-params;
+    descrip   = "List the included PKCS #3 encoded Diffie-Hellman parameters";
+    doc = "Returns stored DH parameters in GnuTLS. Those parameters returned
+are defined in RFC7919, and can be considered standard parameters for a TLS
+key exchange. This option is provided for old applications which require
+DH parameters to be specified; modern GnuTLS applications should not require
+them.";
+};
+
+flag = {
+    name      = dh-info;
+    descrip   = "Print information PKCS #3 encoded Diffie-Hellman parameters";
     doc = "";
 };
 
 flag = {
-    name      = to-p12;
-    descrip   = "Generate a PKCS #12 structure";
-    doc = "It requires a certificate, a private key and possibly a CA certificate to be specified.";
+    name      = load-privkey;
+    descrip   = "Loads a private key file";
+    arg-type  = string;
+    doc = "This can be either a file or a PKCS #11 URL";
 };
 
 flag = {
-    name      = to-p8;
-    descrip   = "Generate a PKCS #8 structure";
-    doc = "";
+    name      = load-pubkey;
+    descrip   = "Loads a public key file";
+    arg-type  = string;
+    doc = "This can be either a file or a PKCS #11 URL";
 };
 
 flag = {
-    name      = pkcs8;
-    value     = 8;
-    descrip   = "Use PKCS #8 format for private keys";
-    doc = "";
+    name      = load-request;
+    descrip   = "Loads a certificate request file";
+    arg-type  = string;
+    doc = "This option can be used with a file";
+};
+
+flag = {
+    name      = load-certificate;
+    descrip   = "Loads a certificate file";
+    arg-type  = string;
+    doc = "This option can be used with a file";
+};
+
+flag = {
+    name      = load-ca-privkey;
+    descrip   = "Loads the certificate authority's private key file";
+    arg-type  = string;
+    doc = "This can be either a file or a PKCS #11 URL";
+};
+
+flag = {
+    name      = load-ca-certificate;
+    descrip   = "Loads the certificate authority's certificate file";
+    arg-type  = string;
+    doc = "This can be either a file or a PKCS #11 URL";
+};
+
+flag = {
+    name      = load-crl;
+    descrip   = "Loads the provided CRL";
+    arg-type  = string;
+    doc = "This option can be used with a file";
+};
+
+flag = {
+    name      = load-data;
+    descrip   = "Loads auxiliary data";
+    arg-type  = string;
+    doc = "This option can be used with a file";
+};
+
+flag = {
+    name      = password;
+    arg-type  = string;
+    descrip   = "Password to use";
+    doc   = "You can use this option to specify the password in the command line instead of reading it from the tty. Note, that the command line arguments are available for view in others in the system. Specifying password as '' is the same as specifying no password.";
+};
+
+flag = {
+    name      = null-password;
+    descrip   = "Enforce a NULL password";
+    doc   = "This option enforces a NULL password. This is different than the empty or no password in schemas like PKCS #8.";
+};
+
+flag = {
+    name      = empty-password;
+    descrip   = "Enforce an empty password";
+    doc   = "This option enforces an empty password. This is different than the NULL or no password in schemas like PKCS #8.";
+};
+
+
+flag = {
+    name      = hex-numbers;
+    descrip   = "Print big number in an easier format to parse";
+    doc   = "";
+};
+
+flag = {
+    name      = cprint;
+    descrip   = "In certain operations it prints the information in C-friendly format";
+    doc   = "In certain operations it prints the information in C-friendly format, suitable for including into C programs.";
 };
 
 flag = {
@@ -418,6 +522,7 @@ flag = {
     descrip   = "Generate RSA key";
     doc = "When combined with --generate-privkey generates an RSA private key.";
     description = "This option is equivalent to '--key-type rsa'.";
+    deprecated;
 };
 
 flag = {
@@ -425,6 +530,7 @@ flag = {
     descrip   = "Generate DSA key";
     doc = "When combined with --generate-privkey generates a DSA private key.";
     description = "This option is equivalent to '--key-type dsa'.";
+    deprecated;
 };
 
 flag = {
@@ -432,11 +538,13 @@ flag = {
     descrip   = "Generate ECC (ECDSA) key";
     doc = "When combined with --generate-privkey generates an elliptic curve private key to be used with ECDSA.";
     description = "This option is equivalent to '--key-type ecdsa'.";
+    deprecated;
 };
 
 flag = {
     name      = ecdsa;
     aliases   = ecc;
+    deprecated;
 };
 
 flag = {
@@ -449,15 +557,6 @@ flag = {
 };
 
 flag = {
-    name      = sign-params;
-    arg-type  = string;
-    descrip   = "Sign a certificate with a specific signature algorithm";
-    doc = "This option can be combined with --generate-certificate, to sign the certificate with
-a specific signature algorithm variant. The only option supported is
-'RSA-PSS', and should be specified when the signer does not have a certificate which is marked for RSA-PSS use only.";
-};
-
-flag = {
     name      = hash;
     arg-type  = string;
     descrip   = "Hash algorithm to use for signing";
@@ -493,28 +592,6 @@ flag = {
 };
 
 flag = {
-    name      = bits;
-    arg-type  = number;
-    descrip   = "Specify the number of bits for key generate";
-    doc      = "";
-};
-
-flag = {
-    name      = curve;
-    arg-type  = string;
-    descrip   = "Specify the curve used for EC key generation";
-    doc      = "Supported values are secp192r1, secp224r1, secp256r1, secp384r1 and secp521r1.";
-};
-
-flag = {
-    name      = sec-param;
-    arg-type  = string;
-    arg-name  = "Security parameter";
-    descrip   = "Specify the security level [low, legacy, medium, high, ultra]";
-    doc      = "This is alternative to the bits option.";
-};
-
-flag = {
     name      = disable-quick-random;
     descrip   = "No effect";
     doc      = "";