aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJakob Unterwurzacher2017-02-12 19:12:02 +0100
committerJakob Unterwurzacher2017-02-12 19:20:21 +0100
commit54caaf4b980e0432baef54c5129aa53c43be70e8 (patch)
tree6181128532b23db5952b59379adf24be35b063bc
parent8adfbf2dc34560df7436c89b59a9749d2dd3b78e (diff)
Add CLI ABI documentation
Closes https://github.com/rfjakob/gocryptfs/issues/77
-rw-r--r--Documentation/CLI_ABI.md73
-rw-r--r--README.md7
2 files changed, 80 insertions, 0 deletions
diff --git a/Documentation/CLI_ABI.md b/Documentation/CLI_ABI.md
new file mode 100644
index 0000000..6930e83
--- /dev/null
+++ b/Documentation/CLI_ABI.md
@@ -0,0 +1,73 @@
+Stable CLI ABI
+==============
+
+If you want to call gocryptfs from your script or app, this is the
+stable ABI.
+
+General
+-------
+
+1. A password is piped into gocryptfs with an optional terminating
+ newline. Any unexpected data after the final newline will
+ cause gocryptfs to abort.
+2. Always pass "--" after the options. This prevents a CIPERDIR that
+ starts with a dash ("-") to wreak havoc.
+3. Use "-q" to get rid of all informational messages. Only error
+ messages (if any) will be printed to stderr (capture it!).
+4. Check the exit code of gocryptfs. 0 is success, anything else is an
+ error and details about that error will have been printed to stderr.
+
+Initialize Filesystem
+---------------------
+
+### Bash example
+
+ $ cat mypassword.txt | gocryptfs -init -q -- CIPHERDIR
+
+Content of "mypassword.txt":
+
+ mypassword1234
+
+### What you have to pipe to gocryptfs
+
+1. Password
+2. Optional newline
+
+### Notes
+
+1. The CIPHERDIR directory must exist and be empty
+
+Mount
+-----
+
+### Bash example
+
+ $ cat mypassword.txt | gocryptfs -q -- CIPHERDIR MOUNTPOINT
+
+### What you have to pipe to gocryptfs
+
+Same as for "Initialize Filesystem".
+
+### Notes
+
+1. The MOUNTPOINT directory must exist and be empty.
+
+Change Password
+---------------
+
+### Bash example
+
+ $ cat change.txt | gocryptfs -passwd -q -- CIPHERDIR
+
+Content of "change.txt":
+
+ mypassword1234
+ newpassword9876
+
+### What you have to pipe to gocryptfs
+
+1. Old password
+2. Newline
+3. New password
+4. Optional newline
+
diff --git a/README.md b/README.md
index f130c52..905c3c0 100644
--- a/README.md
+++ b/README.md
@@ -79,6 +79,13 @@ The [MANPAGE.md](Documentation/MANPAGE.md) containes a description of available
If you already have gocryptfs installed, run `./MANPAGE-render.bash` to bring up the rendered manpage in
your man pager (requires pandoc).
+Stable CLI ABI
+--------------
+
+If you want to call gocryptfs from your app or script, see
+[CLI_ABI.md](Documentation/CLI_ABI.md) for the official stable
+ABI. This ABI is regression-tested by the test suite.
+
Storage Overhead
----------------