Add implementation

1 files changed, 63 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..6b11e46
--- /dev/null
+++ b/README
@@ -0,0 +1,63 @@
+This package contains the OpenSSL key agent and client utilities.
+
+The aim of these utilities is to provide an openssl-rsautl(1) drop-in
+replacement for performing cryptographic operations using a private key
+that is unlocked for the session, similar to OpenSSH's ssh-agent(1).
+
+The typical usage is as follows:
+
+1. Start the OpenSSL key agent which prompts for a password/PIN for the
+   specified private key. The agent then forks off the daemon which unlocks
+   the key, opens a UNIX domain socket, and waits for cryptographic operation
+   requests from the OpenSSL client.
+
+   The agent also prints to stdout a shell script fragment that sets the
+   environment variables necessary for locating the agent.
+
+2. Source the script fragment printed by the agent into the shell.
+
+3. Run the OpenSSL client to perform a cryptographic operation.
+
+For example:
+
+$ openssl-agent-pkcs11 "pkcs11:object=SIGN%20key" >agent.env
+Enter PIN for PKCS#11:*******
+
+$ source agent.env
+Agent pid 14696
+
+$ openssl-client rsautl -sign -keyform engine -engine pkcs11 \
+-inkey "pkcs11:object=SIGN%20key" <<<test >signature
+
+...
+
+$ kill 14696
+
+By default, openssl-agent-pkcs11(1) uses opensc-pkcs11 module, unless a
+different one is explicitly specified in the private key URL (see RFC7512
+Section "The PKCS #11 URI Scheme" for details).
+
+To use opensc-pkcs11, make sure that the following packages are installed in
+the system:
+
+Debian/Ubuntu: opensc-pkcs11
+Fedora/RHEL:   opensc
+
+Note that for some Debian versions the opensc-pkcs11 package has the missing
+libpcsclite1 dependency, so make sure it is also installed.
+
+For more information see:
+
+https://build2.org/
+
+See the NEWS file for the user-visible changes from the previous release.
+
+See the LICENSE file for the distribution conditions.
+
+See the INSTALL file for the prerequisites and installation instructions.
+
+See the doc/ directory for documentation.
+
+Send questions, bug reports, or any other feedback to the users@build2.org
+mailing list. You can post without subscribing. See https://lists.build2.org
+for searchable archives, posting guidelines, etc.