Mercurial > dropbear

comparison DEVELOPING.md @ 1733:d529a52b2f7c coverity coverity

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
merge coverity from main
author Matt Johnston <matt@ucc.asn.au>
date Fri, 26 Jun 2020 21:07:34 +0800
parents 57226fc75cb5
children
comparison
equal deleted inserted replaced
1643:b59623a64678 1733:d529a52b2f7c
1 # Developer Notes
2
3 ## Building
4
5 See [INSTALL](INSTALL) for build instructions.
6 [SMALL](SMALL) has hints for building smaller binaries, also see comments
7 in default_options.h.
8
9 ## Debug printing
10
11 Set `#define DEBUG_TRACE 1` in localoptions.h to enable a `-v` option
12 for dropbear and dbclient. That prints various details of the session. For
13 development running `dropbear -F -E` is useful to run in the foreground. You
14 can set `#define DEBUG_NOFORK 1` to make dropbear a one-shot server, easy to
15 run under a debugger.
16
17 ## Random sources
18
19 Most cryptography requires a good random entropy source, both to generate secret
20 keys and in the course of a session. Dropbear uses the Linux kernel's
21 `getrandom()` syscall to ensure that the system RNG has been initialised before
22 using it. On some systems there is insufficient entropy gathered during early
23 boot - generating hostkeys then will block for some amount of time.
24 Dropbear has a `-R` option to generate hostkeys upon the first connection
25 as required - that will allow the system more time to gather entropy.
26
27 ## Algorithms
28
29 Default algorithm lists are specified in [common-algo.c](common-algo.c).
30 They are in priority order, the client's first matching choice is used
31 (see rfc4253).
32 Dropbear client has `-c` and `-m` arguments to choose which are enabled at
33 runtime (doesn't work for server as of June 2020).
34
35 Enabling/disabling algorithms is done in [localoptions.h](localoptions.h),
36 see [default_options.h](default_options.h).
37
38 ## Style
39
40 Source code is indented with tabs, width set to 4 (though width shouldn't
41 matter much). Braces are on the same line as functions/loops/if - try
42 to keep consistency with existing code.
43
44 All `if` statements should have braces, no exceptions.
45
46 Avoid using pointer arithmetic, instead the functions in
47 [buffer.h](buffer.h) should be used.
48
49 Some Dropbear platforms have old compilers.
50 Variable declarations must be at the top of a scope and
51 comments must be `/* */` rather than `//`.
52
53 Pointer variables should be initialised to NULL - it can reduce the
54 severity of bugs.
55
56 ## Third party code
57
58 Libtomcrypt and libtommath are periodically synced from upstream, so
59 avoid making changes to that code which will need to be maintained.
60 Improvements can be sent upstream to the libtom project.
61
62 ## Non-root user
63
64 Dropbear server will run fine as a non-root user, allowing logins only for
65 that user. Password authentication probably won't work (can't read shadow
66 passwords). You will need to create hostkeys that are readable.
67
68 ## Connection setup
69
70 Dropbear implements first_kex_packet_follows to reduce
71 handshake latency (rfc 4253 7.1). Some less common implementations don't
72 handle that, it can be a cause of problems connecting. Note also that
73 Dropbear may send several ssh packets within a single TCP packet - it's just a
74 stream.
75