Dropbear - Markdown documentation files

Converted some regular text file into Markdown format. Better rendering
on github, and still very much readable by humans in a text editor.

Fixed links. Tried to use consistent formatting throughout.

Didn't add a .md extension, so they can be diff-ed. Otherwise git thinks
they are new files altogether. Will add the extension on the next commit.

tjk :)

6 files changed, 176 insertions, 253 deletions

diff --git a/DEVELOPING.md b/DEVELOPING.md
index 1846b15..65ae9ae 100644
--- a/DEVELOPING.md
+++ b/DEVELOPING.md
@@ -1,75 +1,49 @@
-# Developer Notes
+## Developer Notes
 
-## Building
+#### Building
 
-See [INSTALL](INSTALL) for build instructions. 
-[SMALL](SMALL) has hints for building smaller binaries, also see comments
-in default_options.h.
+See [INSTALL.md](INSTALL.md) for build instructions.
+[SMALL.md](SMALL.md) has hints for building smaller binaries, also see comments in [default_options.h](./src/default_options.h).
 
-## Debug printing
+To be able to debug add `-g` compiler option to the `CFLAGS` environment variable. This will generate debug symbols.
+```
+export CFLAGS="$CFLAGS -g"
+```
 
-Set `#define DEBUG_TRACE 1` in localoptions.h to enable a `-v` option
-for dropbear and dbclient. That prints various details of the session. For
-development running `dropbear -F -E` is useful to run in the foreground. You
-can set `#define DEBUG_NOFORK 1` to make dropbear a one-shot server, easy to 
-run under a debugger.
+#### Debug printing
 
-## Random sources
+Set `#define DEBUG_TRACE 1` in [localoptions.h](./src/localoptions.h) to enable a `-v` option for dropbear and dbclient. That prints various details of the session. For development running `dropbear -F -E` is useful to run in the foreground. You can set `#define DEBUG_NOFORK 1` to make dropbear a one-shot server, easy to run under a debugger.
 
-Most cryptography requires a good random entropy source, both to generate secret
-keys and in the course of a session. Dropbear uses the Linux kernel's
-`getrandom()` syscall to ensure that the system RNG has been initialised before
-using it. On some systems there is insufficient entropy gathered during early
-boot - generating hostkeys then will block for some amount of time. 
-Dropbear has a `-R` option to generate hostkeys upon the first connection 
-as required - that will allow the system more time to gather entropy.
+#### Random sources
 
-## Algorithms
+Most cryptography requires a good random entropy source, both to generate secret keys and in the course of a session. Dropbear uses the Linux kernel's `getrandom()` syscall to ensure that the system RNG has been initialised before using it. On some systems there is insufficient entropy gathered during early boot - generating hostkeys then will block for some amount of time. Dropbear has a `-R` option to generate hostkeys upon the first connection as required - that will allow the system more time to gather entropy.
 
-Default algorithm lists are specified in [common-algo.c](common-algo.c).
-They are in priority order, the client's first matching choice is used
-(see rfc4253). 
-Dropbear client has `-c` and `-m` arguments to choose which are enabled at
-runtime (doesn't work for server as of June 2020).
+#### Algorithms
 
-Enabling/disabling algorithms is done in [localoptions.h](localoptions.h),
-see [default_options.h](default_options.h).
+Default algorithm lists are specified in [common-algo.c](./src/common-algo.c). They are in priority order, the client's first matching choice is used (see [rfc4253](https://www.rfc-editor.org/rfc/rfc4253.html)). Dropbear client has `-c` and `-m` arguments to choose which are enabled at runtime (doesn't work for server as of June 2020).
 
-## Style
+Enabling/disabling algorithms is done in [localoptions.h](./src/localoptions.h), see [default_options.h](./src/default_options.h).
 
-Source code is indented with tabs, width set to 4 (though width shouldn't
-matter much). Braces are on the same line as functions/loops/if - try
-to keep consistency with existing code.
+#### Style
 
