ssh/auth.c: Rename some procedures

* ssh/auth.c (guile_ssh_userauth_pubkey): Rename to
  `guile_ssh_userauth_public_key_x'.  All callers updated.
  (guile_ssh_userauth_pubkey_auto_x): Rename to
  `guile_ssh_userauth_public_key_auto_x'.  All callers updated.
  (guile_ssh_userauth_password): Rename to
  `guile_ssh_userauth_password_x'.  All callers updated.
  (guile_ssh_userauth_public_key_try): New procedure.
* ssh/auth.h, ssh/auth.scm: Update.
* examples/echo/client.scm.in (main): Update.
* examples/sssh.scm.in (main): Update.
* tests/client-server.scm ("userauth-pubkey!, success"): Rename to
  "userauth-public-key!, success".  Update.
* doc/api-auth.texi (Auth): Update.  Add description of
  `userauth-public-key/try' and `userauth-agent!' procedures.
* NEWS: Update.

9 files changed, 109 insertions, 22 deletions

diff --git a/ChangeLog b/ChangeLog
index 2333898..c692bac 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,21 @@
 2014-06-01  Artyom Poptsov  <poptsov.artyom@gmail.com>
 
+	* ssh/auth.c (guile_ssh_userauth_pubkey): Rename to
+	`guile_ssh_userauth_public_key_x'.  All callers updated.
+	(guile_ssh_userauth_pubkey_auto_x): Rename to
+	`guile_ssh_userauth_public_key_auto_x'.  All callers updated.
+	(guile_ssh_userauth_password): Rename to
+	`guile_ssh_userauth_password_x'.  All callers updated.
+	(guile_ssh_userauth_public_key_try): New procedure.
+	* ssh/auth.h, ssh/auth.scm: Update.
+	* examples/echo/client.scm.in (main): Update.
+	* examples/sssh.scm.in (main): Update.
+	* tests/client-server.scm ("userauth-pubkey!, success"): Rename to
+	"userauth-public-key!, success".  Update.
+	* doc/api-auth.texi (Auth): Update.  Add description of
+	`userauth-public-key/try' and `userauth-agent!' procedures.
+	* NEWS: Update.
+
 	* examples/echo/client.scm.in (main): Fix a bug: Print fingerprint
 	as a MD5 hex string.
 
diff --git a/NEWS b/NEWS
index e93f1fd..b10bcab 100644
--- a/NEWS
+++ b/NEWS
@@ -14,6 +14,11 @@ Copyright (C) Artyom V. Poptsov <poptsov.artyom@gmail.com>
 *** Accept a public key as the first argument
 *** Accept a hash type as the second argument
     Possible types are: 'md5, 'sha1
+** Change `userauth-pubkey!'
+*** Rename it to `userauth-public-key!'
+*** Change arguments
+** Rename `userauth-pubkey-auto!' to `userauth-public-key/auto!'
+** New `userauth-public-key/try' procedure in (ssh auth)
 ** New `bytevector->hex-string' procedure in (ssh key)
 
 * Changes in version 0.6.0 (2014-03-23)
diff --git a/doc/api-auth.texi b/doc/api-auth.texi
index 459543e..9ad8f24 100644
--- a/doc/api-auth.texi
+++ b/doc/api-auth.texi
@@ -15,8 +15,8 @@ Please note that you must specify a username either on creation of a
 session or by @code{session-set!} call (@pxref{Sessions}) before
 calling of procedures from this section.
 
-@deffn {Scheme Procedure} userauth-pubkey! session public-key private-key
-Try to authenticate with a @var{public-key}.
+@deffn {Scheme Procedure} userauth-public-key! session private-key
+Try to authenticate with a public/private key.
 
 Return one of the following symbols:
 
@@ -34,7 +34,7 @@ A serious error happened.
 
 @end deffn
 
-@deffn {Scheme Procedure} userauth-autopubkey! session
+@deffn {Scheme Procedure} userauth-public-key/auto! session
 @cindex authentication with a SSH agent
 Try to automatically authenticate with @code{none} method first and
 then with public keys.  The procedure will try to get a cached private
@@ -58,6 +58,49 @@ A serious error happened.
 
 @end deffn
 
