Add new remctl_set_ccache function to the remctl library API

Add new remctl_set_ccache function to the remctl library API.  Call
this function after remctl_new and before remctl_open to set the
Kerberos credential cache that will be used for client authentication,
overriding KRB5CCNAME.  Be aware that this will normally change the
default credential cache for all other GSS-API operations in this
context or thread, not just for that remctl object, due to GSS-API
limitations.

4 files changed, 60 insertions, 3 deletions

diff --git a/client/api.c b/client/api.c
index 009470f..8a1979b 100644
--- a/client/api.c
+++ b/client/api.c
@@ -11,7 +11,7 @@
  *
  * Written by Russ Allbery <rra@stanford.edu>
  * Based on work by Anton Ushakov
- * Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
+ * Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2011
  *     The Board of Trustees of the Leland Stanford Junior University
  *
  * See LICENSE for licensing terms.
@@ -27,6 +27,7 @@
 
 #include <client/internal.h>
 #include <client/remctl.h>
+#include <util/macros.h>
 
 
 /*
@@ -224,6 +225,45 @@ remctl_new(void)
 
 
 /*
+ * Set the Kerberos credential cache for client connections.  Takes a string
+ * representing the Kerberos credential cache name (the format may vary based
+ * on the underlying Kerberos implementation).  When the GSS-API context is
+ * created for a client connection in a subsequent remctl_open, this will be
+ * set as the Kerberos credential cache.  Returns true on success and false on
+ * failure.
+ *
+ * Callers should be prepared for failure for GSS-API implementations that do
+ * not support setting the Kerberos ticket cache.  A reasonable fallback is to
+ * set the KRB5CCNAME environment variable.
+ *
+ * Be aware that this function sets the Kerberos credential cache globally for
+ * all uses of GSS-API by that process.  The GSS-API does not provide a way of
+ * setting it only for one particular GSS-API context.
+ */
+#ifdef HAVE_GSS_KRB5_CCACHE_NAME
+int
+remctl_set_ccache(struct remctl *r, const char *ccache)
+{
+    OM_uint32 major, minor;
+
+    major = gss_krb5_ccache_name(&minor, ccache, NULL);
+    if (major != GSS_S_COMPLETE) {
+        internal_gssapi_error(r, "cannot set credential cache", major, minor);
+        return 0;
+    }
+    return 1;
+}
+#else /* !HAVE_GSS_KRB5_CCACHE_NAME */
+int
+remctl_set_ccache(struct remctl *r, const char *ccache UNUSED)
+{
+    internal_set_error(r, "setting Kerberos ticket cache not supported");
+    return 0;
+}
+#endif /* !HAVE_GSS_KRB5_CCACHE_NAME */
+
+
+/*
  * Set the source address for client connections.  Takes a string, which may
  * be NULL to use whatever the default source address is.  The string will be
  * parsed as an IPv4 or IPv6 address, and only connections over the
diff --git a/client/libremctl.map b/client/libremctl.map
index 2699a57..bba3513 100644
--- a/client/libremctl.map
+++ b/client/libremctl.map
@@ -9,6 +9,7 @@ REMCTL_1.0 {
         remctl_open;
         remctl_output;
         remctl_result_free;
+        remctl_set_ccache;
         remctl_set_source_ip;
 
     local:
diff --git a/client/libremctl.sym b/client/libremctl.sym
index 29ed04b..5fa1740 100644
--- a/client/libremctl.sym
+++ b/client/libremctl.sym
@@ -7,4 +7,5 @@ remctl_new
 remctl_open
 remctl_output
 remctl_result_free
+remctl_set_ccache
 remctl_set_source_ip
diff --git a/client/remctl.h b/client/remctl.h
index 7b8adaf..b91ecee 100644
--- a/client/remctl.h
+++ b/client/remctl.h
@@ -3,7 +3,7 @@
  *
  * Written by Russ Allbery <rra@stanford.edu>
  * Based on prior work by Anton Ushakov
- * Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008
+ * Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2011
  *     The Board of Trustees of the Leland Stanford Junior University
  *
  * Permission to use, copy, modify, and distribute this software and its
@@ -119,6 +119,22 @@ int remctl_open(struct remctl *, const char *host, unsigned short port,
 void remctl_close(struct remctl *);
 
 /*
+ * Set the Kerberos credential cache for client connections.  This must be
+ * called before remctl_open.  Takes a string representing the Kerberos
+ * credential cache name (the format may vary based on the underlying Kerberos
+ * implementation).  Returns true on success and false on failure.
+ *
+ * Callers should be prepared for failure for GSS-API implementations that do
+ * not support setting the Kerberos ticket cache.  A reasonable fallback is to
+ * set the KRB5CCNAME environment variable.
+ *
+ * Be aware that this function sets the Kerberos credential cache globally for
+ * all uses of GSS-API by that process.  The GSS-API does not provide a way of
+ * setting it only for one particular GSS-API context.
+ */
+int remctl_set_ccache(struct remctl *, const char *);
+
+/*
  * Set the source address for connections.  If remctl_set_source_ip is called
  * before remctl_open, the IP address passed into remctl_set_source_ip will be
  * used as the source address.  This may be NULL to use the default system
@@ -128,7 +144,6 @@ void remctl_close(struct remctl *);
  */
 int remctl_set_source_ip(struct remctl *, const char *);
 
-
 /*
  * Send a complete remote command.  Returns true on success, false on failure.
  * On failure, use remctl_error to get the error.  There are two forms of this