-All `if` statements should have braces, no exceptions.
+Source code is indented with tabs, width set to 4 (though width shouldn't matter much). Braces are on the same line as functions/loops/if - try to keep consistency with existing code.
 
-Avoid using pointer arithmetic, instead the functions in
-[buffer.h](buffer.h) should be used.
+All `if` statements should have braces, no exceptions.
 
-Some Dropbear platforms have old compilers.
-Variable declarations must be at the top of a scope and
-comments must be `/* */` rather than `//`.
+Avoid using pointer arithmetic, instead the functions in [buffer.h](./src/buffer.h) should be used.
 
-Pointer variables should be initialised to NULL - it can reduce the
-severity of bugs.
+Some Dropbear platforms have old compilers. Variable declarations must be at the top of a scope and comments must be `/* */` rather than `//`.
 
-## Third party code
+Pointer variables should be initialised to NULL - it can reduce the severity of bugs.
 
-Libtomcrypt and libtommath are periodically synced from upstream, so
-avoid making changes to that code which will need to be maintained.
-Improvements can be sent upstream to the libtom project.
+#### Third party code
 
-## Non-root user
+Libtomcrypt and libtommath are periodically synced from upstream, so avoid making changes to that code which will need to be maintained. Improvements can be sent upstream to the libtom project.
 
-Dropbear server will run fine as a non-root user, allowing logins only for 
-that user. Password authentication probably won't work (can't read shadow 
-passwords). You will need to create hostkeys that are readable.
+#### Non-root user
 
-## Connection setup 
+Dropbear server will run fine as a non-root user, allowing logins only for that user. Password authentication probably won't work (can't read shadow passwords). You will need to create hostkeys that are readable.
 
-Dropbear implements first_kex_packet_follows to reduce 
-handshake latency (rfc 4253 7.1). Some less common implementations don't 
-handle that, it can be a cause of problems connecting. Note also that
-Dropbear may send several ssh packets within a single TCP packet - it's just a 
-stream.
+#### Connection setup
 
