Improve some docs and public symbols

Some unnecessary members are no longer exported, and some docs improved.

async/src/agent.rs

@@ -14,10 +14,9 @@ use sunset_sshwire_derive::*;
 
 use crate::*;
 use sunset::sshwire;
-use sunset::{PubKey, AuthSigMsg, Signature};
+use sunset::{PubKey, AuthSigMsg, Signature,OwnedSig, SignKey};
 use sshwire::{WireError, WireResult, BinString, TextString, Blob, SSHSink, SSHSource, SSHDecode, SSHEncode};
 use sshwire::{SSHEncodeEnum, SSHDecodeEnum};
-use sunset::sign::{OwnedSig, SignKey};
 use sunset::sshnames::*;
 
 // Must be sufficient for the list of all public keys
@@ -105,12 +104,16 @@ impl<'de: 'a, 'a> SSHDecode<'de> for AgentIdentitiesAnswer<'a> {
     }
 }
 
+/// A SSH Agent client
 pub struct AgentClient {
     conn: UnixStream,
     buf: Vec<u8>,
 }
 
 impl AgentClient {
+    /// Create a new client
+    ///
+    /// `path` is a Unix socket to a ssh-agent, such as that from `$SSH_AUTH_SOCK`.
     pub async fn new(path: impl AsRef<Path>) -> Result<Self, std::io::Error> {
         let conn = UnixStream::connect(path).await?;
         Ok(Self {

async/src/cmdline_client.rs

@@ -50,6 +50,9 @@ enum Msg {
     Exited,
 }
 
+/// A commandline client session
+///
+/// This opens a single channel and presents it to the stdin/stdout terminal.
 pub struct CmdlineClient {
     cmd: SessionCommand<String>,
     want_pty: bool,
@@ -101,6 +104,11 @@ impl CmdlineClient {
         }
     }
 
+    /// Splits a `CmdlineClient` into hooks and the runner.
+    ///
+    /// `CmdlineRunner` should be awaited until the session completes.
+    /// `CmdlineHooks` can be used to exit early (and may in future provide
+    /// other functionality).
     pub fn split(&mut self) -> (CmdlineHooks, CmdlineRunner) {
 
         let pty = self.make_pty();
@@ -306,8 +314,10 @@ impl<'a> CmdlineRunner<'a> {
         Ok(())
     }
 
-    /// Runs the `CmdlineClient` session. Requests a shell or command, performs
-    /// channel IO.
+    /// Runs the `CmdlineClient` session to completion.
+    ///
+    /// Performs authentication, requests a shell or command, performs channel IO.
+    /// Will return `Ok` after the session ends normally, or an error.
     pub async fn run(&mut self, cli: &'a SSHClient<'a, CmdlineHooks<'a>>) -> Result<()> {
         // chanio is only set once a channel is opened below
         let chanio = Fuse::terminated();

async/src/lib.rs

@@ -11,11 +11,11 @@ mod agent;
 #[cfg(unix)]
 mod fdio;
 #[cfg(unix)]
-pub use fdio::{stdin, stdout, stderr_out};
+use fdio::{stdin, stdout, stderr_out};
 
-pub use pty::{raw_pty, RawPtyGuard};
+use pty::{raw_pty, RawPtyGuard};
 
-pub use cmdline_client::CmdlineClient;
+pub use cmdline_client::{CmdlineClient, CmdlineRunner, CmdlineHooks};
 
 pub use agent::AgentClient;
 

embassy/demos/common/src/server.rs

@@ -70,18 +70,18 @@ async fn session<S: DemoServer>(socket: &mut TcpSocket<'_>, config: &SunsetMutex
     let src = socket.remote_endpoint().unwrap();
     info!("Connection from {}:{}", src.addr, src.port);
 
-    let s = S::new(init);
+    let demo = S::new(init);
 
     let conf = config.lock().await.clone();
-    let app = ServerApp::new(&s, conf)?;
+    let app = ServerApp::new(&demo, conf)?;
     let app = Mutex::<NoopRawMutex, _>::new(app);
 
     let mut ssh_rxbuf = [0; 2000];
     let mut ssh_txbuf = [0; 2000];
     let serv = SSHServer::new(&mut ssh_rxbuf, &mut ssh_txbuf)?;
     let serv = &serv;
 
-    let session = s.run(serv);
+    let session = demo.run(serv);
 
     let (mut rsock, mut wsock) = socket.split();
 

embassy/src/embassy_channel.rs

@@ -72,7 +72,7 @@ impl<'a, C: CliBehaviour, S: ServBehaviour> Write for ChanIO<'a, C, S> {
 
 // Public wrappers for In only
 
-/// An standard bidirectional SSH channel
+/// A standard bidirectional SSH channel
 #[derive(Debug)]
 pub struct ChanInOut<'a, C: CliBehaviour, S: ServBehaviour>(ChanIO<'a, C, S>);
 

src/auth.rs

@@ -19,8 +19,6 @@ use kex::SessId;
 
 /// The message to be signed in a pubkey authentication message,
 /// RFC4252 Section 7.
-///
-/// The UserauthRequest's signature field None.
 #[derive(Debug)]
 pub struct AuthSigMsg<'a> {
     pub(crate) sess_id: BinString<'a>,
@@ -40,7 +38,7 @@ impl SSHEncode for &AuthSigMsg<'_> {
 }
 
 impl<'a> AuthSigMsg<'a> {
-    pub fn new(u: &'a packets::UserauthRequest<'a>, sess_id: &'a SessId) -> Self {
+    pub(crate) fn new(u: &'a packets::UserauthRequest<'a>, sess_id: &'a SessId) -> Self {
         auth::AuthSigMsg {
             sess_id: BinString(sess_id.as_ref()),
             u,

src/behaviour.rs

@@ -149,6 +149,9 @@ pub trait CliBehaviour {
     ///
     /// `key` is a key previously returned from `next_authkey()`,
     /// it will be one of the `Agent...` variants.
+    ///
+    /// The client can call [`msg.enc()`](crate::sshwire::SSHEncode::enc()) to obtain the
+    /// message to use for agent signing.
     #[allow(unused)]
     async fn agent_sign(&mut self, key: &sign::SignKey, msg: &AuthSigMsg<'_>) -> BhResult<sign::OwnedSig> {
         Err(BhError::Fail)

src/error.rs

@@ -14,6 +14,7 @@ use crate::channel::ChanNum;
 
 // TODO: can we make Snafu not require Debug?
 
+/// The Sunset error type.
 #[non_exhaustive]
 #[derive(Snafu, Debug)]
 #[snafu(context(suffix(false)))]
@@ -204,6 +205,7 @@ impl embedded_io::Error for Error {
     }
 }
 
+/// A Sunset-specific Result type.
 pub type Result<T, E = Error> = core::result::Result<T, E>;
 
 pub trait TrapBug<T> {

src/lib.rs

@@ -13,42 +13,41 @@
 // XXX unused_imports only during dev churn
 #![allow(unused_imports)]
 
-// XXX decide what is public
-pub mod conn;
-pub mod encrypt;
+pub mod sshwire;
+pub mod packets;
+pub mod sshnames;
+pub mod config;
+// exported so that UnusedCli can be used
+pub mod behaviour;
+// exported so that some Channel error variants can be created with .fail().
+// perhaps the ones of interest should be expored separately.
 pub mod error;
-pub mod ident;
-pub mod kex;
-pub mod test;
-pub mod namelist;
+// perhaps don't need this, users could just use getrandom?
 pub mod random;
-pub mod sshnames;
-pub mod sign;
+
+mod conn;
+mod encrypt;
+mod ident;
+mod kex;
+mod test;
+mod namelist;
+mod sign;
 
 mod client;
 mod cliauth;
 
 mod server;
 mod servauth;
 
-// mod bhtokio;
-// mod bhnostd;
-
-pub mod sunsetlog;
+mod sunsetlog;
 mod auth;
 mod channel;
 mod runner;
-// TODO only public for UnusedCli etc.
-pub mod behaviour;
 mod termmodes;
 mod ssh_chapoly;
 mod traffic;
 mod noasync;
 
-pub mod packets;
-pub mod sshwire;
-pub mod config;
-pub mod prelude;
 
 // Application API
 pub use behaviour::{Behaviour, ServBehaviour, CliBehaviour,

src/runner.rs

@@ -22,6 +22,10 @@ use conn::{Conn, Dispatched};
 // was completed. The `ChanHandle` is consumed by `Runner::channel_done()`.
 // Internally sunset uses `ChanNum`, which is just a newtype around u32.
 
+/// A SSH session instance
+///
+/// An application provides network or channel data to `Runner` method calls,
+/// and provides customisation callbacks via `CliBehaviour` or `ServBehaviour`.
 pub struct Runner<'a, C: CliBehaviour, S: ServBehaviour> {
     conn: Conn<C, S>,
 
@@ -222,6 +226,7 @@ impl<'a, C: CliBehaviour, S: ServBehaviour> Runner<'a, C, S> {
     }
 
     /// Send data from this application out the wire.
+    ///
     /// Returns `Ok(len)` consumed, `Err(Error::ChannelEof)` on EOF,
     /// or other errors.
     pub fn channel_send(
@@ -254,6 +259,7 @@ impl<'a, C: CliBehaviour, S: ServBehaviour> Runner<'a, C, S> {
     }
 
     /// Receive data coming from the wire into this application.
+    ///
     /// Returns `Ok(len)` received, `Err(Error::ChannelEof)` on EOF,
     /// or other errors. Ok(0) indicates no data available, ie pending.
     /// TODO: EOF is unimplemented
@@ -286,7 +292,7 @@ impl<'a, C: CliBehaviour, S: ServBehaviour> Runner<'a, C, S> {
         Ok(len)
     }
 
-    /// Receives input data, either dt or normal.
+    /// Receives input data, either normal or extended.
     pub fn channel_input_either(
         &mut self,
         chan: &ChanHandle,
@@ -307,7 +313,7 @@ impl<'a, C: CliBehaviour, S: ServBehaviour> Runner<'a, C, S> {
 
 
     /// Discards any channel input data pending for `chan`, regardless of whether
-    /// normal or `dt`.
+    /// normal or extended.
     pub fn discard_channel_input(&mut self, chan: &ChanHandle) -> Result<()> {
         let len = self.traf_in.discard_channel_input(chan.0);
         let wind_adjust = self.conn.channels.finished_input(chan.0, len)?;
@@ -321,7 +327,7 @@ impl<'a, C: CliBehaviour, S: ServBehaviour> Runner<'a, C, S> {
     /// Indicates when channel data is ready.
     ///
     /// When channel data is ready, returns a tuple
-    /// `Some((channel, dt, len))`
+    /// `Some((channel, data, len))`
     /// `len` is the amount of data ready remaining to read, will always be non-zero.
     /// Note that this returns a `ChanNum` index rather than a `ChanHandle` (which would
     /// be owned by the caller already.
@@ -363,6 +369,7 @@ impl<'a, C: CliBehaviour, S: ServBehaviour> Runner<'a, C, S> {
     }
 
     /// Returns `true` if the channel and `dt` are currently valid for writing.
+    ///
     /// Note that they may not be ready to send output.
     pub fn valid_channel_send(&self, chan: &ChanHandle, dt: ChanData) -> bool {
         self.conn.channels.valid_send(chan.0, dt)

src/sshnames.rs

@@ -80,7 +80,7 @@ pub enum ChanFail {
 
 /// SSH agent message numbers
 ///
-/// [draft-miller-ssh-agent-04](https://tools.ietf.org/html/draft-miller-ssh-agent-04)
+/// [draft-miller-ssh-agent](https://datatracker.ietf.org/doc/html/draft-miller-ssh-agent-11#section-5.1)
 #[allow(non_camel_case_types)]
 #[derive(Debug, Copy, Clone)]
 pub enum AgentMessageNum {
@@ -93,5 +93,5 @@ pub enum AgentMessageNum {
 
 }
 
-/// [draft-miller-ssh-agent-04](https://datatracker.ietf.org/doc/html/draft-miller-ssh-agent-04)
+/// [draft-miller-ssh-agent](https://datatracker.ietf.org/doc/html/draft-miller-ssh-agent-11#section-5.3)
 pub const SSH_AGENT_FLAG_RSA_SHA2_256: u32 = 0x02;