aboutsummaryrefslogtreecommitdiff
path: root/openssl/client/options.cli
blob: 795a434a5e9637ba7f0c041dccd2c2fb602bb143 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
// file      : openssl/client/options.cli
// copyright : Copyright (c) 2014-2019 Code Synthesis Ltd
// 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} rsautl [<options>]}

      \h|DESCRIPTION|

      The \cb{rsautl} command is a drop-in replacement for the
      \cb{openssl-rsautl(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-rsautl(1)} options and values to the following usage:

      \
      $ openssl-client rsautl -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}.

      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.
    "
  }
}