From 513313e65e33709c54ed40ce72ba4d7b7b02553a Mon Sep 17 00:00:00 2001 From: John Safranek Date: Thu, 7 Oct 2021 11:19:01 -0700 Subject: [PATCH] Update readme. --- README | 167 +++++++++++++++++++++++++++++++++++++++++++++++++----- README.md | 167 +++++++++++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 306 insertions(+), 28 deletions(-) diff --git a/README b/README index fa04ff15..24e313ce 100644 --- a/README +++ b/README @@ -1,4 +1,4 @@ -wolfssh +WOLFSSH ======= wolfSSL's Embeddable SSH Server @@ -50,13 +50,14 @@ examples The directory `examples` contains an echoserver that any client should be able to connect to. From the terminal run: - $ ./examples/echoserver/echoserver + $ ./examples/echoserver/echoserver -f -From another terminal run: +The option `-f` enables echo-only mode. From another terminal run: - $ ssh_client localhost -p 22222 + $ ssh_client jill@localhost -p 22222 -The server will send a canned banner to the client: +When prompted for a password, enter "upthehill". The server will send a canned +banner to the client: wolfSSH Example Echo Server @@ -65,6 +66,13 @@ If the characters are echoed twice, the client has local echo enabled. The echo server isn't being a proper terminal so the CR/LF translation will not work as expected. +The following control characters will trigger special actions in the +echoserver: + +- CTRL-C: Terminate the connection. +- CTRL-E: Print out some session statistics. +- CTRL-F: Trigger a new key exchange. + testing notes ------------- @@ -100,8 +108,125 @@ or public key list in the echoserver. That account will be logged into a shell started by the echoserver with the privileges of the user running echoserver. -scp support ------------ +EXAMPLES +======== + +wolfSSH comes packaged with a few example tools for testing purposes and to +demonstrate interoperability with other SSH implementations. + + +echoserver +---------- + +The echoserver is the workhorse of wolfSSH. It originally only allowed one +to authenticate one of the canned account and would repeat the characters +typed into it. When enabling shell support, see the later section, it can +spawn a user shell. It will need an actual user name on the machine and an +updated user authentication callback function to validate the credentials. +The echoserver can also handle SCP and SFTP connections. + +The echoserver tool accepts the following command line options: + + -1 exit after a single (one) connection + -e expect ECC public key from client + -E use ECC private key + -f echo input + -p port to accept on, default 22222 + -N use non-blocking sockets + -d set the home directory for SFTP connections + -j load in a public key to accept from peer + + +client +------ + +The client establishes a connection to an SSH server. In its simplest mode, +it sends the string "Hello, wolfSSH!" to the server, prints the response, +and then exits. With the pseudo terminal option, the client will be a real +client. + +The client tool accepts the following command line options: + + -h host to connect to, default 127.0.0.1 + -p port to connect on, default 22222 + -u username to authenticate as (REQUIRED) + -P password for username, prompted if omitted + -e use sample ecc key for user + -i filename for the user's private key + -j filename for the user's public key + -x exit after successful connection without doing + read/write + -N use non-blocking sockets + -t use psuedo terminal + -c executes remote command and pipe stdin/stdout + -a Attempt to use SSH-AGENT + + +portfwd +------- + +The portfwd tool establishes a connection to an SSH server and sets up a +listener for local port forwarding or requests a listener for remote port +forwarding. After a connection, the tool terminates. + +The portfwd tool accepts the following command line options: + + -h host to connect to, default 127.0.0.1 + -p port to connect on, default 22222 + -u username to authenticate as (REQUIRED) + -P password for username, prompted if omitted + -F host to forward from, default 0.0.0.0 + -f host port to forward from (REQUIRED) + -T host to forward to, default to host + -t port to forward to (REQUIRED) + + +scpclient +--------- + +The scpclient, wolfscp, establishes a connection to an SSH server and copies +the specified files from or to the local machine. + +The scpclient tool accepts the following command line options: + + -H host to connect to, default 127.0.0.1 + -p port to connect on, default 22222 + -u username to authenticate as (REQUIRED) + -P password for username, prompted if omitted + -L : copy from local to server + -S : copy from server to local + + +sftpclient +---------- + +The sftpclient, wolfsftp, establishes a connection to an SSH server and +allows directory navigation, getting and putting files, making and removing +directories, etc. + +The sftpclient tool accepts the following command line options: + + -h host to connect to, default 127.0.0.1 + -p port to connect on, default 22222 + -u username to authenticate as (REQUIRED) + -P password for username, prompted if omitted + -d set the default local path + -N use non blocking sockets + -e use ECC user authentication + -l local filename + -r remote filename + -g put local filename as remote filename + -G get remote filename as local filename + + +server +------ + +This tool is a place holder. + + +SCP +=== wolfSSH includes server-side support for scp, which includes support for both copying files 'to' the server, and copying files 'from' the server. Both @@ -148,10 +273,10 @@ To recursively copy a directory FROM the server to the local client: $ scp -P 22222 -r jill@127.0.0.1: -port forwarding support ------------------------ +PORT FORWARDING +=============== -wolfSSH provides client side support for port forwarding. This allows the user +wolfSSH provides support for port forwarding. This allows the user to set up an encrypted tunnel to another server, where the SSH client listens on a socket and forwards connections on that socket to another socket on the server. @@ -184,9 +309,22 @@ are routed back and forth between the client and server. "Hello, wolfSSL!" The source for portfwd provides an example on how to set up and use the port forwarding support in wolfSSH. +The echoserver will handle local and remote port forwarding. To connect with +the ssh tool, using one of the following command lines. You can run either of +the ssh command lines from anywhere: -sftp support ------------- + src/wolfssl$ ./examples/server/server + src/wolfssh$ ./examples/echoserver/echoserver + anywhere 1$ ssh -p 22222 -L 12345:localhost:11111 jill@localhost + anywhere 2$ ssh -p 22222 -R 12345:localhost:11111 jill@localhost + src/wolfssl$ ./examples/client/client -p 12345 + +This will allow port forwarding between the wolfSSL client and server like in +the previous example. + + +SFTP +==== wolfSSH provides server and client side support for SFTP version 3. This allows the user to set up an encrypted connection for managing file systems. @@ -230,8 +368,9 @@ An example of connecting to another system would be src/wolfssh$ ./examples/sftpclient/wolfsftp -p 22 -u user -h 192.168.1.111 -shell support in example echoserver ------------------------------------ +SHELL SUPPORT +============= + wolfSSH's example echoserver can now fork a shell for the user trying to log in. This currently has only been tested on Linux and macOS. The file echoserver.c must be modified to have the user's credentials in the user diff --git a/README.md b/README.md index fa04ff15..24e313ce 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -wolfssh +WOLFSSH ======= wolfSSL's Embeddable SSH Server @@ -50,13 +50,14 @@ examples The directory `examples` contains an echoserver that any client should be able to connect to. From the terminal run: - $ ./examples/echoserver/echoserver + $ ./examples/echoserver/echoserver -f -From another terminal run: +The option `-f` enables echo-only mode. From another terminal run: - $ ssh_client localhost -p 22222 + $ ssh_client jill@localhost -p 22222 -The server will send a canned banner to the client: +When prompted for a password, enter "upthehill". The server will send a canned +banner to the client: wolfSSH Example Echo Server @@ -65,6 +66,13 @@ If the characters are echoed twice, the client has local echo enabled. The echo server isn't being a proper terminal so the CR/LF translation will not work as expected. +The following control characters will trigger special actions in the +echoserver: + +- CTRL-C: Terminate the connection. +- CTRL-E: Print out some session statistics. +- CTRL-F: Trigger a new key exchange. + testing notes ------------- @@ -100,8 +108,125 @@ or public key list in the echoserver. That account will be logged into a shell started by the echoserver with the privileges of the user running echoserver. -scp support ------------ +EXAMPLES +======== + +wolfSSH comes packaged with a few example tools for testing purposes and to +demonstrate interoperability with other SSH implementations. + + +echoserver +---------- + +The echoserver is the workhorse of wolfSSH. It originally only allowed one +to authenticate one of the canned account and would repeat the characters +typed into it. When enabling shell support, see the later section, it can +spawn a user shell. It will need an actual user name on the machine and an +updated user authentication callback function to validate the credentials. +The echoserver can also handle SCP and SFTP connections. + +The echoserver tool accepts the following command line options: + + -1 exit after a single (one) connection + -e expect ECC public key from client + -E use ECC private key + -f echo input + -p port to accept on, default 22222 + -N use non-blocking sockets + -d set the home directory for SFTP connections + -j load in a public key to accept from peer + + +client +------ + +The client establishes a connection to an SSH server. In its simplest mode, +it sends the string "Hello, wolfSSH!" to the server, prints the response, +and then exits. With the pseudo terminal option, the client will be a real +client. + +The client tool accepts the following command line options: + + -h host to connect to, default 127.0.0.1 + -p port to connect on, default 22222 + -u username to authenticate as (REQUIRED) + -P password for username, prompted if omitted + -e use sample ecc key for user + -i filename for the user's private key + -j filename for the user's public key + -x exit after successful connection without doing + read/write + -N use non-blocking sockets + -t use psuedo terminal + -c executes remote command and pipe stdin/stdout + -a Attempt to use SSH-AGENT + + +portfwd +------- + +The portfwd tool establishes a connection to an SSH server and sets up a +listener for local port forwarding or requests a listener for remote port +forwarding. After a connection, the tool terminates. + +The portfwd tool accepts the following command line options: + + -h host to connect to, default 127.0.0.1 + -p port to connect on, default 22222 + -u username to authenticate as (REQUIRED) + -P password for username, prompted if omitted + -F host to forward from, default 0.0.0.0 + -f host port to forward from (REQUIRED) + -T host to forward to, default to host + -t port to forward to (REQUIRED) + + +scpclient +--------- + +The scpclient, wolfscp, establishes a connection to an SSH server and copies +the specified files from or to the local machine. + +The scpclient tool accepts the following command line options: + + -H host to connect to, default 127.0.0.1 + -p port to connect on, default 22222 + -u username to authenticate as (REQUIRED) + -P password for username, prompted if omitted + -L : copy from local to server + -S : copy from server to local + + +sftpclient +---------- + +The sftpclient, wolfsftp, establishes a connection to an SSH server and +allows directory navigation, getting and putting files, making and removing +directories, etc. + +The sftpclient tool accepts the following command line options: + + -h host to connect to, default 127.0.0.1 + -p port to connect on, default 22222 + -u username to authenticate as (REQUIRED) + -P password for username, prompted if omitted + -d set the default local path + -N use non blocking sockets + -e use ECC user authentication + -l local filename + -r remote filename + -g put local filename as remote filename + -G get remote filename as local filename + + +server +------ + +This tool is a place holder. + + +SCP +=== wolfSSH includes server-side support for scp, which includes support for both copying files 'to' the server, and copying files 'from' the server. Both @@ -148,10 +273,10 @@ To recursively copy a directory FROM the server to the local client: $ scp -P 22222 -r jill@127.0.0.1: -port forwarding support ------------------------ +PORT FORWARDING +=============== -wolfSSH provides client side support for port forwarding. This allows the user +wolfSSH provides support for port forwarding. This allows the user to set up an encrypted tunnel to another server, where the SSH client listens on a socket and forwards connections on that socket to another socket on the server. @@ -184,9 +309,22 @@ are routed back and forth between the client and server. "Hello, wolfSSL!" The source for portfwd provides an example on how to set up and use the port forwarding support in wolfSSH. +The echoserver will handle local and remote port forwarding. To connect with +the ssh tool, using one of the following command lines. You can run either of +the ssh command lines from anywhere: -sftp support ------------- + src/wolfssl$ ./examples/server/server + src/wolfssh$ ./examples/echoserver/echoserver + anywhere 1$ ssh -p 22222 -L 12345:localhost:11111 jill@localhost + anywhere 2$ ssh -p 22222 -R 12345:localhost:11111 jill@localhost + src/wolfssl$ ./examples/client/client -p 12345 + +This will allow port forwarding between the wolfSSL client and server like in +the previous example. + + +SFTP +==== wolfSSH provides server and client side support for SFTP version 3. This allows the user to set up an encrypted connection for managing file systems. @@ -230,8 +368,9 @@ An example of connecting to another system would be src/wolfssh$ ./examples/sftpclient/wolfsftp -p 22 -u user -h 192.168.1.111 -shell support in example echoserver ------------------------------------ +SHELL SUPPORT +============= + wolfSSH's example echoserver can now fork a shell for the user trying to log in. This currently has only been tested on Linux and macOS. The file echoserver.c must be modified to have the user's credentials in the user