summaryrefslogtreecommitdiff
path: root/Documentation/CLI_ABI.md
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/CLI_ABI.md')
-rw-r--r--Documentation/CLI_ABI.md73
1 files changed, 73 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
+