// file      : openssl/client/options.cli
// license   : MIT; see accompanying LICENSE file

include <openssl/options.cli>;

"\section=1"
"\name=openssl-client"
"\summary=OpenSSL client"

namespace openssl
{
  namespace client
  {
    {
      "<options>",

      "
      \h|SYNOPSIS|

      \c{\b{openssl-client --help}\n
         \b{openssl-client --version}\n
         \b{openssl-client} pkeyutl [<options>]}

      \h|DESCRIPTION|

      The \cb{pkeyutl} command is a drop-in replacement for the
      \cb{openssl-pkeyutl(1)} cryptographic operations. Instead of performing
      the operations itself, it forwards the request to an OpenSSL key agent
      that keeps the private key unlocked for the session.

      Currently, data signing with a private key stored in a \cb{PKCS#11}
      token is the only supported arrangement. This limits the
      \cb{openssl-pkeyutl(1)} options and values to the following usage:

      \
      $ openssl-client pkeyutl -sign -keyform engine -engine pkcs11 -inkey pkcs11:...
      \

      This command reads data from \cb{stdin}, asks
      \cb{openssl-agent-pkcs11(1)} to sign it using the specified unlocked
      private key, and prints the resulting signature to \cb{stdout}.

      Note that the \cb{rsautl} command is also accepted for backwards
      compatibility.

      The command can be simulated without actually performing any
      cryptographic operations. If the \cb{--simulate} option is specified
      with the \cb{success} outcome, then the command prints a dummy signature
      produced by the agent and exits with zero status. The \cb{failure}
      outcome causes it to print the diagnostics to \cb{stderr} and exit with
      non-zero status. This mode is mostly useful for OpenSSL key agents
      testing.
      "
    }

    class options
    {
      "\h|OPTIONS|"

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

      bool -sign
      {
        "Sign data read from \cb{stdin}."
      }

      string -keyform
      {
        "<form>",
        "Private key format. The only supported format is \cb{engine}."
      }

      string -engine
      {
        "<engine>",
        "Engine to use for the cryptographic operation. The only supported
         engine is \cb{pkcs11}."
      }

      string -inkey
      {
        "<location>",
        "Private key location. Its format (file path, URL, etc) depends on the
         engine used. For the \cb{pkcs11} engine it should be a \cb{PKCS#11}
         URL."
      }

      simulate_outcome --simulate
      {
        "<outcome>",
        "Ask the agent to simulate the cryptographic operation instead of
         performing it for real."
      }
    };

    "
    \h|ENVIRONMENT|

    If \cb{-engine} is \cb{pkcs11}, then the \cb{OPENSSL_AGENT_PKCS11_SOCK}
    environment variable should be set to the Unix-domain socket of the
    \cb{openssl-agent-pkcs11(1)} daemon.
    "

    "
    \h|EXIT STATUS|

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