2009-03-13 03:33:27 +00:00
|
|
|
=====================================================================
|
|
|
|
libtelnet - TELNET protocol handling library
|
|
|
|
=====================================================================
|
|
|
|
|
2009-03-14 17:39:07 +00:00
|
|
|
http://github.com/elanthis/libtelnet
|
|
|
|
|
|
|
|
Sean Middleditch
|
|
|
|
sean@sourcemud.org
|
2009-03-13 03:33:27 +00:00
|
|
|
|
|
|
|
---------------------------------------------------------------------
|
|
|
|
The author or authors of this code dedicate any and all copyright
|
|
|
|
interest in this code to the public domain. We make this dedication
|
|
|
|
for the benefit of the public at large and to the detriment of our
|
|
|
|
heirs and successors. We intend this dedication to be an overt act of
|
|
|
|
relinquishment in perpetuity of all present and future rights to this
|
|
|
|
code under copyright law.
|
|
|
|
---------------------------------------------------------------------
|
|
|
|
|
2009-03-14 09:24:56 +00:00
|
|
|
*** TODO ***
|
|
|
|
|
2009-03-21 03:08:55 +00:00
|
|
|
- the negotiate callback behavior needs to be redone so that the
|
|
|
|
app immediately confirms; right now if you set ev->accept=1 when
|
|
|
|
receiving a request to enable you can't immediately start sending
|
|
|
|
ubnegotiations because the confirmation hasn't been sent yet. :/
|
2009-03-14 09:24:56 +00:00
|
|
|
? ZMP parsing
|
|
|
|
? MSSP parsing
|
2009-03-21 03:08:55 +00:00
|
|
|
? TTYPE parsing
|
2009-03-14 09:24:56 +00:00
|
|
|
? ENVIRON/NEW-ENVIRON parsing
|
|
|
|
|
2009-03-13 03:33:27 +00:00
|
|
|
I. INTRODUCTION
|
|
|
|
=====================================================================
|
|
|
|
|
|
|
|
libtelnet provides safe and correct handling of the core TELNET
|
2009-03-16 05:06:27 +00:00
|
|
|
protocol. In addition to the base TELNET protocol, libtelnet also
|
2009-03-19 06:32:04 +00:00
|
|
|
implements the Q method of TELNET option negotiation. libtelnet can
|
|
|
|
be used for writing servers, clients, or proxies.
|
2009-03-13 03:33:27 +00:00
|
|
|
|
2009-03-14 17:39:07 +00:00
|
|
|
For more information on the TELNET protocol, see:
|
|
|
|
|
|
|
|
http://www.faqs.org/rfcs/rfc854.html
|
2009-03-16 05:06:27 +00:00
|
|
|
http://www.faqs.org/rfcs/rfc1143.html
|
2009-03-14 17:39:07 +00:00
|
|
|
|
2009-03-13 03:33:27 +00:00
|
|
|
II. LIBTELNET API
|
|
|
|
=====================================================================
|
|
|
|
|
2009-03-14 17:39:07 +00:00
|
|
|
The libtelnet API contains several distinct parts. The first part is
|
|
|
|
the basic initialization and deinitialization routines. The second
|
2009-03-19 06:32:04 +00:00
|
|
|
part is a single function for pushing received data into the telnet
|
2009-03-21 03:08:55 +00:00
|
|
|
processor. The third part is the libtelnet output functions, which
|
2009-03-19 06:32:04 +00:00
|
|
|
generate TELNET commands and ensure data is properly formatted before
|
|
|
|
sending over the wire. The final part is the event handler
|
|
|
|
interface.
|
2009-03-14 17:39:07 +00:00
|
|
|
|
|
|
|
IIa. Initialization
|
|
|
|
|
2009-03-22 20:26:06 +00:00
|
|
|
Using libtelnet requires the initialization of a telnet_t structure
|
|
|
|
which stores all current state for a single TELNET connection.
|
|
|
|
|
|
|
|
Initializing a telnet_t structure requires several pieces of data.
|
|
|
|
One of these is the telopt support table, which specifies which
|
|
|
|
TELNET options your application supports both locally and remotely.
|
|
|
|
This table is comprised of telnet_telopt_t structures, one for each
|
|
|
|
supported option. Each entry specifies the option supported,
|
|
|
|
whether the option is supported locally or remotely.
|
|
|
|
|
|
|
|
struct telnet_telopt_t {
|
|
|
|
short telopt;
|
|
|
|
unsigned char us;
|
|
|
|
unsigned char him;
|
|
|
|
};
|
|
|
|
|
|
|
|
The us field denotes whether your application supporst the telopt
|
|
|
|
locally. It should be set to TELNET_WILL if you support it and to
|
|
|
|
TELNET_WONT if you don't. The him field denotes whether the telopt
|
|
|
|
is supported on the remote end, and should be TELNET_DO if yes and
|
|
|
|
TELNET_DONT if not.
|
|
|
|
|
|
|
|
When definition the telopt table you must include an end marker
|
|
|
|
entry, which is simply an entry with telopt set to -1. For
|
|
|
|
example:
|
|
|
|
|
|
|
|
static const telnet_telopt_t my_telopts[] = {
|
|
|
|
{ TELNET_TELOPT_ECHO, TELNET_WILL, TELNET_DONT },
|
|
|
|
{ TELNET_TELOPT_TTYPE, TELNET_WILL, TELNET_DONT },
|
|
|
|
{ TELNET_TELOPT_COMPRESS2, TELNET_WONT, TELNET_DO },
|
|
|
|
{ TELNET_TELOPT_ZMP, TELNET_WONT, TELNET_DO },
|
|
|
|
{ TELNET_TELOPT_MSSP, TELNET_WONT, TELNET_DO },
|
|
|
|
{ TELNET_TELOPT_BINARY, TELNET_WILL, TELNET_DO },
|
|
|
|
{ TELNET_TELOPT_NAWS, TELNET_WILL, TELNET_DONT },
|
|
|
|
{ -1, 0, 0 }
|
|
|
|
};
|
|
|
|
|
|
|
|
If you need to dynamically alter supported options on a
|
|
|
|
per-connection basis then you may use a different tables
|
|
|
|
(dynamically allocated if necessary) per call to telnet_init() or
|
|
|
|
you share a single constant table like the above example between
|
|
|
|
all connections if you support a fixed set of options. Most
|
|
|
|
applications will support only a fixed set of options.
|
|
|
|
|
|
|
|
void telnet_init(telnet_t *telnet, const telnet_telopts_t *telopts,
|
|
|
|
telnet_event_handler_t handler, unsigned char flags,
|
|
|
|
void *user_data);
|
2009-03-19 06:32:04 +00:00
|
|
|
The telnet_init() function is responsible for initializing the
|
|
|
|
data in a telnet_t structure. It must be called immediately after
|
|
|
|
establishing a connection and before any other libtelnet API calls
|
|
|
|
are made.
|
2009-03-14 17:39:07 +00:00
|
|
|
|
2009-03-22 20:26:06 +00:00
|
|
|
The telopts field is the telopt support table as described above.
|
|
|
|
|
2009-03-15 16:57:32 +00:00
|
|
|
The handler parameter must be a function matching the
|
2009-03-19 06:32:04 +00:00
|
|
|
telnet_event_handler_t definition. More information about events
|
|
|
|
can be found in section IId.
|
2009-03-15 01:45:28 +00:00
|
|
|
|
2009-03-15 17:39:24 +00:00
|
|
|
The user_data parameter is passed to the event handler whenver it
|
|
|
|
is invoked. This will usually be a structure container
|
|
|
|
information about the connection, including a socket descriptor
|
2009-03-19 06:32:04 +00:00
|
|
|
for implementing TELNET_EV_SEND event handling.
|
2009-03-15 17:39:24 +00:00
|
|
|
|
2009-03-16 03:29:46 +00:00
|
|
|
The flags parameter can be any of the following flag constants
|
|
|
|
bit-or'd together, or 0 to leave all options disabled.
|
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
TELNET_FLAG_PROXY
|
2009-03-16 20:47:27 +00:00
|
|
|
Operate in proxy mode. This disables the RFC1143 support and
|
|
|
|
enables automatic detection of COMPRESS2 streams.
|
2009-03-14 17:39:07 +00:00
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
boid telnet_free(telnet_t *telnet);
|
|
|
|
Releases any internal memory allocated by libtelnet. This must be
|
|
|
|
called whenever a connection is closed, or you will incur memory
|
|
|
|
leaks.
|
2009-03-14 17:39:07 +00:00
|
|
|
|
|
|
|
IIb. Receiving Data
|
|
|
|
|
2009-03-21 03:08:55 +00:00
|
|
|
void telnet_recv(telnet_t *telnet,
|
2009-03-19 06:08:46 +00:00
|
|
|
const char *buffer, unsigned int size, void *user_data);
|
2009-03-14 17:39:07 +00:00
|
|
|
When your application receives data over the socket from the
|
|
|
|
remote end, it must pass the received bytes into this function.
|
2009-03-15 16:57:32 +00:00
|
|
|
|
|
|
|
As the TELNET stream is parsed, events will be generated and
|
2009-03-19 06:32:04 +00:00
|
|
|
passed to the event handler given to telnet_init(). Of particular
|
|
|
|
interest for data receiving is the TELNET_EV_DATA event, which is
|
|
|
|
triggered for any regular data such as user input or server
|
|
|
|
process output.
|
2009-03-14 17:39:07 +00:00
|
|
|
|
|
|
|
IIc. Sending Data
|
|
|
|
|
2009-03-21 03:08:55 +00:00
|
|
|
All of the output functions will invoke the TELNET_EV_SEND event.
|
2009-03-15 16:57:32 +00:00
|
|
|
|
|
|
|
Note: it is very important that ALL data sent to the remote end of
|
|
|
|
the connection be passed through libtelnet. All user input or
|
|
|
|
process output that you wish to send over the wire should be given
|
2009-03-16 21:21:48 +00:00
|
|
|
to one of the following functions. Do NOT send or buffer
|
|
|
|
unprocessed output data directly!
|
2009-03-14 17:39:07 +00:00
|
|
|
|
2009-03-21 03:08:55 +00:00
|
|
|
void telnet_iac(telnet_t *telnet, unsigned char cmd);
|
2009-03-14 17:39:07 +00:00
|
|
|
Sends a single "simple" TELNET command, such as the GO-AHEAD
|
|
|
|
commands (255 249).
|
|
|
|
|
2009-03-21 03:08:55 +00:00
|
|
|
void telnet_negotiate(telnet_t *telnet, unsigned char cmd,
|
2009-03-19 06:32:04 +00:00
|
|
|
unsigned char opt);
|
|
|
|
Sends a TELNET negotiation command. The cmd parameter must be one
|
|
|
|
of TELNET_WILL, TELNET_DONT, TELNET_DO, or TELNET_DONT. The opt
|
|
|
|
parameter is the option to negotiate.
|
2009-03-14 17:39:07 +00:00
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
Unless in PROXY mode, the RFC1143 support may delay or ellide the
|
|
|
|
request entirely, as appropriate. It will ignore duplicate
|
|
|
|
invocations, such as asking for WILL NAWS when NAWS is already on
|
|
|
|
or is currently awaiting response from the remote end.
|
2009-03-14 17:39:07 +00:00
|
|
|
|
2009-03-21 03:08:55 +00:00
|
|
|
void telnet_send(telnet_t *telnet, const char *buffer, size_t size);
|
2009-03-19 06:32:04 +00:00
|
|
|
Sends raw data, which would be either the process output from a
|
|
|
|
server or the user input from a client.
|
|
|
|
|
|
|
|
For sending regular text is may be more convenient to use
|
|
|
|
telnet_printf().
|
2009-03-19 19:17:13 +00:00
|
|
|
|
|
|
|
void telnet_begin_subnegotiation(telnet_t *telnet, unsigned char
|
|
|
|
telopt);
|
|
|
|
Sends the header for a TELNET sub-negotiation command for the
|
|
|
|
specified option. All send data following this command will be
|
|
|
|
part of the sub-negotiation data until a call is made to
|
|
|
|
telnet_finish_subnegotiation().
|
|
|
|
|
|
|
|
You should not use telnet_printf() for sending subnegotiation
|
|
|
|
data as it will perform newline translations that usually do not
|
|
|
|
need to be done for subnegotiation data, and may cause problems.
|
|
|
|
|
|
|
|
void telnet_finish_subnegotiation(telnet_t *telnet);
|
|
|
|
Sends the end marker for a TELNET sub-negotiation command. This
|
|
|
|
must be called after (and only after) a call has been made to
|
|
|
|
telnet_begin_subnegotiation() and any negotiation data has been
|
|
|
|
sent.
|
2009-03-19 06:32:04 +00:00
|
|
|
|
2009-03-21 03:08:55 +00:00
|
|
|
void telnet_subnegotiation(telnet_t *telnet, unsigned char telopt,
|
|
|
|
const char *buffer, unsigned int size);
|
2009-03-19 06:32:04 +00:00
|
|
|
Sends a TELNET sub-negotiation command. The telopt parameter is
|
|
|
|
the sub-negotiation option.
|
2009-03-14 17:39:07 +00:00
|
|
|
|
2009-03-19 19:17:13 +00:00
|
|
|
Note that this function is just a shorthand for:
|
2009-03-21 03:08:55 +00:00
|
|
|
telnet_begin_sb(telnet, telopt);
|
|
|
|
telnet_send(telnet, buffer, size);
|
|
|
|
telnet_end_sb(telnet);
|
2009-03-16 05:25:52 +00:00
|
|
|
|
|
|
|
For some subnegotiations that involve a lot of complex formatted
|
2009-03-19 19:17:13 +00:00
|
|
|
data to be sent, it may be easier to make calls to both
|
2009-03-21 03:08:55 +00:00
|
|
|
telnet_begin_sb() and telnet_finish_sb() and using telnet_send()
|
|
|
|
or telnet_printf2() to format the data.
|
2009-03-16 05:25:52 +00:00
|
|
|
|
2009-03-21 03:08:55 +00:00
|
|
|
NOTE: telnet_subnegotiation() does have special behavior in
|
2009-03-19 06:32:04 +00:00
|
|
|
PROXY mode, as in that mode this function will automatically
|
2009-03-16 05:25:52 +00:00
|
|
|
detect the COMPRESS2 marker and enable zlib compression.
|
2009-03-16 21:21:48 +00:00
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
int telnet_printf(telnet_t *telnet, const char *fmt, ...);
|
|
|
|
This functions very similarly to fprintf, except that output is
|
|
|
|
sent through libtelnet for processing. IAC bytes are properly
|
|
|
|
escaped, C newlines (\n) are translated into CR LF, and C carriage
|
|
|
|
returns (\r) are translated into CR NUL, all as required by
|
|
|
|
RFC854. The return code is the length of the formatted text.
|
2009-03-16 21:21:48 +00:00
|
|
|
|
|
|
|
NOTE: due to an internal implementation detail, the maximum
|
|
|
|
lenth of the formatted text is 4096 characters.
|
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
int telnet_printf2(telnet_t *telnet, const char *fmt, ...);
|
|
|
|
Identical to telnet_printf() except that \r and \n are not
|
|
|
|
translated. This should be used if you are attempting to send
|
|
|
|
raw data inside a subnegotiation or if you have already manually
|
|
|
|
escaped newlines.
|
2009-03-16 05:25:52 +00:00
|
|
|
|
2009-03-15 16:57:32 +00:00
|
|
|
IId. Event Handling
|
2009-03-14 17:39:07 +00:00
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
libtelnet relies on an event-handling mechanism for processing the
|
|
|
|
parsed TELNET protocol stream as well as for buffering and sending
|
|
|
|
output data.
|
2009-03-15 01:45:28 +00:00
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
When you initialize a telnet_t structure with telnet_init() you had
|
|
|
|
to pass in an event handler function. This function must meet the
|
|
|
|
following prototype:
|
2009-03-15 01:45:28 +00:00
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
void (telnet_t *telnet, telnet_event_t *event, void *user_data);
|
2009-03-15 17:39:24 +00:00
|
|
|
|
|
|
|
The event structure is detailed below. The user_data value is the
|
2009-03-19 06:32:04 +00:00
|
|
|
pointer passed to telnet_init().
|
2009-03-15 01:45:28 +00:00
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
struct telnet_event_t {
|
2009-03-19 06:08:46 +00:00
|
|
|
const char *buffer;
|
2009-03-15 16:57:32 +00:00
|
|
|
unsigned int size;
|
2009-03-19 06:32:04 +00:00
|
|
|
telnet_event_type_t type;
|
2009-03-16 03:24:03 +00:00
|
|
|
unsigned char command;
|
|
|
|
unsigned char telopt;
|
|
|
|
unsigned char accept;
|
2009-03-15 16:57:32 +00:00
|
|
|
};
|
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
The enumeration values of telnet_event_type_t are described in
|
2009-03-15 16:57:32 +00:00
|
|
|
detail below. Whenever the the event handler is invoked, the
|
2009-03-19 06:32:04 +00:00
|
|
|
application must look at the event->type value and do any necessary
|
|
|
|
processing.
|
2009-03-15 16:57:32 +00:00
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
The only event that MUST be implemented is TELNET_EV_SEND. Most
|
|
|
|
applications will also always want to implement the event
|
|
|
|
TELNET_EV_DATA.
|
2009-03-15 16:57:32 +00:00
|
|
|
|
|
|
|
Here is an example event handler implementation which includes
|
|
|
|
handlers for several important events.
|
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
void my_event_handler(telnet_t *telnet, telnet_event_t *ev,
|
2009-03-16 03:24:03 +00:00
|
|
|
void *user_data) {
|
2009-03-15 16:57:32 +00:00
|
|
|
struct user_info *user = (struct user_info *)user_data;
|
|
|
|
|
|
|
|
switch (ev->type) {
|
2009-03-19 06:32:04 +00:00
|
|
|
case TELNET_EV_DATA:
|
2009-03-15 16:57:32 +00:00
|
|
|
process_user_input(user, event->buffer, event->size);
|
|
|
|
break;
|
2009-03-19 06:32:04 +00:00
|
|
|
case TELNET_EV_SEND:
|
2009-03-15 16:57:32 +00:00
|
|
|
write_to_descriptor(user, event->buffer, event->size);
|
|
|
|
break;
|
2009-03-19 06:32:04 +00:00
|
|
|
case TELNET_EV_ERROR:
|
2009-03-15 16:57:32 +00:00
|
|
|
fatal_error("TELNET error: %s", event->buffer);
|
|
|
|
break;
|
|
|
|
}
|
|
|
|
}
|
2009-03-14 17:39:07 +00:00
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
TELNET_EV_DATA:
|
|
|
|
The DATA event is triggered whenever regular data (not part of any
|
|
|
|
special TELNET command) is received. For a client, this will be
|
|
|
|
process output from the server. For a server, this will be input
|
|
|
|
typed by the user.
|
2009-03-14 17:39:07 +00:00
|
|
|
|
2009-03-15 16:57:32 +00:00
|
|
|
The event->buffer value will contain the bytes received and the
|
2009-03-19 06:32:04 +00:00
|
|
|
event->size value will contain the number of bytes received. Note
|
|
|
|
that event->buffer is not NUL terminated!
|
2009-03-14 17:39:07 +00:00
|
|
|
|
2009-03-15 16:57:32 +00:00
|
|
|
NOTE: there is no guarantee that user input or server output
|
|
|
|
will be received in whole lines. If you wish to process data
|
|
|
|
a line at a time, you are responsible for buffering the data and
|
|
|
|
checking for line terminators yourself!
|
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
TELNET_EV_SEND:
|
|
|
|
This event is sent whenever libtelnet has generated data that must
|
|
|
|
be sent over the wire to the remove end. Generally that means
|
|
|
|
calling send() or adding the data to your application's output
|
|
|
|
buffer.
|
2009-03-15 16:57:32 +00:00
|
|
|
|
|
|
|
The event->buffer value will contain the bytes to send and the
|
2009-03-19 06:32:04 +00:00
|
|
|
event->size value will contain the number of bytes to send. Note
|
|
|
|
that event->buffer is not NUL terminated, and may include NUL
|
|
|
|
characters in its data, so always use event->size!
|
2009-03-15 16:57:32 +00:00
|
|
|
|
|
|
|
NOTE: Your SEND event handler must send or buffer the data in
|
|
|
|
its raw form as provided by libtelnet. If you wish to perform
|
|
|
|
any kind of preprocessing on data you want to send to the other
|
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
TELNET_EV_IAC:
|
2009-03-15 16:57:32 +00:00
|
|
|
The IAC event is triggered whenever a simple IAC command is
|
2009-03-19 06:32:04 +00:00
|
|
|
received, such as the IAC EOR (end of record, also called go ahead
|
|
|
|
or GA) command.
|
2009-03-14 17:39:07 +00:00
|
|
|
|
2009-03-15 16:57:32 +00:00
|
|
|
The command received is in the event->command value.
|
2009-03-14 17:39:07 +00:00
|
|
|
|
2009-03-15 16:57:32 +00:00
|
|
|
The necessary processing depends on the specific commands; see
|
|
|
|
the TELNET RFC for more information.
|
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
TELNET_EV_WILL:
|
|
|
|
TELNET_EV_DO:
|
|
|
|
The WILL and DO events are sent when a TELNET negotiation command
|
|
|
|
of the same name is received.
|
2009-03-14 17:39:07 +00:00
|
|
|
|
2009-03-16 03:02:10 +00:00
|
|
|
WILL events are sent by the remote end when they wish to be
|
|
|
|
allowed to turn an option on on their end, or in confirmation
|
|
|
|
after you have sent a DO command to them.
|
2009-03-14 17:39:07 +00:00
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
DO events are sent by the remote end when they wish for you to
|
|
|
|
turn on an option on your end, or in confirmation after you have
|
|
|
|
sent a WILL command to them.
|
2009-03-16 03:02:10 +00:00
|
|
|
|
|
|
|
In either case, the TELNET option under negotiation will be in
|
|
|
|
event->telopt field.
|
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
If you support the option and wish for it to be enabled you must
|
|
|
|
set the event->accept field to 1, unless this event is a
|
|
|
|
confirmation for a previous WILL/DO command you sent to the remote
|
|
|
|
end. If you do not set event->field to 1 then libtelnet will send
|
|
|
|
a rejection command back to the other end.
|
2009-03-16 03:02:10 +00:00
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
libtelnet manages some of the pecularities of negotiation for you.
|
|
|
|
For information on libtelnet's negotiation method, see:
|
2009-03-14 17:39:07 +00:00
|
|
|
|
|
|
|
http://www.faqs.org/rfcs/rfc1143.html
|
|
|
|
|
2009-03-16 03:02:10 +00:00
|
|
|
Examples:
|
|
|
|
|
|
|
|
You want remote end to use TTYPE, so you send DO TTYPE.
|
|
|
|
Remote accepts and sends WILL TTYPE.
|
|
|
|
|
|
|
|
Remote end wants you to use SGA, so they send DO_SGA.
|
|
|
|
You do not support SGA and set event->accept = 0.
|
|
|
|
|
|
|
|
Remote end wants to use ZMP, so they send WILL ZMP.
|
|
|
|
You support ZMP, so you set event->accept = 1 and enable
|
|
|
|
local ZMP support.
|
|
|
|
|
|
|
|
You want to use MCCP2, so you send WILL COMPRESS2.
|
|
|
|
Remote end accepts and sends DO COMPRESS2.
|
|
|
|
|
|
|
|
Note that in PROXY mode libtelnet will do no processing of its
|
|
|
|
own for you.
|
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
TELNET_EV_WONT:
|
|
|
|
TELNET_EV_DONT:
|
2009-03-16 03:02:10 +00:00
|
|
|
The WONT and DONT events are sent when the remote end of the
|
2009-03-19 06:32:04 +00:00
|
|
|
connection wishes to disable an option, when they are refusing to
|
|
|
|
a support an option that you have asked for, or in confirmation of
|
|
|
|
an option you have asked to be disabled.
|
2009-03-16 03:02:10 +00:00
|
|
|
|
|
|
|
Most commonly WONT and DONT events are sent as rejections of
|
|
|
|
features you requested by sending DO or WILL events. Receiving
|
|
|
|
these events means the TELNET option is not or will not be
|
|
|
|
supported by the remote end, so give up.
|
|
|
|
|
|
|
|
Sometimes WONT or DONT will be sent for TELNET options that are
|
|
|
|
already enabled, but the remote end wishes to stop using. You
|
|
|
|
cannot decline. These events are demands that must be complied
|
|
|
|
with. libtelnet will always send the appropriate response back
|
|
|
|
without consulting your application. These events are sent to
|
|
|
|
allow your application to disable its own use of the features.
|
|
|
|
|
|
|
|
In either case, the TELNET option under negotiation will be in
|
|
|
|
event->telopt field.
|
|
|
|
|
|
|
|
Note that in PROXY mode libtelnet will do no processing of its
|
|
|
|
own for you.
|
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
TELNET_EV_SUBNEGOTIATION:
|
2009-03-15 16:57:32 +00:00
|
|
|
Triggered whenever a TELNET sub-negotiation has been received.
|
2009-03-14 17:39:07 +00:00
|
|
|
Sub-negotiations include the NAWS option for communicating
|
2009-03-19 06:32:04 +00:00
|
|
|
terminal size to a server, the NEW-ENVIRON and TTYPE options for
|
|
|
|
negotiating terminal features, and MUD-centric protocols such as
|
|
|
|
ZMP, MSSP, and MCCP2.
|
2009-03-14 17:39:07 +00:00
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
The event->telopt value is the option under sub-negotiation. The
|
|
|
|
remaining data (if any) is passed in event->buffer and
|
|
|
|
event->size. Note that most subnegotiation commands can include
|
|
|
|
embedded NUL bytes in the subnegotiation data, and the data
|
|
|
|
event->buffer is not NUL terminated, so always use the event->size
|
|
|
|
value!
|
2009-03-15 16:57:32 +00:00
|
|
|
|
|
|
|
The meaning and necessary processing for subnegotiations are
|
2009-03-19 06:32:04 +00:00
|
|
|
defined in various TELNET RFCs and other informal specifications.
|
|
|
|
A subnegotiation should never be sent unless the specific option
|
|
|
|
has been enabled through the use of the telnet negotiation
|
|
|
|
feature.
|
2009-03-15 16:57:32 +00:00
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
TELNET_EV_COMPRESS
|
2009-03-15 16:57:32 +00:00
|
|
|
The COMPRESS event notifies the app that COMPRESS2/MCCP2
|
|
|
|
compression has begun or ended. Only servers can send compressed
|
|
|
|
data, and hence only clients will receive compressed data.
|
|
|
|
|
|
|
|
The event->command value will be 1 if compression has started and
|
|
|
|
will be 0 if compression has ended.
|
2009-03-15 23:42:03 +00:00
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
TELNET_EV_WARNING
|
|
|
|
The WARNING event is sent whenever something has gone wrong inside
|
|
|
|
of libtelnet (possibly due to malformed data sent by the other
|
|
|
|
end) but which recovery is (likely) possible. It may be safe to
|
|
|
|
continue using the connection, but some data may have been lost or
|
|
|
|
incorrectly interpreted.
|
2009-03-15 16:57:32 +00:00
|
|
|
|
2009-03-15 23:42:03 +00:00
|
|
|
The event->buffer value will contain a NUL terminated string
|
|
|
|
explaining the error, and the event->size value containers the
|
|
|
|
length of the string.
|
2009-03-15 16:57:32 +00:00
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
TELNET_EV_ERROR
|
2009-03-15 23:42:03 +00:00
|
|
|
Similar to the WARNING event, the ERROR event is sent whenever
|
|
|
|
something has gone wrong. ERROR events are non-recoverable,
|
|
|
|
however, and the application should immediately close the
|
2009-03-19 06:32:04 +00:00
|
|
|
connection. Whatever has happened is likely going only to result
|
|
|
|
in garbage from libtelnet. This is most likely to happen when a
|
|
|
|
COMPRESS2 stream fails, but other problems can occur.
|
2009-03-15 16:57:32 +00:00
|
|
|
|
|
|
|
The event->buffer value will contain a NUL terminated string
|
|
|
|
explaining the error, and the event->size value containers the
|
|
|
|
length of the string.
|
|
|
|
|
|
|
|
III. INTEGRATING LIBTELNET WITH COMMON MUDS
|
2009-03-13 03:33:27 +00:00
|
|
|
=====================================================================
|
|
|
|
|
2009-03-15 16:57:32 +00:00
|
|
|
FIXME: fill in some notes about how to splice in libtelnet with
|
|
|
|
common Diku/Merc/Circle/etc. MUD codebases.
|
2009-03-13 03:33:27 +00:00
|
|
|
|
2009-03-14 17:39:07 +00:00
|
|
|
IV. SAFETY AND CORRECTNESS CONSIDERATIONS
|
2009-03-13 03:33:27 +00:00
|
|
|
=====================================================================
|
|
|
|
|
2009-03-14 17:39:07 +00:00
|
|
|
Your existing application may make heavy use of its own output
|
2009-03-19 06:32:04 +00:00
|
|
|
buffering and transmission commands, including hand-made routines for
|
|
|
|
sending TELNET commands and sub-negotiation requests. There are at
|
|
|
|
times subtle issues that need to be handled when communication over
|
|
|
|
the TELNET protocol, not least of which is the need to escape any
|
|
|
|
byte value 0xFF with a special TELNET command.
|
2009-03-13 03:33:27 +00:00
|
|
|
|
2009-03-14 17:39:07 +00:00
|
|
|
For these reasons, it is very important that applications making use
|
2009-03-21 03:08:55 +00:00
|
|
|
of libtelnet always make use of the libtelnet output functions for
|
|
|
|
all data being sent over the TELNET connection.
|
2009-03-14 17:39:07 +00:00
|
|
|
|
2009-03-15 16:57:32 +00:00
|
|
|
In particular, if you are writing a client, all user input must be
|
2009-03-21 03:08:55 +00:00
|
|
|
passed through to telnet_send(). This also includes any input
|
2009-03-19 06:32:04 +00:00
|
|
|
generated automatically by scripts, triggers, or macros.
|
2009-03-15 16:57:32 +00:00
|
|
|
|
|
|
|
For a server, any and all output -- including ANSI/VT100 escape
|
2009-03-19 06:32:04 +00:00
|
|
|
codes, regular text, newlines, and so on -- must be passed through to
|
2009-03-21 03:08:55 +00:00
|
|
|
telnet_send().
|
2009-03-15 16:57:32 +00:00
|
|
|
|
|
|
|
Any TELNET commands that are to be sent must be given to one of the
|
2009-03-21 03:08:55 +00:00
|
|
|
following: telnet_iac, telnet_negotiate, or telnet_subnegotiation().
|
2009-03-15 16:57:32 +00:00
|
|
|
|
|
|
|
If you are attempting to enable COMPRESS2/MCCP2, you must use the
|
2009-03-19 06:32:04 +00:00
|
|
|
telnet_begin_compress2() function.
|
2009-03-15 16:57:32 +00:00
|
|
|
|
2009-03-14 17:39:07 +00:00
|
|
|
V. MCCP2 COMPRESSION
|
2009-03-13 03:33:27 +00:00
|
|
|
=====================================================================
|
|
|
|
|
2009-03-14 17:39:07 +00:00
|
|
|
The MCCP2 (COMPRESS2) TELNET extension allows for the compression of
|
|
|
|
all traffic sent from server to client. For more information:
|
|
|
|
|
|
|
|
http://www.mudbytes.net/index.php?a=articles&s=mccp
|
|
|
|
|
2009-03-15 16:57:32 +00:00
|
|
|
In order for libtelnet to support MCCP2, zlib must be installed and
|
|
|
|
enabled when compiling libtelnet. Use -DHAVE_ZLIB to enable zlib
|
|
|
|
when compiling libtelnet.c and pass -lz to the linker to link in the
|
|
|
|
zlib shared library.
|
|
|
|
|
2009-03-14 17:39:07 +00:00
|
|
|
libtelnet transparently supports MCCP2. For a server to support
|
2009-03-19 06:32:04 +00:00
|
|
|
MCCP2, the application must begin negotiation of the COMPRESS2 option
|
2009-03-21 03:08:55 +00:00
|
|
|
using telnet_negotiate(), for example:
|
2009-03-14 17:39:07 +00:00
|
|
|
|
2009-03-21 03:08:55 +00:00
|
|
|
telnet_negotiate(&telnet, TELNET_WILL,
|
2009-03-19 06:32:04 +00:00
|
|
|
TELNET_OPTION_COMPRESS2, user_data);
|
2009-03-14 17:39:07 +00:00
|
|
|
|
2009-03-16 03:02:10 +00:00
|
|
|
If a favorable DO COMPRESS2 is sent back from the client then the
|
|
|
|
server application can begin compression at any time by calling
|
2009-03-19 06:32:04 +00:00
|
|
|
telnet_begin_compress2().
|
2009-03-14 17:39:07 +00:00
|
|
|
|
2009-03-15 16:57:32 +00:00
|
|
|
If a connection is in PROXY mode and COMPRESS2 support is enabled
|
|
|
|
then libtelnet will automatically detect the start of a COMPRESS2
|
|
|
|
stream, in either the sending or receiving direction.
|
2009-03-14 17:39:07 +00:00
|
|
|
|
|
|
|
VI. TELNET PROXY UTILITY
|
|
|
|
=====================================================================
|
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
The telnet-proxy utility is a small application that serves both as a
|
|
|
|
testbed for libtelnet and as a powerful debugging tool for TELNET
|
2009-03-14 17:39:07 +00:00
|
|
|
servers and clients.
|
|
|
|
|
|
|
|
To use telnet-proxy, you must first compile it using:
|
|
|
|
|
|
|
|
$ make
|
|
|
|
|
|
|
|
If you do not have zlib installed and wish to disable MCCP2 support
|
|
|
|
then you must first edit the Makefile and remove the -DHAVE_ZLIB and
|
|
|
|
the -lz from the compile flags.
|
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
To run telnet-proxy, you simply give it the server's host name or IP
|
|
|
|
address, the server's port number, and the port number that
|
2009-03-15 05:06:17 +00:00
|
|
|
telnet-proxy should listen on. For example, to connect to the server
|
|
|
|
on mud.example.com port 7800 and to listen on port 5000, run:
|
2009-03-14 17:39:07 +00:00
|
|
|
|
2009-03-15 05:06:17 +00:00
|
|
|
$ ./telnet-proxy mud.example.com 7800 5000
|
2009-03-14 17:39:07 +00:00
|
|
|
|
|
|
|
You can then connect to the host telnet-proxy is running on (e.g.
|
2009-03-15 05:06:17 +00:00
|
|
|
127.0.0.1) on port 500 and you will automatically be proxied into
|
|
|
|
mud.example.com.
|
2009-03-14 17:39:07 +00:00
|
|
|
|
2009-03-19 06:32:04 +00:00
|
|
|
telnet-proxy will display status information about the data passing
|
|
|
|
through both ends of the tunnel. telnet-proxy can only support a
|
|
|
|
single tunnel at a time. It will continue running until an error
|
|
|
|
occurs or a terminating signal is sent to the proxy process.
|