WolfSSL
/
wolfssh
mirror of https://github.com/wolfSSL/wolfssh.git
1
0
Fork 0
Code Issues Releases Wiki Activity

Readme Update 

1. Changed "ssh_client" to "ssh". This example is intended to use the
   usual ssh client.
2. Changed a later section header to be different from an earlier one.
   (examples)
3. Added some backticks around some short phrases that are meant to be
   commands or something included in code.
4. Added some links.
5. Update the build directions.
6. A bunch of lines were longer than 80 columns or got really close.
   These were rewrapped to be a little shorter. Whitespace only.
7. Remove non-markdown README file.
pull/385/head
John Safranek 2022-02-04 10:03:44 -08:00
parent 8dfa04776c
commit a813f9c93a
No known key found for this signature in database
GPG Key ID: 8CE817DE0D3CCB4A
2 changed files with 47 additions and 433 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

393
README
View File

@ -1,393 +0,0 @@
WOLFSSH
=======
wolfSSL's Embeddable SSH Server
[wolfSSH Manual](https://www.wolfssl.com/docs/wolfssh-manual/)
dependencies
------------
[wolfSSH](https://www.wolfssl.com/wolfssh/) is dependent on [wolfCrypt](https://www.wolfssl.com/download/).
The simplest configuration of wolfSSL required for wolfSSH is the default build.
$ cd wolfssl
$ ./configure [OPTIONS] --enable-ssh
$ make check
$ sudo make install
On some systems the optional ldconfig command is needed after installing.
To use the key generation function in wolfSSH, wolfSSL will need to be
configured with keygen: `--enable-keygen`.
If the bulk of wolfSSL code isn't desired, wolfSSL can be configured with
the crypto only option: `--enable-cryptonly`.
Additional build options for wolfSSL are located [here](https://www.wolfssl.com/docs/wolfssl-manual/ch2/).
building
--------
From the wolfSSH source directory run:
$ ./autogen.sh
$ ./configure
$ make
$ make check
The `autogen.sh` script only has to be run the first time after cloning the
repository. If you have already run it or are using code from a source
archive, you should skip it.
For building under Windows with Visual Studio, see the file
"ide/winvs/README.md".
NOTE: On resource constrained devices the DEFAULT_WINDOW_SZ may need to be set
to a lower size. It can also be increased in desktop use cases to help with
large file transfers. By default channels are set to handle 16,384 bytes of data
being sent and received. An example of setting a window size for new channels
would be as follows "./configure CPPFLAGS=-DDEFAULT_WINDOW_SZ=16384"
examples
--------
The directory `examples` contains an echoserver that any client should be able
to connect to. From the terminal run:
$ ./examples/echoserver/echoserver -f
The option `-f` enables echo-only mode. From another terminal run:
$ ssh_client jill@localhost -p 22222
When prompted for a password, enter "upthehill". The server will send a canned
banner to the client:
wolfSSH Example Echo Server
Characters typed into the client will be echoed to the screen by the server.
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
-------------
After cloning the repository, be sure to make the testing private keys read-
only for the user, otherwise ssh_client will tell you to do it.
$ chmod 0600 ./keys/gretel-key-rsa.pem ./keys/hansel-key-rsa.pem \
./keys/gretel-key-ecc.pem ./keys/hansel-key-ecc.pem
Authentication against the example echoserver can be done with a password or
public key. To use a password the command line:
$ ssh_client -p 22222 USER@localhost
Where the *USER* and password pairs are:
jill:upthehill
jack:fetchapail
To use public key authentication use the command line:
$ ssh_client -i ./keys/USER-key-TYPE.pem -p 22222 USER@localhost
Where the *USER* can be `gretel` or `hansel`, and *TYPE* is `rsa` or `ecc`.
Keep in mind, the echoserver has several fake accounts in its wsUserAuth
callback function. (jack, jill, hansel, and gretel) When the shell support is
enabled, those fake accounts will not work. They don't exist in the system's
passwd file. The users will authenticate, but the server will err out because
they don't exist in the system. You can add your own username to the password
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.
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 <num> port to accept on, default 22222
-N use non-blocking sockets
-d <string> set the home directory for SFTP connections
-j <file> 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> host to connect to, default 127.0.0.1
-p <num> port to connect on, default 22222
-u <username> username to authenticate as (REQUIRED)
-P <password> password for username, prompted if omitted
-e use sample ecc key for user
-i <filename> filename for the user's private key
-j <filename> 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 <command> 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> host to connect to, default 127.0.0.1
-p <num> port to connect on, default 22222
-u <username> username to authenticate as (REQUIRED)
-P <password> password for username, prompted if omitted
-F <host> host to forward from, default 0.0.0.0
-f <num> host port to forward from (REQUIRED)
-T <host> host to forward to, default to host
-t <num> 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> host to connect to, default 127.0.0.1
-p <num> port to connect on, default 22222
-u <username> username to authenticate as (REQUIRED)
-P <password> password for username, prompted if omitted
-L <from>:<to> copy from local to server
-S <from>:<to> 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> host to connect to, default 127.0.0.1
-p <num> port to connect on, default 22222
-u <username> username to authenticate as (REQUIRED)
-P <password> password for username, prompted if omitted
-d <path> set the default local path
-N use non blocking sockets
-e use ECC user authentication
-l <filename> local filename
-r <filename> 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
single file and recursive directory copy are supported with the default
send and receive callbacks.
To compile wolfSSH with scp support, use the `--enable-scp` build option
or define `WOLFSSL_SCP`:
$ ./configure --enable-scp
$ make
For full API usage and implementation details, please see the wolfSSH User
Manual.
The wolfSSL example server has been set up to accept a single scp request,
and is compiled by default when compiling the wolfSSH library. To start the
example server, run:
$ ./examples/server/server
Standard scp commands can be used on the client side. The following are a
few examples, where `scp` represents the ssh client you are using.
To copy a single file TO the server, using the default example user "jill":
$ scp -P 22222 <local_file> jill@127.0.0.1:<remote_path>
To copy the same single file TO the server, but with timestamp and in
verbose mode:
$ scp -v -p -P 22222 <local_file> jill@127.0.0.1:<remote_path>
To recursively copy a directory TO the server:
$ scp -P 22222 -r <local_dir> jill@127.0.0.1:<remote_dir>
To copy a single file FROM the server to the local client:
$ scp -P 22222 jill@127.0.0.1:<remote_file> <local_path>
To recursively copy a directory FROM the server to the local client:
$ scp -P 22222 -r jill@127.0.0.1:<remote_dir> <local_path>
PORT FORWARDING
===============
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.
To compile wolfSSH with port forwarding support, use the `--enable-fwd` build
option or define `WOLFSSH_FWD`:
$ ./configure --enable-fwd
$ make
For full API usage and implementation details, please see the wolfSSH User
Manual.
The portfwd example tool will create a "direct-tcpip" style channel. These
directions assume you have OpenSSH's server running in the background with
port forwarding enabled. This example forwards the port for the wolfSSL
client to the server as the application. It assumes that all programs are run
on the same machine in different terminals.
src/wolfssl$ ./examples/server/server
src/wolfssh$ ./examples/portfwd/portfwd -p 22 -u <username> \
-f 12345 -t 11111
src/wolfssl$ ./examples/client/client -p 12345
By default, the wolfSSL server listens on port 11111. The client is set to
try to connect to port 12345. The portfwd logs in as user "username", opens
a listener on port 12345 and connects to the server on port 11111. Packets
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:
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.
To compile wolfSSH with SFTP support, use the `--enable-sftp` build option or
define `WOLFSSH_SFTP`:
$ ./configure --enable-sftp
$ make
For full API usage and implementation details, please see the wolfSSH User
Manual.
The SFTP client created is located in the directory examples/sftpclient/ and the
server is ran using the same echoserver as with wolfSSH.
src/wolfssh$ ./examples/sftpclient/wolfsftp
A full list of supported commands can be seen with typeing "help" after a
connection.
wolfSSH sftp> help
Commands :
cd <string> change directory
chmod <mode> <path> change mode
get <remote file> <local file> pulls file(s) from server
ls list current directory
mkdir <dir name> creates new directory on server
put <local file> <remote file> push file(s) to server
pwd list current path
quit exit
rename <old> <new> renames remote file
reget <remote file> <local file> resume pulling file
reput <remote file> <local file> resume pushing file
<crtl + c> interrupt get/put cmd
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
=============
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
authentication callback, or the user authentication callback needs to be
changed to verify the provided password.
To compile wolfSSH with shell support, use the `--enable-shell` build option
or define `WOLFSSH_SHELL`:
$ ./configure --enable-shell
$ make
By default, the echoserver will try to start a shell. To use the echo testing
behavior, give the echoserver the command line option `-f`.
$ ./examples/echoserver/echoserver -f

87
README.md
View File

@ -7,8 +7,10 @@ wolfSSL's Embeddable SSH Server
dependencies
------------
[wolfSSH](https://www.wolfssl.com/wolfssh/) is dependent on [wolfCrypt](https://www.wolfssl.com/download/).
The simplest configuration of wolfSSL required for wolfSSH is the default build.
[wolfSSH](https://www.wolfssl.com/wolfssh/) is dependent on
[wolfCrypt](https://www.wolfssl.com/download/), found as a part of
wolfSSL. The following is the simplest configuration of wolfSSL to
enable wolfSSH.
$ cd wolfssl
$ ./configure [OPTIONS] --enable-ssh
@ -23,7 +25,9 @@ configured with keygen: `--enable-keygen`.
If the bulk of wolfSSL code isn't desired, wolfSSL can be configured with
the crypto only option: `--enable-cryptonly`.
Additional build options for wolfSSL are located [here](https://www.wolfssl.com/docs/wolfssl-manual/ch2/).
Additional build options for wolfSSL are located in
[chapter two](https://www.wolfssl.com/docs/wolfssl-manual/ch2/).
of the wolfSSH manual.
building
--------
@ -31,44 +35,45 @@ building
From the wolfSSH source directory run:
$ ./autogen.sh
$ ./configure
$ ./configure --with-wolfssl=[/usr/local]
$ make
$ make check
The `autogen.sh` script only has to be run the first time after cloning the
repository. If you have already run it or are using code from a source
archive, you should skip it.
The `autogen.sh` script only has to be run the first time after cloning
the repository. If you have already run it or are using code from a
source archive, you should skip it.
For building under Windows with Visual Studio, see the file
"ide/winvs/README.md".
NOTE: On resource constrained devices the DEFAULT_WINDOW_SZ may need to be set
to a lower size. It can also be increased in desktop use cases to help with
large file transfers. By default channels are set to handle 16,384 bytes of data
being sent and received. An example of setting a window size for new channels
would be as follows "./configure CPPFLAGS=-DDEFAULT_WINDOW_SZ=16384"
NOTE: On resource constrained devices the `DEFAULT_WINDOW_SZ` may need
to be set to a lower size. It can also be increased in desktop use cases
to help with large file transfers. By default channels are set to handle
16,384 bytes of data being sent and received. An example of setting a
window size for new channels would be as follows
`./configure CPPFLAGS=-DDEFAULT_WINDOW_SZ=16384`
examples
--------
The directory `examples` contains an echoserver that any client should be able
to connect to. From the terminal run:
The directory `examples` contains an echoserver that any client should
be able to connect to. From the terminal run:
$ ./examples/echoserver/echoserver -f
The option `-f` enables echo-only mode. From another terminal run:
$ ssh_client jill@localhost -p 22222
$ ssh jill@localhost -p 22222
When prompted for a password, enter "upthehill". 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
Characters typed into the client will be echoed to the screen by the server.
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.
Characters typed into the client will be echoed to the screen by the
server. If the characters are echoed twice, the client has local echo
enabled. The echoserver 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:
@ -81,16 +86,16 @@ echoserver:
testing notes
-------------
After cloning the repository, be sure to make the testing private keys read-
only for the user, otherwise ssh_client will tell you to do it.
After cloning the repository, be sure to make the testing private keys
read-only for the user, otherwise `ssh` will tell you to do it.
$ chmod 0600 ./keys/gretel-key-rsa.pem ./keys/hansel-key-rsa.pem \
./keys/gretel-key-ecc.pem ./keys/hansel-key-ecc.pem
Authentication against the example echoserver can be done with a password or
public key. To use a password the command line:
Authentication against the example echoserver can be done with a
password or public key. To use a password the command line:
$ ssh_client -p 22222 USER@localhost
$ ssh -p 22222 USER@localhost
Where the *USER* and password pairs are:
@ -99,24 +104,26 @@ Where the *USER* and password pairs are:
To use public key authentication use the command line:
$ ssh_client -i ./keys/USER-key-TYPE.pem -p 22222 USER@localhost
$ ssh -i ./keys/USER-key-TYPE.pem -p 22222 USER@localhost
Where the *USER* can be `gretel` or `hansel`, and *TYPE* is `rsa` or `ecc`.
Where the *USER* can be `gretel` or `hansel`, and *TYPE* is `rsa` or
`ecc`.
Keep in mind, the echoserver has several fake accounts in its wsUserAuth
callback function. (jack, jill, hansel, and gretel) When the shell support is
enabled, those fake accounts will not work. They don't exist in the system's
passwd file. The users will authenticate, but the server will err out because
they don't exist in the system. You can add your own username to the password
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.
Keep in mind, the echoserver has several fake accounts in its
`wsUserAuth()` callback function. (jack, jill, hansel, and gretel) When
the shell support is enabled, those fake accounts will not work. They
don't exist in the system's _passwd_ file. The users will authenticate,
but the server will err out because they don't exist in the system. You
can add your own username to the password 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.
EXAMPLES
========
EXAMPLE TOOLS
=============
wolfSSH comes packaged with a few example tools for testing purposes and to
demonstrate interoperability with other SSH implementations.
wolfSSH comes packaged with a few example tools for testing purposes
and to demonstrate interoperability with other SSH implementations.
echoserver
@ -124,7 +131,7 @@ 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
typed into it. When enabling [shell support](#shell-support), 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.