Now the comments reflect the way the code works; no code has been changed. In the process of updating the comments, they have also been copy edited; notably, old-style C comments (/**/) have been replaced with new-style, one-line C++ comments (//).
For the record, `packet.c' is another file that has already been using the new-style C++ comments, so there shouldn't be an existing issue with old compilers. --- default_options.h.in | 409 +++++++++++++++++++++++++++++---------------------- 1 file changed, 233 insertions(+), 176 deletions(-) diff --git a/default_options.h.in b/default_options.h.in index b061391..bc16f90 100644 --- a/default_options.h.in +++ b/default_options.h.in @@ -1,39 +1,47 @@ #ifndef DROPBEAR_DEFAULT_OPTIONS_H_ #define DROPBEAR_DEFAULT_OPTIONS_H_ -/* - > > > Read This < < < - -default_options.h.in (this file) documents compile-time options, and provides -default values. - -Local customisation should be added to localoptions.h which is -used if it exists. Options defined there will override any options in this -file (#ifndef guards added by ifndef_wrapper.sh). - -Options can also be defined with -DDROPBEAR_XXX in Makefile CFLAGS - -IMPORTANT: Many options will require "make clean" after changes */ +// This file documents compile-time options, and provides default values. +// +// Local customisation should be added to localoptions.h; options defined +// there will override the defaults. +// +// Many options are toggles that can be enabled or disabled. +// +// To enable an option, set its value to `1'. +// To disable an option, set its value to `0'. +// +// An option may also be set with something like `-DDROPBEAR_XXX=1' in the +// CFLAGS environment variable. +// +// IMPORTANT: It may be necessary to run `make clean' after altering +// the compile-time options. + +// Set the default port on which the server should listen. #define DROPBEAR_DEFPORT "22" -/* Listen on all interfaces */ +// Set the default IP address on which the server should listen. +// +// Set this to the empty string ("") to indicate that the server +// should listen on all interfaces, by default. #define DROPBEAR_DEFADDRESS "" -/* Default hostkey paths - these can be specified on the command line */ +// Default hostkey paths; these can be specified on the command line. #define DSS_PRIV_FILENAME "/etc/dropbear/dropbear_dss_host_key" #define RSA_PRIV_FILENAME "/etc/dropbear/dropbear_rsa_host_key" #define ECDSA_PRIV_FILENAME "/etc/dropbear/dropbear_ecdsa_host_key" -/* Set NON_INETD_MODE if you require daemon functionality (ie Dropbear listens - * on chosen ports and keeps accepting connections. This is the default. - * - * Set INETD_MODE if you want to be able to run Dropbear with inetd (or - * similar), where it will use stdin/stdout for connections, and each process - * lasts for a single connection. Dropbear should be invoked with the -i flag - * for inetd, and can only accept IPv4 connections. - * - * Both of these flags can be defined at once, don't compile without at least - * one of them. */ +// Set NON_INETD_MODE to `1' if you require daemon functionality (i.e, Dropbear +// listens on chosen ports and keeps accepting connections); otherwise, set it +// to `0'. +// +// Set INETD_MODE to `1' if you want to be able to run Dropbear via the inetd +// program (or similar), where it will use stdin/stdout for connections, and each +// process lasts for a single connection; to make use of this functionality, +// Dropbear should be invoked with the `-i' option (note that this functionality +// implies that Dropbear can accept only IPv4 connections). +// +// At least one of these options must be set to `1'; both may be set to `1'. #define NON_INETD_MODE 1 #define INETD_MODE 1 @@ -41,18 +49,18 @@ IMPORTANT: Many options will require "make clean" after changes */ #error "NON_INETD_MODE or INETD_MODE (or both) must be enabled." #endif -/* Set this if you want to use the DROPBEAR_SMALL_CODE option. This can save -several kB in binary size however will make the symmetrical ciphers and hashes -slower, perhaps by 50%. Recommended for small systems that aren't doing -much traffic. */ +// Set this to `1' to save several kB in binary size; however, it will make the +// symmetrical ciphers and hashes slower, perhaps by 50%. This might be worthwhile +// for small systems that aren't dealing with much traffic. #define DROPBEAR_SMALL_CODE 0 -/* Enable X11 Forwarding - server only */ +// Set this to `1' to enable X11 Forwarding (server only). #define DROPBEAR_X11FWD 1 -/* Enable TCP Fowarding */ -/* 'Local' is "-L" style (client listening port forwarded via server) - * 'Remote' is "-R" style (server listening port forwarded via client) */ +// Set each to `1' to enable TCP Fowarding. +// +// LOCAL is "-L" style (client listening port forwarded via server) +// REMOTE is "-R" style (server listening port forwarded via client) #define DROPBEAR_CLI_LOCALTCPFWD 1 #define DROPBEAR_CLI_REMOTETCPFWD 1 @@ -60,33 +68,37 @@ much traffic. */ #define DROPBEAR_SVR_LOCALTCPFWD 1 #define DROPBEAR_SVR_REMOTETCPFWD 1 -/* Enable Authentication Agent Forwarding */ +// Set each to `1' to enable Authentication Agent Forwarding. #define DROPBEAR_SVR_AGENTFWD 1 #define DROPBEAR_CLI_AGENTFWD 1 -/* Note: Both DROPBEAR_CLI_PROXYCMD and DROPBEAR_CLI_NETCAT must be set to - * allow multihop dbclient connections */ +// Note: Both DROPBEAR_CLI_PROXYCMD and DROPBEAR_CLI_NETCAT must be +// set to `1' to allow multihop connections via dbclient. -/* Allow using -J <proxycommand> to run the connection through a - pipe to a program, rather the normal TCP connection */ +// Set this to `1' to enable using `-J <proxycommand>' to run the connection +// through a pipe to a program, rather than through a normal TCP connection. #define DROPBEAR_CLI_PROXYCMD 1 -/* Enable "Netcat mode" option. This will forward standard input/output - * to a remote TCP-forwarded connection */ +// Set this to `1' to enable the "netcat mode" option; this will forward standard +// input/output to a remote TCP-forwarded connection. #define DROPBEAR_CLI_NETCAT 1 -/* Whether to support "-c" and "-m" flags to choose ciphers/MACs at runtime */ +// Set this to `1' to support the `-c' and `-m' options, which choose +// ciphers and MACs at runtime #define DROPBEAR_USER_ALGO_LIST 1 -/* Encryption - at least one required. - * Protocol RFC requires 3DES and recommends AES128 for interoperability. - * Including multiple keysize variants the same cipher - * (eg AES256 as well as AES128) will result in a minimal size increase.*/ +// Encryption (at least one is required). +// +// Set each to `1' to enable. +// +// The Protocol RFC requires 3DES and recommends AES128 for interoperability. +// Including multiple keysize variants of the same cipher (e.g., AES256 and +// AES128) will result in only a minimal increase in the size of the binaries. #define DROPBEAR_AES128 1 #define DROPBEAR_3DES 1 #define DROPBEAR_AES256 1 -/* Compiling in Blowfish will add ~6kB to runtime heap memory usage */ +// Compiling in Blowfish will add around 6 kB to runtime heap memory usage. #define DROPBEAR_BLOWFISH 0 #define DROPBEAR_TWOFISH256 1 #define DROPBEAR_TWOFISH128 1 @@ -96,119 +108,140 @@ much traffic. */ #error "At least one encryption algorithm must be enabled; 3DES and AES129 are recommended." #endif -/* Enable CBC mode for ciphers. This has security issues though - * is the most compatible with older SSH implementations */ +// Set this to `1' to enable CBC mode for ciphers. Though this has security +// issues, it is the most compatible with older SSH implementations. #define DROPBEAR_ENABLE_CBC_MODE 1 -/* Enable "Counter Mode" for ciphers. This is more secure than normal - * CBC mode against certain attacks. It is recommended for security - * and forwards compatibility */ +// Set this to `1' to enable "Counter Mode" for ciphers. Against certain attacks, +// this is more secure than normal CBC mode. It is recommended for security +// and forwards compatibility. #define DROPBEAR_ENABLE_CTR_MODE 1 -/* Twofish counter mode is disabled by default because it -has not been tested for interoperability with other SSH implementations. -If you test it please contact the Dropbear author */ +// Set this to `1' to enable "Twofish counter mode". +// +// It is disabled by default because it has not been tested for interoperability +// with other SSH implementations. If you test it, please let us know. #define DROPBEAR_TWOFISH_CTR 0 -/* Message integrity. sha2-256 is recommended as a default, - sha1 for compatibility */ +// Message integrity. +// +// Set each to `1' to enable it. +// +// SHA2-256 is recommended as a default, and SHA1 for compatibility. #define DROPBEAR_SHA1_HMAC 1 #define DROPBEAR_SHA1_96_HMAC 1 #define DROPBEAR_SHA2_256_HMAC 1 -/* Default is to include it is sha512 is being compiled in for ECDSA */ +// The default is to enable SHA2_512 only if ECDSA is enabled. #define DROPBEAR_SHA2_512_HMAC (DROPBEAR_ECDSA) -/* XXX needed for fingerprints */ +// Set this to `1' to enable support for fingerprints. #define DROPBEAR_MD5_HMAC 0 -/* Hostkey/public key algorithms - at least one required, these are used - * for hostkey as well as for verifying signatures with pubkey auth. - * Removing either of these won't save very much space. - * RSA is recommended - * DSS may be necessary to connect to some systems though - is not recommended for new keys */ +// Hostkey/public key algorithms (at least one is required). +// +// These are used for hostkey as well as for verifying signatures +// with pubkey authentication. +// +// Removing either of these won't save very much space. +// +// RSA is recommended (set it to `1'). +// DSS may be necessary to connect to some systems, though it is +// not recommended for new keys. #define DROPBEAR_RSA 1 #define DROPBEAR_DSS 1 -/* ECDSA is significantly faster than RSA or DSS. Compiling in ECC - * code (either ECDSA or ECDH) increases binary size - around 30kB - * on x86-64 */ +// Set this to `1' to enable support for ECDSA, which is significantly faster +// than RSA or DSS. Compiling in ECC code (either ECDSA or ECDH) increases +// binary size (by around 30 kB on x86-64). #define DROPBEAR_ECDSA 1 #if !(DROPBEAR_RSA || DROPBEAR_DSS || DROPBEAR_ECDSA) #error "At least one hostkey or public-key algorithm must be enabled; RSA is recommended." #endif -/* RSA must be >=1024 */ +// RSA must be >=1024 #define DROPBEAR_DEFAULT_RSA_SIZE 2048 -/* DSS is always 1024 */ -/* ECDSA defaults to largest size configured, usually 521 */ - -/* Add runtime flag "-R" to generate hostkeys as-needed when the first - connection using that key type occurs. - This avoids the need to otherwise run "dropbearkey" and avoids some problems - with badly seeded /dev/urandom when systems first boot. */ +// DSS is always 1024 +// ECDSA defaults to largest size configured, usually 521 + +// Set this to `1' to add the server runtime option `-R', which generates hostkeys +// as-needed when the first connection using that key type occurs. +// +// This avoids the need to run dropbearkey, and it avoids some problems with a +// badly seeded /dev/urandom (such as when systems are freshly booted). #define DROPBEAR_DELAY_HOSTKEY 1 -/* Enable Curve25519 for key exchange. This is another elliptic - * curve method with good security properties. Increases binary size - * by ~8kB on x86-64 */ +// Set this to `1' to enable Curve25519 for key exchange. +// +// This is another elliptic curve method (like ECDSA) with good +// security properties. +// +// Enabling this increases the binary size (by around 8 kB on x86-64). #define DROPBEAR_CURVE25519 1 -/* Enable elliptic curve Diffie Hellman key exchange, see note about - * ECDSA above */ +// Set this to `1' to enable the elliptic-curve Diffie-Hellman key exchange +// (see the note about ECDSA). #define DROPBEAR_ECDH 1 -/* Key exchange algorithm. - * group14_sha1 - 2048 bit, sha1 - * group14_sha256 - 2048 bit, sha2-256 - * group16 - 4096 bit, sha2-512 - * group1 - 1024 bit, sha1 - * - * group14 is supported by most implementations. - * group16 provides a greater strength level but is slower and increases binary size - * group1 is too small for security though is necessary if you need - compatibility with some implementations such as Dropbear versions < 0.53 - */ +// Key exchange algorithm. +// +// GROUP1 1024 bit, SHA1 +// GROUP14_SHA1 2048 bit, SHA1 +// GROUP14_SHA256 2048 bit, SHA2-256 +// GROUP16 4096 bit, SHA2-512 +// +// GROUP1 is too small for security, but it is necessary if you need +// compatibility with some implementations, such as Dropbear versions < 0.53. +// +// GROUP14 is supported by most implementations. +// +// GROUP16 provides a greater strength level but is slower and increases +// the binary size. #define DROPBEAR_DH_GROUP1 1 #define DROPBEAR_DH_GROUP14_SHA1 1 #define DROPBEAR_DH_GROUP14_SHA256 1 #define DROPBEAR_DH_GROUP16 0 -/* Control the memory/performance/compression tradeoff for zlib. - * Set windowBits=8 for least memory usage, see your system's - * zlib.h for full details. - * Default settings (windowBits=15) will use 256kB for compression - * windowBits=8 will use 129kB for compression. - * Both modes will use ~35kB for decompression (using windowBits=15 for - * interoperability) */ +// Control zlib's tradeoffs among memory/performance/compression. +// +// The default, `15' (bits), is used for compatibility, and will use +// 256 kB of working memory for compression. +// +// Set this to `8' (bits) for the least memory usage; see your system's +// `zlib.h' for full details. This will use 129 kB for compression. +// +// Both modes will use around 35 kB for decompression. #define DROPBEAR_ZLIB_WINDOW_BITS 15 -/* Whether to do reverse DNS lookups. */ +// Set this to `1' to do reverse DNS lookups. #define DO_HOST_LOOKUP 0 -/* Whether to print the message of the day (MOTD). */ +// Set this to `1' to print the message of the day (MOTD). #define DO_MOTD 0 -/* The MOTD file path */ +// The MOTD file path #define MOTD_FILENAME "/etc/motd" -/* Authentication Types - at least one required. - RFC Draft requires pubkey auth, and recommends password */ - -/* Note: PAM auth is quite simple and only works for PAM modules which just do - * a simple "Login: " "Password: " (you can edit the strings in svr-authpam.c). - * It's useful for systems like OS X where standard password crypts don't work - * but there's an interface via a PAM module. It won't work for more complex - * PAM challenge/response. - * You can't enable both PASSWORD and PAM. */ - -/* This requires crypt() */ +// Authentication Types (at least one is required). +// +// Set each to `1' to enable it. +// +// The RFC requires PUBKEY_AUTH, and recommends PASSWORD_AUTH. +// +// Note: PAM_AUTH is quite simple, and only works for PAM modules which just do +// a simple "Login:" and "Password:" (you can edit the strings in `svr-authpam.c'). +// It's useful for systems like OS X where standard password crypts don't work +// but there's an interface via a PAM module. It won't work for a more complex +// PAM challenge/response. +// +// You cannot enable both PASSWORD_AUTH and PAM_AUTH. + +// This requires crypt() #ifdef HAVE_CRYPT #define DROPBEAR_SVR_PASSWORD_AUTH 1 #else #define DROPBEAR_SVR_PASSWORD_AUTH 0 #endif -/* PAM requires ./configure --enable-pam */ +// PAM requires `./configure --enable-pam' #define DROPBEAR_SVR_PAM_AUTH 0 #define DROPBEAR_SVR_PUBKEY_AUTH 1 @@ -220,11 +253,11 @@ If you test it please contact the Dropbear author */ #error "DROPBEAR_SVR_PASSWORD_AUTH cannot be enabled at the same time as DROPBEAR_SVR_PAM_AUTH." #endif -/* Whether to take public key options in - * authorized_keys file into account */ +// Set this to `1' to account for public key options in +// the `authorized_keys' file. #define DROPBEAR_SVR_PUBKEY_OPTIONS 1 -/* This requires getpass. */ +// This requires getpass. #ifdef HAVE_GETPASS #define DROPBEAR_CLI_PASSWORD_AUTH 1 #define DROPBEAR_CLI_INTERACT_AUTH 1 @@ -238,109 +271,133 @@ If you test it please contact the Dropbear author */ #error "At least one client authentication type must be enabled; PUBKEY and PASSWORD are recommended." #endif -/* A default argument for dbclient -i <privatekey>. -Homedir is prepended unless path begins with / */ +// Set a default `<privatekey>' for `dbclient -i <privatekey>'. +// +// This is a file path; if the path begins with `/', then it +// is used without modification. Otherwise, this value is +// prefixed with the user's home directory. #define DROPBEAR_DEFAULT_CLI_AUTHKEY ".ssh/id_dropbear" -/* This variable can be used to set a password for client - * authentication on the commandline. Beware of platforms - * that don't protect environment variables of processes etc. Also - * note that it will be provided for all "hidden" client-interactive - * style prompts - if you want something more sophisticated, use - * SSH_ASKPASS instead. Comment out this var to remove this functionality.*/ +// Set this to `1' to enable the client to read an authentication +// password from the DROPBEAR_PASSWORD environment variable. +// +// Beware of platforms that don't protect the environment variables +// that are being used by processes, etc. Also note that it will be +// provided for all "hidden" client-interactive style prompts; if you +// want something more sophisticated, use SSH_ASKPASS instead. #define DROPBEAR_USE_DROPBEAR_PASSWORD 1 -/* Define this (as well as DROPBEAR_CLI_PASSWORD_AUTH) to allow the use of - * a helper program for the ssh client. The helper program should be - * specified in the SSH_ASKPASS environment variable, and dbclient - * should be run with DISPLAY set and no tty. The program should - * return the password on standard output */ +// Set this (and DROPBEAR_CLI_PASSWORD_AUTH) to `1' to allow the use of +// a helper program for the ssh client. The helper program should be +// specified in the SSH_ASKPASS environment variable, and dbclient +// should be run with DISPLAY set and no tty. The program should +// return the password on standard output. #define DROPBEAR_CLI_ASKPASS_HELPER 0 #if DROPBEAR_CLI_ASKPASS_HELPER #define DROPBEAR_CLI_PASSWORD_AUTH 1 #endif -/* Save a network roundtrip by sendng a real auth request immediately after - * sending a query for the available methods. It is at the expense of < 100 - * bytes of extra network traffic. This is not yet enabled by default since it - * could cause problems with non-compliant servers */ +// Set this to `1' to save a network roundtrip by sendng a real auth request +// immediately after sending a query for the available methods. It is at the +// expense of < 100 bytes of extra network traffic. +// +// This is not yet enabled by default because it could cause problems with +// non-compliant servers. #define DROPBEAR_CLI_IMMEDIATE_AUTH 0 -/* Source for randomness. This must be able to provide hundreds of bytes per SSH - * connection without blocking. In addition /dev/random is used for seeding - * rsa/dss key generation */ +// Source for randomness. This must be able to provide hundreds of bytes per SSH +// connection without blocking. In addition, /dev/random is used for seeding +// RSA/DSS key generation. #define DROPBEAR_URANDOM_DEV "/dev/urandom" -/* Set this to use PRNGD or EGD instead of /dev/urandom or /dev/random */ -/*#define DROPBEAR_PRNGD_SOCKET "/var/run/dropbear-rng"*/ +// Set this to use PRNGD or EGD instead of /dev/urandom or /dev/random +//#define DROPBEAR_PRNGD_SOCKET "/var/run/dropbear-rng" + +// Specify the number of clients we will allow to be connected but +// not yet authenticated. After this limit, connections are rejected. -/* Specify the number of clients we will allow to be connected but - * not yet authenticated. After this limit, connections are rejected */ -/* The first setting is per-IP, to avoid denial of service */ +// Specify a per-IP limit to avoid denial of service. #define MAX_UNAUTH_PER_IP 5 -/* And then a global limit to avoid chewing memory if connections - * come from many IPs */ +// Specify a global limit to avoid chewing up memory if connections +// come from many IPs. #define MAX_UNAUTH_CLIENTS 30 -/* Default maximum number of failed authentication tries (server option) */ -/* -T server option overrides */ +// Specify the default maximum number of failed authentication tries; +// the server option `-T' overrides this value. #define MAX_AUTH_TRIES 10 -/* The default file to store the daemon's process ID, for shutdown - scripts etc. This can be overridden with the -P flag */ +// Specify the default file for storing the daemon's process ID, which +// is intended to be used by shutdown scripts, etc. +// This can be overridden with the server option `-P'. #define DROPBEAR_PIDFILE "/var/run/dropbear.pid" -/* The command to invoke for xauth when using X11 forwarding. - * "-q" for quiet */ +// Specify the command to invoke for xauth when using X11 forwarding; +// include `-q' for quiet operation. #define XAUTH_COMMAND "/usr/bin/xauth -q" +// Set this to `1' to enable support for running an sFTP server program. #define DROPBEAR_SFTPSERVER 1 -/* if you want to enable running an sftp server (such as the one included with - * OpenSSH), set the path below. If the path isn't defined, sftp will not - * be enabled */ +// Specify the path to an sFTP server program to run. #define SFTPSERVER_PATH "/usr/libexec/sftp-server" -/* This is used by the scp binary when used as a client binary. If you're - * not using the Dropbear client, you'll need to change it */ +// Set the path to the SSH client program to use. +// This is used by the `scp' program. #define DROPBEAR_PATH_SSH_PROGRAM "/usr/bin/dbclient" -/* Whether to log commands executed by a client. This only logs the - * (single) command sent to the server, not what a user did in a - * shell/sftp session etc. */ +// Set this to `1' to log commands executed by a client. This only logs the +// (single) command sent to the server, not what a user does in a +// shell/sFTP session, etc. #define LOG_COMMANDS 0 -/* Window size limits. These tend to be a trade-off between memory - usage and network performance: */ -/* Size of the network receive window. This amount of memory is allocated - as a per-channel receive buffer. Increasing this value can make a - significant difference to network performance. 24kB was empirically - chosen for a 100mbit ethernet network. The value can be altered at - runtime with the -W argument. */ +// Window size limits. These tend to be a trade-off between memory +// usage and network performance: + +// Specify the size of the network receive window. This amount of memory +// (in bytes) is allocated as a per-channel receive buffer. Increasing +// this value can have a significant impact on network performance. +// +// The value (24 KiB) was chosen empirically for a 100 Mbit ethernet +// network. The value can be altered at runtime with the `-W' option. #define DEFAULT_RECV_WINDOW 24576 -/* Maximum size of a received SSH data packet - this _MUST_ be >= 32768 - in order to interoperate with other implementations */ + +// Specify the maximum size of a received SSH data packet; this *MUST* +// be >= 32768 in order to interoperate with other implementations. #define RECV_MAX_PAYLOAD_LEN 32768 -/* Maximum size of a transmitted data packet - this can be any value, - though increasing it may not make a significant difference. */ + +// Specify the maximum size of a transmitted data packet; this can be +// any value, though increasing it may not have a significant impact. #define TRANS_MAX_PAYLOAD_LEN 16384 -/* Ensure that data is transmitted every KEEPALIVE seconds. This can -be overridden at runtime with -K. 0 disables keepalives */ +// Specify the default number of seconds that should elapse between +// 2 consecutive keepalive messages. +// +// This value can be overridden at runtime with the `-K' option. +// +// The value `0' disables keepalives by default. #define DEFAULT_KEEPALIVE 0 -/* If this many KEEPALIVES are sent with no packets received from the -other side, exit. Not run-time configurable - if you have a need -for runtime configuration please mail the Dropbear list */ +// Set the maximum number of unanswered keepalives that are allowed to +// occur before determining that the connection has failed. +// +// This is not runtime configurable; if you have a need for runtime +// configuration, please contact the Dropbear mailing list. #define DEFAULT_KEEPALIVE_LIMIT 3 -/* Ensure that data is received within IDLE_TIMEOUT seconds. This can -be overridden at runtime with -I. 0 disables idle timeouts */ +// Set the maximum number of seconds that may elapse without transmission +// of data in either direction; if no data is sent or received within this +// amount of time, then the session is ended. +// +// This value can be overridden at runtime with the `-I' option. +// +// The value `0' disables this timeout. #define DEFAULT_IDLE_TIMEOUT 0 -/* The default path. This will often get replaced by the shell */ +// Set the default PATH environment variable provided by the server; usually, +// when a client invokes a shell, the shell replaces this value with something +// else. #define DEFAULT_PATH "/usr/bin:/bin" #endif /* DROPBEAR_DEFAULT_OPTIONS_H_ */ -- 2.10.0