+@deffn {Scheme Procedure} userauth-public-key/try session public-key
+Try to authenticate with the given @var{public-key}.
+
+To avoid unnecessary processing and user interaction, the following
+method is provided for querying whether authentication using the
+@var{public-key} would be possible.
+
+Return one of the following symbols:
+
+@table @samp
+@item success
+The public key is accepted, you want now to use
+@code{userauth-public-key!}.
+@item partial
+You've been partially authenticated, you still have to use another
+method.
+@item denied
+Authentication failed: use another method.
+@item error
+A serious error happened.
+@end table
+
+@end deffn
+
+@deffn {Scheme Procedure} userauth-agent! session
+Try to do public key authentication with ssh agent.
+
+Return one of the following symbols:
+
+@table @samp
+@item success
+Authentication success.
+@item partial
+You've been partially authenticated, you still have to use another
+method.
+@item denied
+Authentication failed: use another method.
+@item error
+A serious error happened.
+@end table
+
+@end deffn
+
 @deffn {Scheme Procedure} userauth-password! session password
 Try to authenticate by @var{password}.
 
diff --git a/examples/echo/client.scm.in b/examples/echo/client.scm.in
index 05899c7..1d360b0 100644
--- a/examples/echo/client.scm.in
+++ b/examples/echo/client.scm.in
@@ -141,7 +141,7 @@ Options:
 
       (let ((private-key (get-prvkey session identity-file)))
 
-        (if (eqv? (userauth-pubkey! session private-key) 'error)
+        (if (eqv? (userauth-public-key! session private-key) 'error)
             (handle-error session))
 
         (let ((channel (make-channel session)))
diff --git a/examples/sssh.scm.in b/examples/sssh.scm.in
index cd3a0f5..3184f1d 100644
--- a/examples/sssh.scm.in
+++ b/examples/sssh.scm.in
@@ -180,7 +180,7 @@ Options:
           (format-debug "   MD5 hash: ~a~%" (bytevector->hex-string hash)))
 
         (print-debug "5. userauth-autopubkey!\n")
-        (let ((res (userauth-pubkey-auto! session)))
+        (let ((res (userauth-public-key/auto! session)))
           (if (eqv? res 'error)
               (handle-error session)))
 
diff --git a/ssh/auth.c b/ssh/auth.c
index 76638d1..594b145 100644
--- a/ssh/auth.c
+++ b/ssh/auth.c
@@ -67,11 +67,11 @@ ssh_auth_result_to_symbol (const int res)
     }
 }
 
-SCM_DEFINE (guile_ssh_userauth_pubkey, "userauth-pubkey!", 2, 0, 0,
+SCM_DEFINE (guile_ssh_userauth_public_key_x, "userauth-public-key!", 2, 0, 0,
             (SCM session_smob,
              SCM private_key_smob),
             "Try to authenticate with a public key.")
-#define FUNC_NAME s_guile_ssh_userauth_pubkey
+#define FUNC_NAME s_guile_ssh_userauth_public_key_x
 {
   struct session_data *session_data = _scm_to_ssh_session (session_smob);
   struct key_data *private_key_data = _scm_to_ssh_key (private_key_smob);
@@ -93,8 +93,8 @@ SCM_DEFINE (guile_ssh_userauth_pubkey, "userauth-pubkey!", 2, 0, 0,
 }
 #undef FUNC_NAME
 
-SCM_DEFINE (guile_ssh_userauth_pubkey_auto_x,
-            "userauth-pubkey-auto!", 1, 0, 0,
+SCM_DEFINE (guile_ssh_userauth_public_key_auto_x,
+            "userauth-public-key/auto!", 1, 0, 0,
             (SCM session),
             "Try to automatically authenticate with \"none\" method first and "
             "then with public keys.  If the key is encrypted the user "
@@ -114,6 +114,24 @@ SCM_DEFINE (guile_ssh_userauth_pubkey_auto_x,
 }
 #undef FUNC_NAME
 
+SCM_DEFINE (guile_ssh_userauth_public_key_try,
+            "userauth-public-key/try", 2, 0, 0,
+            (SCM session, SCM public_key),
+            "")
+#define FUNC_NAME s_guile_ssh_userauth_public_key_try
+{
+  struct session_data *sd = _scm_to_ssh_session (session);
+  struct key_data *kd = _scm_to_ssh_key (public_key);
+  char *username = NULL;        /* See "On the username" commentary above */
+  int res;
+
+  SCM_ASSERT (_public_key_p (kd), public_key, SCM_ARG2, FUNC_NAME);
+
+  res = ssh_userauth_try_publickey (sd->ssh_session, username, kd->ssh_key);
+  return ssh_auth_result_to_symbol (res);
+}
+#undef FUNC_NAME
+
 SCM_DEFINE (guile_ssh_userauth_agent_x,
             "userauth-agent!", 1, 0, 0,
             (SCM session),
@@ -131,10 +149,10 @@ SCM_DEFINE (guile_ssh_userauth_agent_x,
 #undef FUNC_NAME
 
 /* Try to authenticate by password. */
-SCM_DEFINE (guile_ssh_userauth_password, "userauth-password!", 2, 0, 0,
+SCM_DEFINE (guile_ssh_userauth_password_x, "userauth-password!", 2, 0, 0,
             (SCM session, SCM password),
             "Try to authenticate by password.")
-#define FUNC_NAME s_guile_ssh_userauth_password
+#define FUNC_NAME s_guile_ssh_userauth_password_x
 {
   struct session_data* session_data = _scm_to_ssh_session (session);
 
@@ -167,7 +185,7 @@ SCM_DEFINE (guile_ssh_userauth_password, "userauth-password!", 2, 0, 0,
 
    Return one of the following symbols: 'success, 'error, 'denied,
    'partial, 'again */
-SCM_DEFINE (guile_ssh_userauth_none, "userauth-none!", 1, 0, 0,
+SCM_DEFINE (guile_ssh_userauth_none_x, "userauth-none!", 1, 0, 0,
             (SCM arg1),
             "Try to authenticate through the \"none\" method.")
 {
diff --git a/ssh/auth.h b/ssh/auth.h
index 4d2b83a..5b31ff3 100644
--- a/ssh/auth.h
+++ b/ssh/auth.h
@@ -19,10 +19,12 @@
 #ifndef __AUTH_H__
 #define __AUTH_H__
 
-extern SCM guile_ssh_userauth_autopubkey_x (SCM arg1);
-extern SCM guile_ssh_userauth_pubkey (SCM arg1, SCM arg2, SCM arg3, SCM arg4);
-extern SCM guile_ssh_userauth_password (SCM arg1, SCM arg2, SCM arg3);
-extern SCM guile_ssh_userauth_none (SCM arg1);
+extern SCM guile_ssh_userauth_public_key_x (SCM arg1, SCM arg2);
+extern SCM guile_ssh_userauth_public_key_auto_x (SCM arg1);
+extern SCM guile_ssh_userauth_public_key_try (SCM arg1, SCM arg2);
+extern SCM guile_ssh_userauth_agent_x (SCM arg1);
+extern SCM guile_ssh_userauth_password_x (SCM arg1, SCM arg2);
+extern SCM guile_ssh_userauth_none_x (SCM arg1);
 extern SCM guile_ssh_userauth_get_list (SCM arg1);
 
 extern void init_auth_func (void);
diff --git a/ssh/auth.scm b/ssh/auth.scm
index 4eab362..6109656 100644
--- a/ssh/auth.scm
+++ b/ssh/auth.scm
@@ -24,8 +24,10 @@
 ;; 
 ;; These methods are exported:
 ;;
-;;   userauth-pubkey!
-;;   userauth-autopubkey!
+;;   userauth-public-key!
+;;   userauth-public-key/auto!
+;;   userauth-public-key/try
+;;   userauth-agent!
 ;;   userauth-password!
 ;;   userauth-none!
 ;;   userauth-get-list
@@ -35,8 +37,9 @@
 
 (define-module (ssh auth)
   #:use-module (ssh session)
-  #:export (userauth-pubkey!
-            userauth-pubkey-auto!
+  #:export (userauth-public-key!
+            userauth-public-key/auto!
+            userauth-public-key/try
             userauth-agent!
             userauth-password!
             userauth-none!
diff --git a/tests/client-server.scm b/tests/client-server.scm
index 8a17ef2..d5148c2 100644
--- a/tests/client-server.scm
+++ b/tests/client-server.scm
@@ -279,12 +279,12 @@
        (make-session-loop session
          (message-reply-success msg))))))
 
-(test-assert "userauth-pubkey!, success"
+(test-assert "userauth-public-key!, success"
   (let ((session (make-session-for-test)))
     (connect! session)
     (authenticate-server session)
     (let* ((prvkey (private-key-from-file session rsakey)))
-      (let ((res (userauth-pubkey! session prvkey)))
+      (let ((res (userauth-public-key! session prvkey)))
         (disconnect! session)
         (eq? res 'success)))))