add credential storage support for external special remotes & update example

2 files changed, 49 insertions, 4 deletions

diff --git a/doc/design/external_special_remote_protocol.mdwn b/doc/design/external_special_remote_protocol.mdwn
index e93ead8d6..8fef581a0 100644
--- a/doc/design/external_special_remote_protocol.mdwn
+++ b/doc/design/external_special_remote_protocol.mdwn
@@ -189,6 +189,23 @@ in control.
   can have been set by a previous SETCONFIG. Can be run at any time.  
   (git-annex replies with VALUE followed by the value. If the setting is
   not set, the value will be empty.)
+* `SETCREDS Setting User Password`  
+  When some form of user and password is needed to access a special remote,
+  this can be used to securely store them for later use.
+  (Like SETCONFIG, this is normally sent only during INITREMOTE.)  
+  The Setting indicates which value in a remote's configuration can be
+  used to store the creds.  
+  Note that creds are normally only stored in the remote's configuration
+  when it's surely safe to do so; when gpg encryption is used, in which
+  case the creds will be encrypted using it. If creds are not stored in
+  the configuration, they'll only be stored in a local file.  
+  (embedcreds can be set to yes by the user or by SETCONFIG to force
+   the creds to be stored in the remote's configuration).
+* `GETCREDS Setting`  
+  Gets any creds that were previously stored in the remote's configuration
+  or a file.
+  (git-annex replies with "CREDS User Password". If no creds are found,
+  User and Password are both empty.)
 
 ## general messages
 
diff --git a/doc/special_remotes/external/example.sh b/doc/special_remotes/external/example.sh
index 97f8a2813..428e2ecb9 100755
--- a/doc/special_remotes/external/example.sh
+++ b/doc/special_remotes/external/example.sh
@@ -48,6 +48,32 @@ ask () {
 	esac
 }
 
+# This remote doesn't need credentials to access it,
+# but many of them will. Here's how to handle requiring the user
+# set MYPASSWORD and MYLOGIN when running initremote. The creds
+# will be stored securely for later use, so the user only needs
+# to provide them once.
+setupcreds () {
+	if [ -z "$MYPASSWORD" ] || [ -z "$MYLOGIN" ]; then
+		echo INITREMOTE-FAILURE "You need to set MYPASSWORD and MYLOGIN environment variables when running initremote."
+	else
+		echo SETCREDS mycreds "$MYLOGIN" "$MYPASSWORD"	
+		echo INITREMOTE-SUCCESS
+	fi
+}
+
+getcreds () {
+	echo GETCREDS mycreds
+	read resp
+	case "${resp%% *}" in
+		CREDS)
+			MYLOGIN="$(echo "$resp" | sed 's/^CREDS \([^ ]*\) .*/\1/')"
+			MYPASSWORD="$(echo "$resp" | sed 's/^CREDS [^ ]* //')"
+		;;
+	esac
+
+}
+
 # This has to come first, to get the protocol started.
 echo VERSION 1
 
@@ -66,16 +92,17 @@ while read line; do
 			# git annex initremote or git annex enableremote is
 			# run.)
 
+			# The directory provided by the user
+			# could be relative; make it absolute,
+			# and store that.
 			getconfig directory
-			# Input directory could be relative; make it
-			# absolute, and store that.
-			mydirectory="$(readlink -f "$RET")"
+			mydirectory="$(readlink -f "$RET")" || true
 			setconfig directory "$mydirectory"
 			if [ -z "$mydirectory" ]; then
 				echo INITREMOTE-FAILURE "You need to set directory="
 			else
 				if mkdir -p "$mydirectory"; then
-					echo INITREMOTE-SUCCESS
+					setupcreds
 				else
 					echo INITREMOTE-FAILURE "Failed to write to $mydirectory"
 				fi
@@ -87,6 +114,7 @@ while read line; do
 			# special remote here.
 			getconfig directory
 			mydirectory="$RET"
+			getcreds
 			echo PREPARE-SUCCESS
 		;;
 		TRANSFER)