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 variable
GNUTLS_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      = 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      = initialize;
    descrip   = "Initializes a PKCS #11 token";
    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      = label;
    arg-type  = string;
    descrip   = "Sets a label for the write operation";
    doc       = "";
};

flag = {
    name      = trusted;
    disable   = "no";
    disabled;
    descrip   = "Marks the object to be written as trusted";
    doc = "";
};

flag = {
    name      = ca;
    disable   = "no";
    disabled;
    descrip   = "Marks the object to be written as a CA";
    doc = "";
};

flag = {
    name      = private;
    disable   = "no";
    enabled;
    descrip   = "Marks the object to be written as private";
    doc = "The written object will require a PIN to be used.";
};

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      = 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      = 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";
};


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_;
};