// file      : openssl/agent/pkcs11/options.cli
// copyright : Copyright (c) 2014-2018 Code Synthesis Ltd
// license   : MIT; see accompanying LICENSE file

include <openssl/options.cli>;

"\section=1"
"\name=openssl-agent-pkcs11"
"\summary=OpenSSL PKCS#11 key agent"

namespace openssl
{
  namespace agent
  {
    namespace pkcs11
    {
      {
        "<options> <url>",

        "
        \h|SYNOPSIS|

        \c{\b{openssl-agent-pkcs11 --help}\n
           \b{openssl-agent-pkcs11 --version}\n
           \b{openssl-agent-pkcs11} [<options>] <url>}

        \h|DESCRIPTION|

        The \cb{PKCS#11} key agent prompts for a PIN for the specified token
        and forks off the daemon, which unlocks the key, opens a UNIX domain
        socket, and waits for cryptographic operation requests from the
        OpenSSL client \l{openssl-client(1)}. The agent also prints to
        \cb{stdout} a shell script fragment that sets the environment
        variables necessary for locating the agent. See the ENVIRONMENT
        section for details.

        The daemon can be run in the simulation mode without actually logging
        into the \cb{PKCS#11} token. If the \cb{--simulate} option is
        specified with the \cb{success} outcome, the daemon pretends to unlock
        the requested key and responds with a dummy signature to the
        subsequent data signing requests. The \cb{failure} outcome causes the
        daemon to exit with non-zero status, as if it failed to find the key.
        This mode is mostly useful for testing.
        "
      }

      class options
      {
        "\h|OPTIONS|"

        bool --help {"Print usage information and exit."}
        bool --version {"Print version and exit."}

        simulate_outcome --simulate
        {
          "<outcome>",
          "Run the daemon in the simulation mode."
        }
      };

      "
      \h|ENVIRONMENT|

      The printed shell script fragment sets the
      \cb{OPENSSL_AGENT_PKCS11_SOCK} and \cb{OPENSSL_AGENT_PKCS11_PID}
      environment variables. The former refers to the Unix-domain socket that
      should be used by \cb{openssl-client(1)} for communicating with the
      daemon. The latter contains the daemon process id that can be used to
      terminate the daemon by sending it the \cb{SIGTERM} signal.
      "

      "
      \h|EXIT STATUS|

      Non-zero exit status is returned in case of an error.
      "
    }
  }
}