annotate DEVELOPING.md @ 1938:77bc00dcc19f default tip main master

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