path: root/src/p11tool-args.def

AutoGen Definitions options;
prog-name     = p11tool;
prog-title    = "GnuTLS PKCS #11 tool";
prog-desc     = "Program to handle PKCS #11 smart cards and security modules.\n";
detail    = "Program that allows operations on PKCS #11 smart cards
and security modules. 

To use PKCS #11 tokens with GnuTLS the p11-kit configuration files need to be setup.
That is create a .module file in /etc/pkcs11/modules with the contents 'module: /path/to/pkcs11.so'.
Alternatively the configuration file /etc/gnutls/pkcs11.conf has to exist and contain a number
of lines of the form 'load=/usr/lib/opensc-pkcs11.so'.

You can provide the PIN to be used for the PKCS #11 operations with the environment variables
GNUTLS_PIN and GNUTLS_SO_PIN.
";

short-usage   = "p11tool [options] [url]\np11tool --help for usage instructions.\n";
explain       = "";
reorder-args;
argument = "[url]";

#define  OUTFILE_OPT   1
#include args-std.def

flag = {
    name      = list-tokens;
    descrip   = "List all available tokens";
    doc = "";
};

flag = {
    name      = export;
    descrip   = "Export the object specified by the URL";
    doc = "";
};

flag = {
    name      = export-chain;
    descrip   = "Export the certificate specified by the URL and its chain of trust";
    doc = "Exports the certificate specified by the URL and generates its chain of trust based on the stored certificates in the module.";
};

flag = {
    name      = list-mechanisms;
    descrip   = "List all available mechanisms in a token";
    doc = "";
};

flag = {
    name      = info;
    descrip   = "List information on an available object in a token";
    doc = "";
};

flag = {
    name      = list-all;
    descrip   = "List all available objects in a token";
    doc = "";
};

flag = {
    name      = list-all-certs;
    descrip   = "List all available certificates in a token";
    doc = "";
};

flag = {
    name      = list-certs;
    descrip   = "List all certificates that have an associated private key";
    doc = "";
};

flag = {
    name      = list-all-privkeys;
    descrip   = "List all available private keys in a token";
    doc = "Lists all the private keys in a token that match the specified URL.";
};

flag = {
    name      = list-privkeys;
    aliases   = list-all-privkeys;
};

flag = {
    name      = list-keys;
    aliases   = list-all-privkeys;
};

flag = {
    name      = list-all-trusted;
    descrip   = "List all available certificates marked as trusted";
    doc = "";
};

flag = {
    name      = write;
    descrip   = "Writes the loaded objects to a PKCS #11 token";
    doc = "It can be used to write private keys, certificates or secret keys to a token.";
};

flag = {
    name      = delete;
    descrip   = "Deletes the objects matching the PKCS #11 URL";
    doc = "";
};

flag = {
    name      = generate-random;
    descrip   = "Generate random data";
    arg-type  = number;
    doc = "Asks the token to generate a number of bytes of random bytes.";
};

flag = {
    name      = generate-rsa;
    descrip   = "Generate an RSA private-public key pair";
    doc = "Generates an RSA private-public key pair on the specified token.";
};

flag = {
    name      = generate-dsa;
    descrip   = "Generate an RSA private-public key pair";
    doc = "Generates an RSA private-public key pair on the specified token.";
};
flag = {
    name      = generate-ecc;
    descrip   = "Generate an RSA private-public key pair";
    doc = "Generates an RSA private-public key pair on the specified token.";
};


flag = {
    name      = export-pubkey;
    descrip   = "Export the public key for a private key";
    doc = "Exports the public key for the specified private key";
};

flag = {
    name      = set-id;
    descrip   = "Set the CKA_ID in the specified by the URL object";
    doc = "Sets the CKA_ID in the specified by the URL object. The ID should be specified in hexadecimal format.";
    arg-type  = string;
};

flag = {
    name      = set-label;
    descrip   = "Set the CKA_LABEL in the specified by the URL object";
    doc = "Sets the CKA_LABEL in the specified by the URL object";
    arg-type  = string;
};

flag = {
    name      = label;
    arg-type  = string;
    descrip   = "Sets a label for the write operation";
    doc       = "";
};

flag = {
    name      = mark-wrap;
    disable   = "no";
    disabled;
    descrip   = "Marks the generated key to be a wrapping key";
    doc = "Marks the generated key with the CKA_WRAP flag.";
};

flag = {
    name      = mark-trusted;
    disable   = "no";
    disabled;
    descrip   = "Marks the object to be written as trusted";
    doc = "Marks the object to be generated/copied with the CKA_TRUST flag.";
};

flag = {
    name      = mark-ca;
    disable   = "no";
    disabled;
    descrip   = "Marks the object to be written as a CA";
    doc = "Marks the object to be generated/copied with the CKA_CERTIFICATE_CATEGORY as CA.";
};