+Dropbear implements `first_kex_packet_follows` to reduce handshake latency (rfc 4253 7.1)[https://www.rfc-editor.org/rfc/rfc4253.html#section-7.1]. Some less common implementations don't handle that - it can be a cause of problems connecting. Note also that Dropbear may send several ssh packets within a single TCP packet - it's just a stream.
diff --git a/FUZZER-NOTES.md b/FUZZER-NOTES.md
index 4967eba..078fbc5 100644
--- a/FUZZER-NOTES.md
+++ b/FUZZER-NOTES.md
@@ -1,77 +1,45 @@
-# Fuzzing Dropbear
+## Fuzzing Dropbear
 
-Dropbear is process-per-session so it assumes calling `dropbear_exit()`
-is fine at any point to clean up. This makes fuzzing a bit trickier. 
-A few pieces of wrapping infrastructure are used to work around this.
+Dropbear is process-per-session so it assumes calling `dropbear_exit()` is fine at any point to clean up. This makes fuzzing a bit trickier. A few pieces of wrapping infrastructure are used to work around this.
 
-The [libfuzzer](http://llvm.org/docs/LibFuzzer.html#fuzz-target) harness
-expects a long running process to continually run a test function with 
-a string of crafted input. That process should not leak resources or exit.
+The [libfuzzer](http://llvm.org/docs/LibFuzzer.html#fuzz-target) harness expects a long running process to continually run a test function with a string of crafted input. That process should not leak resources or exit.
 
-## longjmp
+#### longjmp
 
-When dropbear runs in fuzz mode it sets up a 
-[`setjmp()`](http://man7.org/linux/man-pages/man3/setjmp.3.html) target prior 
-to launching the code to be fuzzed, and then [`dropbear_exit()`](dbutil.c#L125)
-calls `longjmp()` back there. This avoids exiting though it doesn't free 
-memory or other resources.
+When dropbear runs in fuzz mode it sets up a [`setjmp()`](http://man7.org/linux/man-pages/man3/setjmp.3.html) target prior to launching the code to be fuzzed, and then [`dropbear_exit()`](./src/dbutil.c#L125) calls `longjmp()` back there. This avoids exiting though it doesn't free memory or other resources.
 
-## malloc Wrapper
+#### malloc Wrapper
 
-Dropbear normally uses a [`m_malloc()`](dbmalloc.c) function that is the same as `malloc()` but
-exits if allocation fails. In fuzzing mode this is replaced with a tracking allocator
-that stores all allocations in a linked list. After the `longjmp()` occurs the fuzzer target
-calls [`m_malloc_free_epoch(1, 1)`](dbmalloc.c) to clean up any unreleased memory.
+Dropbear normally uses a [`m_malloc()`](./src/dbmalloc.c) function that is the same as `malloc()` but exits if allocation fails. In fuzzing mode this is replaced with a tracking allocator that stores all allocations in a linked list. After the `longjmp()` occurs the fuzzer target calls [`m_malloc_free_epoch(1, 1)`](./src/dbmalloc.c#L80) to clean up any unreleased memory.
 
-If the fuzz target runs to completion it calls `m_malloc_free_epoch(1, 0)` which will reset 
-the tracked allocations but will not free memory - that allows libfuzzer's leak checking
-to detect leaks in normal operation.
+If the fuzz target runs to completion it calls `m_malloc_free_epoch(1, 0)` which will reset the tracked allocations but will not free memory - that allows libfuzzer's leak checking to detect leaks in normal operation.
 
-## File Descriptor Input
+#### File Descriptor Input
 
-As a network process Dropbear reads and writes from a socket. The wrappers for
-`read()`/`write()`/`select()` in [fuzz-wrapfd.c](fuzz-wrapfd.c) will read from the
-fuzzer input that has been set up with `wrapfd_add()`. `write()` output is
-currently discarded.
-These also test error paths such as EINTR and short reads with certain probabilities.
+As a network process Dropbear reads and writes from a socket. The wrappers for `read()`/`write()`/`select()` in [fuzz-wrapfd.c](./fuzz/fuzz-wrapfd.c) will read from the fuzzer input that has been set up with `wrapfd_add()`. `write()` output is currently discarded. These also test error paths such as EINTR and short reads with certain probabilities.
 
-This allows running the entire dropbear server process with network input provided by the
-fuzzer, without many modifications to the main code. At the time of writing this 
-only runs the pre-authentication stages, though post-authentication could be run similarly.
+This allows running the entire dropbear server process with network input provided by the fuzzer, without many modifications to the main code. At the time of writing this only runs the pre-authentication stages, though post-authentication could be run similarly.
 
-## Encryption and Randomness
+#### Encryption and Randomness
 
-When running in fuzzing mode Dropbear uses a [fixed seed](dbrandom.c#L185)
-every time so that failures can be reproduced. 
+When running in fuzzing mode Dropbear uses a [fixed seed](./src/dbrandom.c#L185) every time so that failures can be reproduced.
 
-Since the fuzzer cannot generate valid encrypted input the packet decryption and
-message authentication calls are disabled, see [packet.c](packet.c). 
-MAC failures are set to occur with a low probability to test that error path.
+Since the fuzzer cannot generate valid encrypted input the packet decryption and message authentication calls are disabled, see [packet.c](./src/packet.c). MAC failures are set to occur with a low probability to test that error path.
 
-## Fuzzers
+#### Fuzzers
 
-Current fuzzers are
+Current fuzzers are:
 
-- [fuzzer-preauth](fuzzer-preauth.c) - the fuzzer input is treated as a stream of session input. This will
-  test key exchange, packet ordering, authentication attempts etc.
+* [fuzzer-preauth](./fuzz/fuzzer-preauth.c) - the fuzzer input is treated as a stream of session input. This will test key exchange, packet ordering, authentication attempts etc.
 
-- [fuzzer-preauth_nomaths](fuzzer-preauth_nomaths.c) - the same as fuzzer-preauth but with asymmetric crypto
-  routines replaced with dummies for faster runtime. corpora are shared 
-  between fuzzers by [oss-fuzz](https://github.com/google/oss-fuzz) so this 
-  will help fuzzer-preauth too.
+* [fuzzer-preauth_nomaths](./fuzz/fuzzer-preauth_nomaths.c) - the same as fuzzer-preauth but with asymmetric crypto routines replaced with dummies for faster runtime. corpora are shared between fuzzers by [oss-fuzz](https://github.com/google/oss-fuzz) so this will help fuzzer-preauth too.
 
-- [fuzzer-verify](fuzzer-verify.c) - read a key and signature from fuzzer input and verify that signature. 
-  It would not be expected to pass, though some keys with bad parameters are 
-  able to validate with a trivial signature - extra checks are added for that.
+* [fuzzer-verify](./fuzz/fuzzer-verify.c) - read a key and signature from fuzzer input and verify that signature. It would not be expected to pass, though some keys with bad parameters are able to validate with a trivial signature - extra checks are added for that.
 
-- [fuzzer-pubkey](fuzzer-pubkey.c) - test parsing of an `authorized_keys` line.
+* [fuzzer-pubkey](./fuzz/fuzzer-pubkey.c) - test parsing of an `authorized_keys` line.
 
-- [fuzzer-kexdh](fuzzer-kexdh.c) - test Diffie-Hellman key exchange where the fuzz input is the 
-  ephemeral public key that would be received over the network. This is testing `mp_expt_mod()`
-  and and other libtommath routines.
+* [fuzzer-kexdh](./fuzz/fuzzer-kexdh.c) - test Diffie-Hellman key exchange where the fuzz input is the ephemeral public key that would be received over the network. This is testing `mp_expt_mod()` and and other libtommath routines.
 
-- [fuzzer-kexecdh](fuzzer-kexecdh.c) - test Elliptic Curve Diffie-Hellman key exchange like fuzzer-kexdh.
-  This is testing libtommath ECC routines.
+* [fuzzer-kexecdh](./fuzz/fuzzer-kexecdh.c) - test Elliptic Curve Diffie-Hellman key exchange like fuzzer-kexdh. This is testing libtommath ECC routines.
 
-- [fuzzer-kexcurve25519](fuzzer-kexcurve25519.c) - test Curve25519 Elliptic Curve Diffie-Hellman key exchange
-  like fuzzer-kexecdh. This is testing `dropbear_curve25519_scalarmult()` and other libtommath routines.
+* [fuzzer-kexcurve25519](./fuzz/fuzzer-kexcurve25519.c) - test Curve25519 Elliptic Curve Diffie-Hellman key exchange like fuzzer-kexecdh. This is testing `dropbear_curve25519_scalarmult()` and other libtommath routines.
diff --git a/INSTALL b/INSTALL
index 60eb707..ec53e3b 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,93 +1,77 @@
-Basic Dropbear build instructions:
+## Basic Dropbear Build Instructions
 
-- Edit localoptions.h to set which features you want. Available options
-  are described in default_options.h, these will be overridden by
-  anything set in localoptions.h
-  localoptions.h should be located in the build directory if you are
-  building out of tree.
+Edit [localoptions.h](./src/localoptions.h) to set which features you want. Available options are described in default_options.h, these will be overridden by anything set in [localoptions.h](./src/localoptions.h) should be located in the build directory if you are building out of tree.
+Note that the file is not tracked ([*.gitignore*](.gitignore)-d) and you may need to create it.
 
-- Configure for your system:
-  ./configure     (optionally with --disable-zlib or --disable-syslog,
-                  or --help for other options)
+#### Configure for your system
+```
+./configure
+```
+Optionally with `--disable-zlib` or `--disable-syslog`.
+Or `--help` for other options.
 
-  (you'll need to first run "autoconf; autoheader" if you edit configure.ac)
+You'll need to first run `autoconf; autoheader` if you edit `configure.ac`.
 
-- Compile:
+#### Compile:
 
-  make PROGRAMS="dropbear dbclient dropbearkey dropbearconvert scp"
+```
+make PROGRAMS="dropbear dbclient dropbearkey dropbearconvert scp"
+```
 
-- Optionally install, or copy the binaries another way
+Optionally install, or copy the binaries another way:
 
-  make install (/usr/local/bin is usual default):
+```
+make install
+```
+`/usr/local/bin` is usual default.
 
-  or
+or
 
-  make PROGRAMS="dropbear dbclient dropbearkey dropbearconvert scp" install
+```
+make PROGRAMS="dropbear dbclient dropbearkey dropbearconvert scp" install
+```
 
-(you can leave items out of the PROGRAMS list to avoid compiling them. If you
-recompile after changing the PROGRAMS list, you *MUST* "make clean" before
-recompiling - bad things will happen otherwise)
+You can leave items out of the `PROGRAMS` list to avoid compiling them. If you recompile after changing the `PROGRAMS` list, you **MUST** `make clean` before recompiling - bad things will happen otherwise.
 
-DEVELOPING.md has some notes on other developer topics, including debugging.
+[DEVELOPING.md](DEVELOPING.md) has some notes on other developer topics, including debugging.
 
-See MULTI for instructions on making all-in-one binaries.
+See [MULTI.md](MULTI.md) for instructions on making all-in-one binaries.
 
-If you want to compile statically use ./configure --enable-static
+If you want to compile statically use
+```
+./configure --enable-static
+```
 
-By default Dropbear adds various build flags that improve robustness 
-against programming bugs (good for security). If these cause problems
-they can be disabled with ./configure --disable-harden
+By default Dropbear adds various build flags that improve robustness against programming bugs (good for security). If these cause problems they can be disabled with `./configure --disable-harden`.
 
-Binaries can be stripped with "make strip"
+Binaries can be stripped with `make strip`.
 
-============================================================================
+> **Note**
+> If you're compiling for a 386-class CPU, you will probably need to add CFLAGS=-DLTC_NO_BSWAP so that libtomcrypt doesn't use 486+ instructions.
 
-If you're compiling for a 386-class CPU, you will probably need to add
-CFLAGS=-DLTC_NO_BSWAP so that libtomcrypt doesn't use 486+ instructions.
+## Compiling with uClibc
 
-============================================================================
+Firstly, make sure you have at least uclibc 0.9.17, as `getusershell()` in prior versions is broken. Also note that you may get strange issues if your uClibc headers don't match the library you are running with, ie the headers might say that shadow password support exists, but the libraries don't have it.
 
-Compiling with uClibc:
+Compiling for uClibc should be the same as normal, just set CC to the magic uClibc toolchain compiler (ie `export CC=i386-uclibc-gcc` or whatever). You can use `make STATIC=1` to make statically linked binaries, and it is advisable to strip the binaries too. If you're looking to make a small binary, you should remove unneeded ciphers and algorithms, by editing [localoptions.h](./src/localoptions.h).
 
-Firstly, make sure you have at least uclibc 0.9.17, as getusershell() in prior
-versions is broken. Also note that you may get strange issues if your uClibc
-headers don't match the library you are running with, ie the headers might
-say that shadow password support exists, but the libraries don't have it.
-
-Compiling for uClibc should be the same as normal, just set CC to the magic
-uClibc toolchain compiler (ie export CC=i386-uclibc-gcc or whatever).
-You can use "make STATIC=1" to make statically linked binaries, and it is
-advisable to strip the binaries too. If you're looking to make a small binary,
-you should remove unneeded ciphers and algorithms, by editing localoptions.h
-
-It is possible to compile zlib in, by copying zlib.h and zconf.h into a
-subdirectory (ie zlibincludes), and 
+It is possible to compile zlib in, by copying zlib.h and zconf.h into a subdirectory (ie zlibincludes), and
 
+```
 export CFLAGS="-Izlibincludes -I../zlibincludes"
 export LDFLAGS=/usr/lib/libz.a
+```
+before `./configure` and `make`.
 
-before ./configure and make.
-
-If you disable zlib, you must explicitly disable compression for the client -
-OpenSSH is possibly buggy in this regard, it seems you need to disable it
-globally in ~/.ssh/config, not just in the host entry in that file.
+If you disable zlib, you must explicitly disable compression for the client - OpenSSH is possibly buggy in this regard, it seems you need to disable it globally in *~/.ssh/config*, not just in the host entry in that file.
 
-You may want to manually disable lastlog recording when using uClibc, configure
-with --disable-lastlog.
+You may want to manually disable lastlog recording when using uClibc, configure with `--disable-lastlog`.
 
-One common problem is pty allocation. There are a number of types of pty
-allocation which can be used -- if they work properly, the end result is the
-same for each type. Running configure should detect the best type to use
-automatically, however for some systems, this may be incorrect. Some
+One common problem is pty allocation. There are a number of types of pty allocation which can be used -- if they work properly, the end result is the same for each type. Running configure should detect the best type to use automatically, however for some systems, this may be incorrect. Some
 things to note:
 
-    If your system expects /dev/pts to be mounted (this is a uClibc option),
-	make sure that it is.
+* If your system expects */dev/pts* to be mounted (this is a uClibc option), make sure that it is.
 
-	Make sure that your libc headers match the library version you are using.
+* Make sure that your libc headers match the library version you are using.
 
-	If openpty() is being used (HAVE_OPENPTY defined in config.h) and it fails,
-	you can try compiling with --disable-openpty. You will probably then need
-	to create all the /dev/pty?? and /dev/tty?? devices, which can be
-	problematic for devfs. In general, openpty() is the best way to allocate
-	PTYs, so it's best to try and get it working.
+* If `openpty()` is being used (`HAVE_OPENPTY` defined in *config.h*) and it fails, you can try compiling with `--disable-openpty`. You will probably then need to create all the */dev/pty??* and */dev/tty??* devices, which can be problematic for devfs. In general, `openpty()` is the best way to allocate PTYs, so it's best to try and get it working.
diff --git a/MULTI b/MULTI
index 606f815..01f9bc1 100644
--- a/MULTI
+++ b/MULTI
@@ -1,22 +1,23 @@
-Multi-binary compilation
-========================
+## Multi-Binary Compilation
 
-To compile for systems without much space (floppy distributions etc), you
-can create a single binary. This will save disk space by avoiding repeated
-code between the various parts.
-If you are familiar with "busybox", it's the same principle.
+To compile for systems without much space (floppy distributions etc), you can create a single binary. This will save disk space by avoiding repeated code between the various parts. If you are familiar with "busybox", it's the same principle.
 
-To compile the multi-binary, first "make clean" (if you've compiled
-previously), then
+To compile the multi-binary, first `make clean` (if you've compiled previously), then
 
+```
 make PROGRAMS="programs you want here" MULTI=1
+```
 
 To use the binary, symlink it from the desired executable:
 
+```
 ln -s dropbearmulti dropbear
 ln -s dropbearmulti dbclient
-etc
+```
+etc.
 
-then execute as normal:
+Then execute as normal:
 
+```
 ./dropbear <options here>
+```
diff --git a/README b/README
index bdc99dc..4b3f23e 100644
--- a/README
+++ b/README
@@ -1,81 +1,74 @@
-This is Dropbear, a smallish SSH server and client.
+## Dropbear SSH
+A smallish SSH server and client
 https://matt.ucc.asn.au/dropbear/dropbear.html
 
-INSTALL has compilation instructions.
+[INSTALL.md](INSTALL.md) has compilation instructions.
 
-MULTI has instructions on making a multi-purpose binary (ie a single binary
-which performs multiple tasks, to save disk space)
+[MULTI.md](MULTI.md) has instructions on making a multi-purpose binary (ie a single binary which performs multiple tasks, to save disk space).
 
-SMALL has some tips on creating small binaries.
+[SMALL.md](SMALL.md) has some tips on creating small binaries.
 
-A mirror of the Dropbear website and tarballs is available at https://dropbear.nl/mirror/
+A mirror of the Dropbear website and tarballs is available at https://dropbear.nl/mirror/.
 
-Please contact me if you have any questions/bugs found/features/ideas/comments etc :)
-There is also a mailing list http://lists.ucc.gu.uwa.edu.au/mailman/listinfo/dropbear
+Please contact me if you have any questions/bugs found/features/ideas/comments etc :). There is also a mailing list at http://lists.ucc.gu.uwa.edu.au/mailman/listinfo/dropbear
 
 Matt Johnston
 matt@ucc.asn.au
 
 
-In the absence of detailed documentation, some notes follow:
-============================================================================
+### In the absence of detailed documentation, some notes follow
 
-Server public key auth:
+----
+#### Server public key auth
 
-You can use ~/.ssh/authorized_keys in the same way as with OpenSSH, just put
-the key entries in that file. They should be of the form:
+You can use *~/.ssh/authorized_keys* in the same way as with OpenSSH, just put the key entries in that file. They should be of the form:
 
-ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAIEAwVa6M6cGVmUcLl2cFzkxEoJd06Ub4bVDsYrWvXhvUV+ZAM9uGuewZBDoAqNKJxoIn0Hyd0Nk/yU99UVv6NWV/5YSHtnf35LKds56j7cuzoQpFIdjNwdxAN0PCET/MG8qyskG/2IE2DPNIaJ3Wy+Ws4IZEgdJgPlTYUBWWtCWOGc= someone@hostname
+```
+ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAIEAwVa6M6cGVmUcLl2cFzkxEoJd06Ub4bVDsYrWvXhvUV+ZAM9uGuewZBDoAqNKJxoIn0Hyd0NkyU99UVv6NWV/5YSHtnf35LKds56j7cuzoQpFIdjNwdxAN0PCET/MG8qyskG/2IE2DPNIaJ3Wy+Ws4IZEgdJgPlTYUBWWtCWOGc= someone@hostname
+```
 
-You must make sure that ~/.ssh, and the key file, are only writable by the
-user. Beware of editors that split the key into multiple lines.
+You must make sure that *~/.ssh*, and the key file, are only writable by the user. Beware of editors that split the key into multiple lines.
 
 Dropbear supports some options for authorized_keys entries, see the manpage.
 
-============================================================================
+----
+#### Client public key auth
 
-Client public key auth:
+Dropbear can do public key auth as a client, but you will have to convert OpenSSH style keys to Dropbear format, or use dropbearkey to create them.
 
-Dropbear can do public key auth as a client, but you will have to convert
-OpenSSH style keys to Dropbear format, or use dropbearkey to create them.
-
-If you have an OpenSSH-style private key ~/.ssh/id_rsa, you need to do:
+If you have an OpenSSH-style private key *~/.ssh/id_rsa*, you need to do:
 
+```
 dropbearconvert openssh dropbear ~/.ssh/id_rsa  ~/.ssh/id_rsa.db
 dbclient -i ~/.ssh/id_rsa.db <hostname>
+```
 
 Dropbear does not support encrypted hostkeys though can connect to ssh-agent.
 
-============================================================================
-
-If you want to get the public-key portion of a Dropbear private key, look at
-dropbearkey's '-y' option.
-
-============================================================================
+----
+If you want to get the public-key portion of a Dropbear private key, look at dropbearkey's `-y` option.
 
+----
 To run the server, you need to generate server keys, this is one-off:
+
+```
 ./dropbearkey -t rsa -f dropbear_rsa_host_key
 ./dropbearkey -t dss -f dropbear_dss_host_key
 ./dropbearkey -t ecdsa -f dropbear_ecdsa_host_key
 ./dropbearkey -t ed25519 -f dropbear_ed25519_host_key
+```
 
-or alternatively convert OpenSSH keys to Dropbear:
-./dropbearconvert openssh dropbear /etc/ssh/ssh_host_dsa_key dropbear_dss_host_key
-
-You can also get Dropbear to create keys when the first connection is made -
-this is preferable to generating keys when the system boots. Make sure 
-/etc/dropbear/ exists and then pass '-R' to the dropbear server.
+Or alternatively convert OpenSSH keys to Dropbear:
 
-============================================================================
+```
+./dropbearconvert openssh dropbear /etc/ssh/ssh_host_dsa_key dropbear_dss_host_key
+```
 
-If the server is run as non-root, you most likely won't be able to allocate a
-pty, and you cannot login as any user other than that running the daemon
-(obviously). Shadow passwords will also be unusable as non-root.
+You can also get Dropbear to create keys when the first connection is made - this is preferable to generating keys when the system boots. Make sure */etc/dropbear/* exists and then pass `-R` to the dropbear server.
 
-============================================================================
+----
+If the server is run as non-root, you most likely won't be able to allocate a pty, and you cannot login as any user other than that running the daemon (obviously). Shadow passwords will also be unusable as non-root.
 
-The Dropbear distribution includes a standalone version of OpenSSH's scp
-program. You can compile it with "make scp", you may want to change the path
-of the ssh binary, specified by _PATH_SSH_PROGRAM in options.h . By default
-the progress meter isn't compiled in to save space, you can enable it by 
-adding 'SCPPROGRESS=1' to the make commandline.
+----
+The Dropbear distribution includes a standalone version of OpenSSH's `scp` program. You can compile it with `make scp`. You may want to change the path of the ssh binary, specified by `_PATH_SSH_PROGRAM` in *options.h*. By default
+the progress meter isn't compiled in to save space, you can enable it by adding `SCPPROGRESS=1` to the `make` commandline.
diff --git a/SMALL b/SMALL
index 02658b1..742ac7e 100644
--- a/SMALL
+++ b/SMALL
@@ -1,56 +1,59 @@
-Tips for a small system:
+## Tips for a small system
 
 If you only want server functionality (for example), compile with
-	make PROGRAMS=dropbear
+
+```
+make PROGRAMS=dropbear
+```
+
 rather than just
-	make dropbear
-so that client functionality in shared portions of Dropbear won't be included.
-The same applies if you are compiling just a client.
 
----
+```
+make dropbear
+```
 
-The following are set in localoptions.h:
+so that client functionality in shared portions of Dropbear won't be included. The same applies if you are compiling just a client.
 
-	- If you're compiling statically, you can turn off host lookups
+---
+The following are set in *localoptions.h*:
 
-	- You can disable either password or public-key authentication, though note
-	  that the IETF draft states that pubkey authentication is required.
+* If you're compiling statically, you can turn off host lookups.
 
-	- Similarly with DSS and RSA, you can disable one of these if you know that
-	  all clients will be able to support a particular one. The IETF draft
-	  states that DSS is required, however you may prefer to use RSA. 
-	  DON'T disable either of these on systems where you aren't 100% sure about
-	  who will be connecting and what clients they will be using.
+* You can disable either password or public-key authentication, though note that the IETF draft states that pubkey authentication is required.
 
-	- Disabling the MOTD code and SFTP-SERVER may save a small amount of codesize
+* Similarly with DSS and RSA, you can disable one of these if you know that all clients will be able to support a particular one. The IETF draft states that DSS is required, however you may prefer to use RSA. **DON'T** disable either of these on systems where you aren't 100% sure about who will be connecting and what clients they will be using.
 
-	- You can disable x11, tcp and agent forwarding as desired. None of these are
-	  essential, although agent-forwarding is often useful even on firewall boxes.
+* Disabling the `MOTD` code and `SFTP-SERVER` may save a small amount of codesize.
 
----
+* You can disable x11, tcp and agent forwarding as desired. None of these are essential, although agent-forwarding is often useful even on firewall boxes.
 
-If you are compiling statically, you may want to disable zlib, as it will use
-a few tens of kB of binary-size (./configure --disable-zlib).
+---
+If you are compiling statically, you may want to disable zlib, as it will use a few tens of kB of binary-size
+```
+./configure --disable-zlib
+```
 
-You can create a combined binary, see the file MULTI, which will put all
-the functions into one binary, avoiding repeated code.
+You can create a combined binary, see the file [MULTI.md](MULTI.md), which will put all the functions into one binary, avoiding repeated code.
 
-If you're compiling with gcc, you might want to look at gcc's options for
-stripping unused code. The relevant vars to set before configure are:
+If you're compiling with gcc, you might want to look at gcc's options for stripping unused code. The relevant vars to set before configure are:
 
+```
 LDFLAGS=-Wl,--gc-sections
 CFLAGS="-ffunction-sections -fdata-sections"
+```
 
-You can also experiment with optimisation flags such as -Os, note that in some
-cases these flags actually seem to increase size, so experiment before
+You can also experiment with optimisation flags such as `-Os`. Note that in some cases these flags actually seem to increase size, so experiment before
 deciding.
 
 Of course using small C libraries such as uClibc and dietlibc can also help.
 
 ---
+Libtommath has its own default `CFLAGS` to improve speed. You can use
 
-Libtommath has its own default CFLAGS to improve speed. You can use
+```
 ./configure LTM_CFLAGS=-Os
+```
+
 to reduce size at the expense of speed.
 
 If you have any queries, mail me and I'll see if I can help.