diff options
Diffstat (limited to 'doc/invoke-p11tool.texi')
| -rw-r--r-- | doc/invoke-p11tool.texi | 626 |
1 files changed, 626 insertions, 0 deletions
diff --git a/doc/invoke-p11tool.texi b/doc/invoke-p11tool.texi new file mode 100644 index 0000000..53009bf --- /dev/null +++ b/doc/invoke-p11tool.texi @@ -0,0 +1,626 @@ +@node p11tool Invocation +@subsection Invoking p11tool +@pindex p11tool + +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. + + +@anchor{p11tool usage} +@subsubheading p11tool help/usage (@option{-?}) +@cindex p11tool help + +The text printed is the same whether selected with the @code{help} option +(@option{--help}) or the @code{more-help} option (@option{--more-help}). @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 +p11tool - GnuTLS PKCS #11 tool +Usage: p11tool [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... [url] + +None: + + +Tokens: + + --list-tokens List all available tokens + --list-token-urls List the URLs available tokens + --list-mechanisms List all available mechanisms in a token + --initialize Initializes a PKCS #11 token + --initialize-pin Initializes/Resets a PKCS #11 token user PIN + --initialize-so-pin Initializes/Resets a PKCS #11 token security officer PIN + --set-pin=str Specify the PIN to use on token operations + --set-so-pin=str Specify the Security Officer's PIN to use on token initialization + +Object listing: + + --list-all List all available objects in a token + --list-all-certs List all available certificates in a token + --list-certs List all certificates that have an associated private key + --list-all-privkeys List all available private keys in a token + --list-privkeys an alias for the 'list-all-privkeys' option + --list-keys an alias for the 'list-all-privkeys' option + --list-all-trusted List all available certificates marked as trusted + --export Export the object specified by the URL + - prohibits these options: + export-stapled + export-chain + export-pubkey + --export-stapled Export the certificate object specified by the URL + - prohibits these options: + export + export-chain + export-pubkey + --export-chain Export the certificate specified by the URL and its chain of trust + - prohibits these options: + export-stapled + export + export-pubkey + --export-pubkey Export the public key for a private key + - prohibits these options: + export-stapled + export + export-chain + --info List information on an available object in a token + --trusted an alias for the 'mark-trusted' option + --distrusted an alias for the 'mark-distrusted' option + +Key generation: + + --generate-privkey=str Generate private-public key pair of given type + --bits=num Specify the number of bits for the key generate + --curve=str Specify the curve used for EC key generation + --sec-param=str Specify the security level + +Writing objects: + + --set-id=str Set the CKA_ID (in hex) for the specified by the URL object + - prohibits the option 'write' + --set-label=str Set the CKA_LABEL for the specified by the URL object + - prohibits these options: + write + set-id + --write Writes the loaded objects to a PKCS #11 token + --delete Deletes the objects matching the given PKCS #11 URL + --label=str Sets a label for the write operation + --id=str Sets an ID for the write operation + --mark-wrap Marks the generated key to be a wrapping key + --mark-trusted Marks the object to be written as trusted + - prohibits the option 'mark-distrusted' + --mark-distrusted When retrieving objects, it requires the objects to be distrusted (blacklisted) + - prohibits the option 'mark-trusted' + --mark-decrypt Marks the object to be written for decryption + --mark-sign Marks the object to be written for signature generation + --mark-ca Marks the object to be written as a CA + --mark-private Marks the object to be written as private + --ca an alias for the 'mark-ca' option + --private an alias for the 'mark-private' option + --mark-always-authenticate Marks the object to be written as always authenticate + --secret-key=str Provide a hex encoded secret key + --load-privkey=file Private key file to use + - file must pre-exist + --load-pubkey=file Public key file to use + - file must pre-exist + --load-certificate=file Certificate file to use + - file must pre-exist + +Other options: + + -d, --debug=num Enable debugging + - it must be in the range: + 0 to 9999 + --outfile=str Output file + --login Force (user) login to token + --so-login Force security officer login to token + --admin-login an alias for the 'so-login' option + --test-sign Tests the signature operation of the provided object + --sign-params=str Sign with a specific signature algorithm + --hash=str Hash algorithm to use for signing + --generate-random=num Generate random data + -8, --pkcs8 Use PKCS #8 format for private keys + --inder Use DER/RAW format for input + --inraw an alias for the 'inder' option + --outder Use DER format for output certificates, private keys, and DH parameters + --outraw an alias for the 'outder' option + --provider=file Specify the PKCS #11 provider library + --detailed-url Print detailed URLs + --only-urls Print a compact listing using only the URLs + --batch Disable all interaction with the tool + +Version, usage and configuration options: + + -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. +Operands and options may be intermixed. They will be reordered. + +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. + + +Please send bug reports to: <bugs@@gnutls.org> + +@end example +@exampleindent 4 + +@anchor{p11tool token-related-options} +@subsubheading token-related-options options +Tokens. +@subsubheading list-token-urls option. +@anchor{p11tool list-token-urls} + +This is the ``list the urls available tokens'' option. +This is a more compact version of --list-tokens. +@subsubheading initialize-so-pin option. +@anchor{p11tool initialize-so-pin} + +This is the ``initializes/resets a pkcs #11 token security officer pin'' option. +This initializes the security officer's PIN. When used non-interactively use the GNUTLS_NEW_SO_PIN +environment variables to initialize SO's PIN. +@subsubheading set-pin option. +@anchor{p11tool set-pin} + +This is the ``specify the pin to use on token operations'' option. +This option takes a ArgumentType.STRING argument. +Alternatively the GNUTLS_PIN environment variable may be used. +@subsubheading set-so-pin option. +@anchor{p11tool set-so-pin} + +This is the ``specify the security officer's pin to use on token initialization'' option. +This option takes a ArgumentType.STRING argument. +Alternatively the GNUTLS_SO_PIN environment variable may be used. +@anchor{p11tool object-list-related-options} +@subsubheading object-list-related-options options +Object listing. +@subsubheading list-all option. +@anchor{p11tool list-all} + +This is the ``list all available objects in a token'' option. +All objects available in the token will be listed. That includes +objects which are potentially unaccessible using this tool. +@subsubheading list-all-certs option. +@anchor{p11tool list-all-certs} + +This is the ``list all available certificates in a token'' option. +That option will also provide more information on the +certificates, for example, expand the attached extensions in a trust +token (like p11-kit-trust). +@subsubheading list-certs option. +@anchor{p11tool list-certs} + +This is the ``list all certificates that have an associated private key'' option. +That option will only display certificates which have a private +key associated with them (share the same ID). +@subsubheading list-all-privkeys option. +@anchor{p11tool list-all-privkeys} + +This is the ``list all available private keys in a token'' option. +Lists all the private keys in a token that match the specified URL. +@subsubheading list-privkeys option. +@anchor{p11tool list-privkeys} + +This is an alias for the @code{list-all-privkeys} option, +@pxref{p11tool list-all-privkeys, the list-all-privkeys option documentation}. + +@subsubheading list-keys option. +@anchor{p11tool list-keys} + +This is an alias for the @code{list-all-privkeys} option, +@pxref{p11tool list-all-privkeys, the list-all-privkeys option documentation}. + +@subsubheading export-stapled option. +@anchor{p11tool export-stapled} + +This is the ``export the certificate object specified by the url'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +export, export-chain, export-pubkey. +@end itemize + +Exports the certificate specified by the URL while including any attached extensions to it. +Since attached extensions are a p11-kit extension, this option is only +available on p11-kit registered trust modules. +@subsubheading export-chain option. +@anchor{p11tool export-chain} + +This is the ``export the certificate specified by the url and its chain of trust'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +export-stapled, export, export-pubkey. +@end itemize + +Exports the certificate specified by the URL and generates its chain of trust based on the stored certificates in the module. +@subsubheading export-pubkey option. +@anchor{p11tool export-pubkey} + +This is the ``export the public key for a private key'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +export-stapled, export, export-chain. +@end itemize + +Exports the public key for the specified private key +@subsubheading trusted option. +@anchor{p11tool trusted} + +This is an alias for the @code{mark-trusted} option, +@pxref{p11tool mark-trusted, the mark-trusted option documentation}. + +@subsubheading distrusted option. +@anchor{p11tool distrusted} + +This is an alias for the @code{mark-distrusted} option, +@pxref{p11tool mark-distrusted, the mark-distrusted option documentation}. + +@anchor{p11tool keygen-related-options} +@subsubheading keygen-related-options options +Key generation. +@subsubheading generate-privkey option. +@anchor{p11tool generate-privkey} + +This is the ``generate private-public key pair of given type'' option. +This option takes a ArgumentType.STRING argument. +Generates a private-public key pair in the specified token. +Acceptable types are RSA, ECDSA, Ed25519, and DSA. Should be combined with --sec-param or --bits. +@subsubheading generate-rsa option. +@anchor{p11tool generate-rsa} + +This is the ``generate an rsa private-public key pair'' option. +Generates an RSA private-public key pair on the specified token. +Should be combined with --sec-param or --bits. + +@strong{NOTE}@strong{: THIS OPTION IS DEPRECATED} +@subsubheading generate-dsa option. +@anchor{p11tool generate-dsa} + +This is the ``generate a dsa private-public key pair'' option. +Generates a DSA private-public key pair on the specified token. +Should be combined with --sec-param or --bits. + +@strong{NOTE}@strong{: THIS OPTION IS DEPRECATED} +@subsubheading generate-ecc option. +@anchor{p11tool generate-ecc} + +This is the ``generate an ecdsa private-public key pair'' option. +Generates an ECDSA private-public key pair on the specified token. +Should be combined with --curve, --sec-param or --bits. + +@strong{NOTE}@strong{: THIS OPTION IS DEPRECATED} +@subsubheading bits option. +@anchor{p11tool bits} + +This is the ``specify the number of bits for the key generate'' option. +This option takes a ArgumentType.NUMBER argument. +For applications which have no key-size restrictions the +--sec-param option is recommended, as the sec-param levels will adapt +to the acceptable security levels with the new versions of gnutls. +@subsubheading curve option. +@anchor{p11tool curve} + +This is the ``specify the curve used for ec key generation'' option. +This option takes a ArgumentType.STRING argument. +Supported values are secp192r1, secp224r1, secp256r1, secp384r1 and secp521r1. +@subsubheading sec-param option. +@anchor{p11tool sec-param} + +This is the ``specify the security level'' option. +This option takes a ArgumentType.STRING argument @file{Security parameter}. +This is alternative to the bits option. Available options are [low, legacy, medium, high, ultra]. +@anchor{p11tool write-object-related-options} +@subsubheading write-object-related-options options +Writing objects. +@subsubheading set-id option. +@anchor{p11tool set-id} + +This is the ``set the cka_id (in hex) for the specified by the url object'' option. +This option takes a ArgumentType.STRING argument. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +write. +@end itemize + +Modifies or sets the CKA_ID in the specified by the URL object. The ID should be specified in hexadecimal format without a '0x' prefix. +@subsubheading set-label option. +@anchor{p11tool set-label} + +This is the ``set the cka_label for the specified by the url object'' option. +This option takes a ArgumentType.STRING argument. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +write, set-id. +@end itemize + +Modifies or sets the CKA_LABEL in the specified by the URL object +@subsubheading write option. +@anchor{p11tool write} + +This is the ``writes the loaded objects to a pkcs #11 token'' option. +It can be used to write private, public keys, certificates or secret keys to a token. Must be combined with one of --load-privkey, --load-pubkey, --load-certificate option. + +When writing a certificate object, its CKA_ID is set to the same CKA_ID of the corresponding public key, if it exists on the token; otherwise it will be derived from the X.509 Subject Key Identifier of the certificate. If this behavior is undesired, write the public key to the token beforehand. +@subsubheading id option. +@anchor{p11tool id} + +This is the ``sets an id for the write operation'' option. +This option takes a ArgumentType.STRING argument. +Sets the CKA_ID to be set by the write operation. The ID should be specified in hexadecimal format without a '0x' prefix. +@subsubheading mark-wrap option. +@anchor{p11tool mark-wrap} + +This is the ``marks the generated key to be a wrapping key'' option. +Marks the generated key with the CKA_WRAP flag. +@subsubheading mark-trusted option. +@anchor{p11tool mark-trusted} + +This is the ``marks the object to be written as trusted'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +mark-distrusted. +@item +can be disabled with --no-mark-trusted. +@end itemize + +Marks the object to be generated/written with the CKA_TRUST flag. +@subsubheading mark-distrusted option. +@anchor{p11tool mark-distrusted} + +This is the ``when retrieving objects, it requires the objects to be distrusted (blacklisted)'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +mark-trusted. +@end itemize + +Ensures that the objects retrieved have the CKA_X_TRUST flag. +This is p11-kit trust module extension, thus this flag is only valid with +p11-kit registered trust modules. +@subsubheading mark-decrypt option. +@anchor{p11tool mark-decrypt} + +This is the ``marks the object to be written for decryption'' option. +Marks the object to be generated/written with the CKA_DECRYPT flag set to true. +@subsubheading mark-sign option. +@anchor{p11tool mark-sign} + +This is the ``marks the object to be written for signature generation'' option. +Marks the object to be generated/written with the CKA_SIGN flag set to true. +@subsubheading mark-ca option. +@anchor{p11tool mark-ca} + +This is the ``marks the object to be written as a ca'' option. +Marks the object to be generated/written with the CKA_CERTIFICATE_CATEGORY as CA. +@subsubheading mark-private option. +@anchor{p11tool mark-private} + +This is the ``marks the object to be written as private'' option. +Marks the object to be generated/written with the CKA_PRIVATE flag. The written object will require a PIN to be used. +@subsubheading ca option. +@anchor{p11tool ca} + +This is an alias for the @code{mark-ca} option, +@pxref{p11tool mark-ca, the mark-ca option documentation}. + +@subsubheading private option. +@anchor{p11tool private} + +This is an alias for the @code{mark-private} option, +@pxref{p11tool mark-private, the mark-private option documentation}. + +@subsubheading mark-always-authenticate option. +@anchor{p11tool mark-always-authenticate} + +This is the ``marks the object to be written as always authenticate'' option. +Marks the object to be generated/written with the CKA_ALWAYS_AUTHENTICATE flag. The written object will Mark the object as requiring authentication (pin entry) before every operation. +@subsubheading secret-key option. +@anchor{p11tool secret-key} + +This is the ``provide a hex encoded secret key'' option. +This option takes a ArgumentType.STRING argument. +This secret key will be written to the module if --write is specified. +@anchor{p11tool other-options} +@subsubheading other-options options +Other options. +@subsubheading debug option (-d). +@anchor{p11tool debug} + +This is the ``enable debugging'' option. +This option takes a ArgumentType.NUMBER argument. +Specifies the debug level. +@subsubheading so-login option. +@anchor{p11tool so-login} + +This is the ``force security officer login to token'' option. +Forces login to the token as security officer (admin). +@subsubheading admin-login option. +@anchor{p11tool admin-login} + +This is an alias for the @code{so-login} option, +@pxref{p11tool so-login, the so-login option documentation}. + +@subsubheading test-sign option. +@anchor{p11tool test-sign} + +This is the ``tests the signature operation of the provided object'' option. +It can be used to test the correct operation of the signature operation. +If both a private and a public key are available this operation will sign and verify +the signed data. +@subsubheading sign-params option. +@anchor{p11tool sign-params} + +This is the ``sign with a specific signature algorithm'' option. +This option takes a ArgumentType.STRING argument. +This option can be combined with --test-sign, to sign with +a specific signature algorithm variant. The only option supported is 'RSA-PSS', and should be +specified in order to use RSA-PSS signature on RSA keys. +@subsubheading hash option. +@anchor{p11tool hash} + +This is the ``hash algorithm to use for signing'' option. +This option takes a ArgumentType.STRING argument. +This option can be combined with test-sign. Available hash functions are SHA1, RMD160, SHA256, SHA384, SHA512, SHA3-224, SHA3-256, SHA3-384, SHA3-512. +@subsubheading generate-random option. +@anchor{p11tool generate-random} + +This is the ``generate random data'' option. +This option takes a ArgumentType.NUMBER argument. +Asks the token to generate a number of bytes of random bytes. +@subsubheading inder option. +@anchor{p11tool inder} + +This is the ``use der/raw format for input'' option. +Use DER/RAW format for input certificates and private keys. +@subsubheading inraw option. +@anchor{p11tool inraw} + +This is an alias for the @code{inder} option, +@pxref{p11tool inder, the inder option documentation}. + +@subsubheading outder option. +@anchor{p11tool outder} + +This is the ``use der format for output certificates, private keys, and dh parameters'' option. +The output will be in DER or RAW format. +@subsubheading outraw option. +@anchor{p11tool outraw} + +This is an alias for the @code{outder} option, +@pxref{p11tool outder, the outder option documentation}. + +@subsubheading provider option. +@anchor{p11tool provider} + +This is the ``specify the pkcs #11 provider library'' option. +This option takes a ArgumentType.FILE argument. +This will override the default options in /etc/gnutls/pkcs11.conf +@subsubheading provider-opts option. +@anchor{p11tool provider-opts} + +This is the ``specify parameters for the pkcs #11 provider library'' option. +This option takes a ArgumentType.STRING argument. +This is a PKCS#11 internal option used by few modules. + Mainly for testing PKCS#11 modules. + +@strong{NOTE}@strong{: THIS OPTION IS DEPRECATED} +@subsubheading batch option. +@anchor{p11tool batch} + +This is the ``disable all interaction with the tool'' option. +In batch mode there will be no prompts, all parameters need to be specified on command line. +@subsubheading version option (-v). +@anchor{p11tool version} + +This is the ``output version information and exit'' option. +This option takes a ArgumentType.KEYWORD argument. +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +@subsubheading help option (-h). +@anchor{p11tool help} + +This is the ``display extended usage information and exit'' option. +Display usage information and exit. +@subsubheading more-help option (-!). +@anchor{p11tool more-help} + +This is the ``extended usage information passed thru pager'' option. +Pass the extended usage information through a pager. +@anchor{p11tool exit status} +@subsubheading p11tool 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{p11tool See Also} +@subsubheading p11tool See Also + certtool (1) +@anchor{p11tool Examples} +@subsubheading p11tool Examples +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-privkey 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 + |