libssh 0.1.0 → 0.2.0

data/ext/libssh_ruby/session.c

@@ -57,6 +57,14 @@ static VALUE m_initialize(VALUE self) {
   return self;
 }
 
+/*
+ * @overload log_verbosity=(verbosity)
+ *  Set the session logging verbosity.
+ *  @since 0.1.0
+ *  @param [Symbol] verbosity +:none+, +:warn+, +:info+, +:debug+, or +:trace+.
+ *  @return [nil]
+ *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_options_set(SSH_OPTIONS_LOG_VERBOSITY)
+ */
 static VALUE m_set_log_verbosity(VALUE self, VALUE verbosity) {
   ID id_verbosity;
   int c_verbosity;
@@ -86,16 +94,301 @@ static VALUE m_set_log_verbosity(VALUE self, VALUE verbosity) {
   return Qnil;
 }
 
+static VALUE set_string_option(VALUE self, enum ssh_options_e type, VALUE str) {
+  SessionHolder *holder;
+  TypedData_Get_Struct(self, SessionHolder, &session_type, holder);
+  RAISE_IF_ERROR(ssh_options_set(holder->session, type, StringValueCStr(str)));
+  return Qnil;
+}
+
+/*
+ * @overload host=(host)
+ *  Set the hostname or IP address to connect to.
+ *  @since 0.1.0
+ *  @param [String] host
+ *  @return [nil]
+ *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_options_set(SSH_OPTIONS_HOST)
+ */
 static VALUE m_set_host(VALUE self, VALUE host) {
+  return set_string_option(self, SSH_OPTIONS_HOST, host);
+}
+
+/*
+ * @overload user=(user)
+ *  Set the username for authentication.
+ *  @since 0.2.0
+ *  @param [String] user
+ *  @return [nil]
+ *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_options_set(SSH_OPTIONS_USER)
+ */
+static VALUE m_set_user(VALUE self, VALUE user) {
+  return set_string_option(self, SSH_OPTIONS_USER, user);
+}
+
+static VALUE set_int_option(VALUE self, enum ssh_options_e type, VALUE i) {
   SessionHolder *holder;
+  int j;
 
+  Check_Type(i, T_FIXNUM);
+  j = FIX2INT(i);
   TypedData_Get_Struct(self, SessionHolder, &session_type, holder);
-  RAISE_IF_ERROR(ssh_options_set(holder->session, SSH_OPTIONS_HOST,
-                                 StringValueCStr(host)));
+  RAISE_IF_ERROR(ssh_options_set(holder->session, type, &j));
+  return Qnil;
+}
+
+/*
+ * @overload port=(port)
+ *  Set the port to connect to.
+ *  @since 0.2.0
+ *  @param [Fixnum] port
+ *  @return [nil]
+ *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_options_set(SSH_OPTIONS_PORT)
+ */
+static VALUE m_set_port(VALUE self, VALUE port) {
+  return set_int_option(self, SSH_OPTIONS_PORT, port);
+}
+
+/*
+ * @overload bindaddr=(addr)
+ *  Set the address to bind the client to.
+ *  @since 0.2.0
+ *  @param [String] addr
+ *  @return [nil]
+ *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_options_set(SSH_OPTIONS_BINDADDR)
+ */
+static VALUE m_set_bindaddr(VALUE self, VALUE addr) {
+  return set_string_option(self, SSH_OPTIONS_BINDADDR, addr);
+}
 
+/*
+ * @overload knownhosts=(path)
+ *  Set the known hosts file name
+ *  @since 0.2.0
+ *  @param [String] path
+ *  @return [nil]
+ *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_options_set(SSH_OPTIONS_KNOWNHOSTS)
+ */
+static VALUE m_set_knownhosts(VALUE self, VALUE path) {
+  return set_string_option(self, SSH_OPTIONS_KNOWNHOSTS, path);
+}
+
+static VALUE set_long_option(VALUE self, enum ssh_options_e type, VALUE i) {
+  SessionHolder *holder;
+  long j;
+
+  Check_Type(i, T_FIXNUM);
+  j = FIX2LONG(i);
+  TypedData_Get_Struct(self, SessionHolder, &session_type, holder);
+  RAISE_IF_ERROR(ssh_options_set(holder->session, type, &j));
   return Qnil;
 }
 
+/*
+ * @overload timeout=(sec)
+ *  Set a timeout for the connection in seconds
+ *  @since 0.2.0
+ *  @param [Fixnum] sec
+ *  @return [nil]
+ *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_options_set(SSH_OPTIONS_TIMEOUT)
+ */
+static VALUE m_set_timeout(VALUE self, VALUE sec) {
+  return set_long_option(self, SSH_OPTIONS_TIMEOUT, sec);
+}
+
+/*
+ * @overload timeout_usec=(usec)
+ *  Set a timeout for the connection in micro seconds
+ *  @since 0.2.0
+ *  @param [Fixnum] usec
+ *  @return [nil]
+ *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_options_set(SSH_OPTIONS_TIMEOUT_USEC)
+ */
+static VALUE m_set_timeout_usec(VALUE self, VALUE usec) {
+  return set_long_option(self, SSH_OPTIONS_TIMEOUT_USEC, usec);
+}
+
+/*
+ * @overload protocol=(protocol)
+ *  Set allowed SSH protocols
+ *  @since 0.2.0
+ *  @param [Array<Integer>] protocol
+ *  @return [nil]
+ *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_options_set(SSH_OPTIONS_SSH1)
+ */
+static VALUE m_set_protocol(VALUE self, VALUE protocols) {
+  SessionHolder *holder;
+  VALUE protocol;
+  int i, ssh1 = 0, ssh2 = 0;
+
+  Check_Type(protocols, T_ARRAY);
+
+  for (i = 0; i < RARRAY_LEN(protocols); i++) {
+    protocol = rb_ary_entry(protocols, i);
+    Check_Type(protocol, T_FIXNUM);
+    switch (FIX2INT(protocol)) {
+      case 1:
+        ssh1 = 1;
+        break;
+      case 2:
+        ssh2 = 1;
+        break;
+      default:
+        rb_raise(rb_eArgError, "protocol should be 1 or 2");
+    }
+  }
+
+  TypedData_Get_Struct(self, SessionHolder, &session_type, holder);
+  RAISE_IF_ERROR(ssh_options_set(holder->session, SSH_OPTIONS_SSH1, &ssh1));
+  RAISE_IF_ERROR(ssh_options_set(holder->session, SSH_OPTIONS_SSH2, &ssh2));
+
+  return Qnil;
+}
+
+static VALUE set_comma_separated_option(VALUE self, enum ssh_options_e type,
+                                        VALUE ary) {
+  VALUE str;
+
+  Check_Type(ary, T_ARRAY);
+  str = rb_ary_join(ary, rb_str_new_cstr(","));
+
+  return set_string_option(self, type, str);
+}
+
+/*
+ * @overload key_exchange=(methods)
+ *  Set the key exchange method to be used
+ *  @since 0.2.0
+ *  @param [Array<String>] methods
+ *  @return [nil]
+ *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_options_set(SSH_OPTIONS_KEY_EXCHANGE)
+ */
+static VALUE m_set_key_exchange(VALUE self, VALUE kex) {
+  return set_comma_separated_option(self, SSH_OPTIONS_KEY_EXCHANGE, kex);
+}
+
+/*
+ * @overload hostkeys=(key_types)
+ *  Set the preferred server host key types
+ *  @since 0.2.0
+ *  @param [Array<String>] key_types
+ *  @return [nil]
+ *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_options_set(SSH_OPTIONS_HOSTKEYS)
+ */
+static VALUE m_set_hostkeys(VALUE self, VALUE hostkeys) {
+  return set_comma_separated_option(self, SSH_OPTIONS_HOSTKEYS, hostkeys);
+}
+
+/*
+ * @overload compression=(algorithm)
+ *  Set the compression to use for both directions communication
+ *  @since 0.2.0
+ *  @param [TrueClass, FalseClass] algorithm
+ *  @param [String] algorithm e.g. "yes", "no", "zlib", "zlib@openssh.com", "none"
+ *  @return [nil]
+ *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_options_set(SSH_OPTIONS_COMPRESSION)
+ */
+static VALUE m_set_compression(VALUE self, VALUE compression) {
+  SessionHolder *holder;
+  char *val;
+  if (compression == Qtrue || compression == Qfalse) {
+    if (compression == Qtrue) {
+      val = "yes";
+    } else {
+      val = "no";
+    }
+
+    TypedData_Get_Struct(self, SessionHolder, &session_type, holder);
+    RAISE_IF_ERROR(
+        ssh_options_set(holder->session, SSH_OPTIONS_COMPRESSION, val));
+
+    return Qnil;
+  } else {
+    return set_string_option(self, SSH_OPTIONS_COMPRESSION, compression);
+  }
+}
+
+/*
+ * @overload compression_level=(level)
+ *  Set the compression level to use for zlib functions
+ *  @since 0.2.0
+ *  @param [Fixnum] level
+ *  @return [nil]
+ *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_options_set(SSH_OPTIONS_COMPRESSION_LEVEL)
+ */
+static VALUE m_set_compression_level(VALUE self, VALUE level) {
+  return set_int_option(self, SSH_OPTIONS_COMPRESSION_LEVEL, level);
+}
+
+/*
+ * @overload stricthostkeycheck=(enable)
+ *  Set the parameter StrictHostKeyChecking to avoid asking about a fingerprint
+ *  @since 0.2.0
+ *  @param [TrueClass, FalseClass] enable
+ *  @return [nil]
+ *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_options_set(SSH_OPTIONS_STRICTHOSTKEYCHECK)
+ */
+static VALUE m_set_stricthostkeycheck(VALUE self, VALUE enable) {
+  return set_int_option(self, SSH_OPTIONS_STRICTHOSTKEYCHECK,
+                        INT2FIX(RTEST(enable) ? 1 : 0));
+}
+
+/*
+ * @overload proxycommand=(command)
+ *  Set the command to be executed in order to connect to server
+ *  @since 0.2.0
+ *  @param [String] command
+ *  @return [nil]
+ *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_options_set(SSH_OPTIONS_PROXYCOMMAND)
+ */
+static VALUE m_set_proxycommand(VALUE self, VALUE proxycommand) {
+  return set_string_option(self, SSH_OPTIONS_PROXYCOMMAND, proxycommand);
+}
+
+/*
+ * @overload gssapi_client_identity=(identity)
+ *  Set the GSSAPI client identity that libssh should expect when connecting to the server
+ *  @since 0.2.0
+ *  @param [String] identity
+ *  @return [nil]
+ *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_options_set(SSH_OPTIONS_GSSAPI_CLIENT_IDENTITY)
+ */
+static VALUE m_set_gssapi_client_identity(VALUE self, VALUE identity) {
+  return set_string_option(self, SSH_OPTIONS_GSSAPI_CLIENT_IDENTITY, identity);
+}
+
+/*
+ * @overload gssapi_server_identity=(identity)
+ *  Set the GSSAPI server identity that libssh should expect when connecting to the server
+ *  @since 0.2.0
+ *  @param [String] identity
+ *  @return [nil]
+ *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_options_set(SSH_OPTIONS_GSSAPI_SERVER_IDENTITY)
+ */
+static VALUE m_set_gssapi_server_identity(VALUE self, VALUE identity) {
+  return set_string_option(self, SSH_OPTIONS_GSSAPI_SERVER_IDENTITY, identity);
+}
+
+/*
+ * @overload gssapi_delegate_credentials=(enable)
+ *  Set whether GSSAPI should delegate credentials to the server
+ *  @since 0.2.0
+ *  @param [FalseClass, TrueClass] enable
+ *  @return [nil]
+ *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_options_set(SSH_OPTIONS_GSSAPI_DELEGATE_CREDENTIALS)
+ */
+static VALUE m_set_gssapi_delegate_credentials(VALUE self, VALUE enable) {
+  return set_int_option(self, SSH_OPTIONS_GSSAPI_DELEGATE_CREDENTIALS,
+                        INT2FIX(RTEST(enable) ? 1 : 0));
+}
+
+/*
+ * @overload parse_config(path = nil)
+ *  Parse the ssh_config file.
+ *  @since 0.1.0
+ *  @param [String, nil] Path to ssh_config. If +nil+, the default ~/.ssh/config will be used.
+ *  @return [Boolean] Parsing the ssh_config was successful or not.
+ *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_options_parse_config
+ */
 static VALUE m_parse_config(int argc, VALUE *argv, VALUE self) {
   SessionHolder *holder;
   VALUE path;
@@ -117,6 +410,14 @@ static VALUE m_parse_config(int argc, VALUE *argv, VALUE self) {
   }
 }
 
+/*
+ * @overload add_identity(path_format)
+ *  Add the identity file name format.
+ *  @since 0.1.0
+ *  @param [String] path_format Format string for identity file.
+ *  @return [nil]
+ *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_options_set(SSH_OPTIONS_ADD_IDENTITY)
+ */
 static VALUE m_add_identity(VALUE self, VALUE path) {
   SessionHolder *holder;
 
@@ -138,6 +439,13 @@ static void *nogvl_connect(void *ptr) {
   return NULL;
 }
 
+/*
+ * @overload connect
+ *  Connect to the SSH server.
+ *  @since 0.1.0
+ *  @return [nil]
+ *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_connect
+ */
 static VALUE m_connect(VALUE self) {
   SessionHolder *holder;
   struct nogvl_session_args args;
@@ -150,6 +458,13 @@ static VALUE m_connect(VALUE self) {
   return Qnil;
 }
 
+/*
+ * @overload server_known
+ *  Check if the server is knonw.
+ *  @since 0.1.0
+ *  @return [Fixnum]
+ *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_is_server_known
+ */
 static VALUE m_server_known(VALUE self) {
   SessionHolder *holder;
   int rc;
@@ -160,6 +475,13 @@ static VALUE m_server_known(VALUE self) {
   return INT2FIX(rc);
 }
 
+/*
+ * @overload userauth_none
+ *  Try to authenticate through then "none" method.
+ *  @since 0.1.0
+ *  @return [Fixnum]
+ *  @see http://api.libssh.org/stable/group__libssh__auth.html ssh_userauth_none
+ */
 static VALUE m_userauth_none(VALUE self) {
   SessionHolder *holder;
   int rc;
@@ -170,6 +492,13 @@ static VALUE m_userauth_none(VALUE self) {
   return INT2FIX(rc);
 }
 
+/*
+ * @overload userauth_list
+ *  Get available authentication methods from the server.
+ *  @since 0.1.0
+ *  @return [Array<Symbol>]
+ *  @see http://api.libssh.org/stable/group__libssh__auth.html ssh_userauth_list
+ */
 static VALUE m_userauth_list(VALUE self) {
   SessionHolder *holder;
   int list;
@@ -207,6 +536,13 @@ static void *nogvl_userauth_publickey_auto(void *ptr) {
   return NULL;
 }
 
+/*
+ * @overload userauth_publickey_auto
+ *  Try to automatically authenticate with public key and "none".
+ *  @since 0.1.0
+ *  @return [Fixnum]
+ *  @see http://api.libssh.org/stable/group__libssh__auth.html ssh_userauth_publickey_auto
+ */
 static VALUE m_userauth_publickey_auto(VALUE self) {
   SessionHolder *holder;
   struct nogvl_session_args args;
@@ -218,6 +554,13 @@ static VALUE m_userauth_publickey_auto(VALUE self) {
   return INT2FIX(args.rc);
 }
 
+/*
+ * @overload get_publickey
+ *  Get the server public key from a session.
+ *  @since 0.1.0
+ *  @return [Key]
+ *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_get_publickey
+ */
 static VALUE m_get_publickey(VALUE self) {
   SessionHolder *holder;
   KeyHolder *key_holder;
@@ -230,6 +573,13 @@ static VALUE m_get_publickey(VALUE self) {
   return key;
 }
 
+/*
+ * @overload write_knownhost
+ *  Write the current server as known in the known_hosts file.
+ *  @since 0.1.0
+ *  @return [nil]
+ *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_write_knownhost
+ */
 static VALUE m_write_knownhost(VALUE self) {
   SessionHolder *holder;
 
@@ -257,9 +607,43 @@ void Init_libssh_session() {
 
   rb_define_method(rb_cLibSSHSession, "initialize",
                    RUBY_METHOD_FUNC(m_initialize), 0);
+
   rb_define_method(rb_cLibSSHSession, "log_verbosity=",
                    RUBY_METHOD_FUNC(m_set_log_verbosity), 1);
   rb_define_method(rb_cLibSSHSession, "host=", RUBY_METHOD_FUNC(m_set_host), 1);
+  rb_define_method(rb_cLibSSHSession, "user=", RUBY_METHOD_FUNC(m_set_user), 1);
+  rb_define_method(rb_cLibSSHSession, "port=", RUBY_METHOD_FUNC(m_set_port), 1);
+  rb_define_method(rb_cLibSSHSession, "bindaddr=",
+                   RUBY_METHOD_FUNC(m_set_bindaddr), 1);
+  rb_define_method(rb_cLibSSHSession, "knownhosts=",
+                   RUBY_METHOD_FUNC(m_set_knownhosts), 1);
+  rb_define_method(rb_cLibSSHSession, "timeout=",
+                   RUBY_METHOD_FUNC(m_set_timeout), 1);
+  rb_define_method(rb_cLibSSHSession, "timeout_usec=",
+                   RUBY_METHOD_FUNC(m_set_timeout_usec), 1);
+  rb_define_method(rb_cLibSSHSession, "protocol=",
+                   RUBY_METHOD_FUNC(m_set_protocol), 1);
+  rb_define_method(rb_cLibSSHSession, "key_exchange=",
+                   RUBY_METHOD_FUNC(m_set_key_exchange), 1);
+  rb_define_method(rb_cLibSSHSession, "hostkeys=",
+                   RUBY_METHOD_FUNC(m_set_hostkeys), 1);
+  rb_define_method(rb_cLibSSHSession, "compression=",
+                   RUBY_METHOD_FUNC(m_set_compression), 1);
+  rb_define_method(rb_cLibSSHSession, "compression_level=",
+                   RUBY_METHOD_FUNC(m_set_compression_level), 1);
+  rb_define_method(rb_cLibSSHSession, "compression_level=",
+                   RUBY_METHOD_FUNC(m_set_compression_level), 1);
+  rb_define_method(rb_cLibSSHSession, "stricthostkeycheck=",
+                   RUBY_METHOD_FUNC(m_set_stricthostkeycheck), 1);
+  rb_define_method(rb_cLibSSHSession, "proxycommand=",
+                   RUBY_METHOD_FUNC(m_set_proxycommand), 1);
+  rb_define_method(rb_cLibSSHSession, "gssapi_client_identity=",
+                   RUBY_METHOD_FUNC(m_set_gssapi_client_identity), 1);
+  rb_define_method(rb_cLibSSHSession, "gssapi_server_identity=",
+                   RUBY_METHOD_FUNC(m_set_gssapi_server_identity), 1);
+  rb_define_method(rb_cLibSSHSession, "gssapi_delegate_credentials=",
+                   RUBY_METHOD_FUNC(m_set_gssapi_delegate_credentials), 1);
+
   rb_define_method(rb_cLibSSHSession, "parse_config",
                    RUBY_METHOD_FUNC(m_parse_config), -1);
   rb_define_method(rb_cLibSSHSession, "add_identity",