flag = {
    name      = mark-private;
    disable   = "no";
    enabled;
    descrip   = "Marks the object to be written as private";
    doc = "Marks the object to be generated/copied with the CKA_PRIVATE flag. The written object will require a PIN to be used.";
};

flag = {
    name      = trusted;
    aliases   = mark-trusted;
};

flag = {
    name      = ca;
    aliases   = mark-ca;
};

flag = {
    name      = private;
    aliases   = mark-private;
};

flag = {
    name      = login;
    descrip   = "Force (user) login to token";
    disabled;
    disable   = "no";
    doc       = "";
};

flag = {
    name      = so-login;
    descrip   = "Force security officer login to token";
    disabled;
    disable   = "no";
    doc       = "Forces login to the token as security officer (admin).";
};

flag = {
    name      = admin-login;
    aliases   = so-login;
};

flag = {
    name      = detailed-url;
    descrip   = "Print detailed URLs";
    disabled;
    disable   = "no";
    doc   = "";
};

flag = {
    name      = secret-key;
    arg-type  = string;
    descrip   = "Provide a hex encoded secret key";
    doc   = "";
};

flag = {
    name      = load-privkey;
    arg-type  = file;
    file-exists = yes;
    descrip   = "Private key file to use";
    doc      = "";
};

flag = {
    name      = load-pubkey;
    arg-type  = file;
    file-exists = yes;
    descrip   = "Public key file to use";
    doc      = "";
};

flag = {
    name      = load-certificate;
    arg-type  = file;
    file-exists = yes;
    descrip   = "Certificate file to use";
    doc      = "";
};

flag = {
    name      = pkcs8;
    value     = 8;
    descrip   = "Use PKCS #8 format for private keys";
    doc      = "";
};

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";
    doc      = "This is alternative to the bits option. Available options are [low, legacy, medium, high, ultra].";
};


flag = {
    name      = inder;
    descrip   = "Use DER/RAW format for input";
    disabled;
    disable   = "no";
    doc      = "Use DER/RAW format for input certificates and private keys.";
};

flag = {
    name      = inraw;
    aliases   = inder;
};

flag = {
    name      = outder;
    descrip   = "Use DER format for output certificates, private keys, and DH parameters";
    disabled;
    disable   = "no";
    doc       = "The output will be in DER or RAW format.";
};

flag = {
    name      = outraw;
    aliases   = outder;
};

flag = {
    name      = initialize;
    descrip   = "Initializes a PKCS #11 token";
    doc = "";
};

flag = {
    name      = set-pin;
    arg-type  = string;
    descrip   = "Specify the PIN to use on token initialization";
    doc      = "Alternatively the GNUTLS_PIN environment variable may be used.";
};

flag = {
    name      = set-so-pin;
    arg-type  = string;
    descrip   = "Specify the Security Officer's PIN to use on token initialization";
    doc      = "Alternatively the GNUTLS_SO_PIN environment variable may be used.";
};

flag = {
    name      = provider;
    arg-type  = file;
    file-exists = yes;
    descrip   = "Specify the PKCS #11 provider library";
    doc      = "This will override the default options in /etc/gnutls/pkcs11.conf";
};

flag = {
    name      = batch;
    descrip   = "Disable all interaction with the tool. All parameters need to be specified on command line.";
    doc = "";
};


doc-section = {
  ds-type = 'SEE ALSO';
  ds-format = 'texi';
  ds-text   = <<-_EOT_
    certtool (1)
_EOT_;
};

doc-section = {
  ds-type = 'EXAMPLES';
  ds-format = 'texi';
  ds-text   = <<-_EOT_
To view all tokens in your system use:
@example
$ p11tool --list-tokens
@end example

To view all objects in a token use:
@example
$ p11tool --login --list-all "pkcs11:TOKEN-URL"
@end example

To store a private key and a certificate in a token run:
@example
$ p11tool --login --write "pkcs11:URL" --load-privkey key.pem \
          --label "Mykey"
$ p11tool --login --write "pkcs11:URL" --load-certificate cert.pem \
          --label "Mykey"
@end example
Note that some tokens require the same label to be used for the certificate
and its corresponding private key.

To generate an RSA private key inside the token use:
@example
$ p11tool --login --generate-rsa --bits 1024 --label "MyNewKey" \
          --outfile MyNewKey.pub "pkcs11:TOKEN-URL"
@end example
The bits parameter in the above example is explicitly set because some
tokens only support limited choices in the bit length. The output file is the
corresponding public key. This key can be used to general a certificate
request with certtool.
@example
certtool --generate-request --load-privkey "pkcs11:KEY-URL" \
   --load-pubkey MyNewKey.pub --outfile request.pem
@end example

_EOT_;
};