GnuDIP Remote User Maintenance Protocol

Here we describe the remote user maintenance protocol provided by the gdiprmaint.pl (X)INETD daemon, and which is used by the gdiprmclt.pl client script.

ASCII is (of course) used for representing printable characters.

The client makes a TCP connection to the appropriate port on the server host. There is no standard port. Each GnuDIP site should choose its own.

As soon as the connection is established the server will send a randomly generated 10 character "salt" string. The manner in which this is used depends on whether the maintenance message is sent in unencrypted or encrypted form.

Unencrypted Form

In this case the maintenance request and response messages are not encrypted, but the remote maintenance access password (a value known both to the server and the client) is still protected. The random salt is used in this process in a way that prevents the possibility of "spoofing" the server by replaying requests.

The random salt sent by the server is used in the following algorithm for hashing the password:

Digest the remote maintenance access password using the MD5 digest message digest algorithm. Convert the digest value (which is a binary value) to its hexadecimal character string representation (characters 0-9 and lower case a-f).
Append a period (".") and the salt value to create a longer character string.
Digest this longer character string and convert it to its hexadecimal character representation.

The message character string is then transmited to the GnuDIP server. It is sent as several lines using a single new line character as the line ending. The general form is:

0
hashed_password
maintenance_request_line_1
maintenance_request_line_2
   *
   *
maintenance_request_line_n
end

The response from the server will in most cases be single line containing a response code:

response_code

For a response code of zero to a get request, there will also be two or more data lines:

0
get_response_line_1
get_response_line_2
   *
   *
get_response_line_n
end

The format of maintenance requests and responses to a "get" is explained below, along with the possible response codes.

Encrypted Form

In this case the maintenance request and response messages are both encrypted with Blowfish encryption using a key known both to the server and the client. This random salt sent by the server is included in the encrpyted request message to prevent the possibility of "spoofing" the server by replaying requests.

Note:

The Blowfish encryption option is not yet implemented.
It probably never will be either, since encryption over the public Internet is easily done using Stunnel.

The encrypted request is then converted from binary form to its character hexadecimal representation, using the digits and the lower case letters "a", "b", "c", "d", "e" and "f". The message character string is then transmited to the GnuDIP server. It is sent as two lines using a single new line character as the line ending. The general form is:

1
encrypted_message_as_hex_on_one_line

Before being encrypyted, the message that gets encrypted and placed in the second line above consists of several lines using single new line character as the line ending, with this form:

random_salt
maintenance_request_line_1
maintenance_request_line_2
   *
   *
maintenance_request_line_n

The response from the server will in most cases be single line containing a response code:

response_code

For a response code of zero to a get request, there will also be an encrypted data line:

0
encrypted_get_response_as_hex_on_one_line

Before being encrypyted, the get response that gets encrypted and placed in the second line above consists of several lines using single new line character as the line ending, with this form:

get_response_line_1
get_response_line_2
   *
   *
get_response_line_n

The format of maintenance requests and responses to a "get" is explained below, along with the possible response codes.

Maintenance Requests, Response Codes and Get Responses

These requests correspond precisely at a semantic level to the user maintenance commands described in maintenance_commands.html.

A request consists of several lines using a single new line character as the line ending. The general form is:

command
parameter_1=value_1
parameter_2=value_2
   *
   *
parameter_n=value_n

The number of parameter/value pairs will vary. The "command" is one of:

get
add
mod
del

The response from to successful get request consists of two or more data lines:

parameter_1=value_1
parameter_2=value_2
   *
   *
parameter_n=value_n

We now describe the exchange for each command in more detail:

get

In this case the request will be of the form:

get
user=user_name
domain=domain_name

If the specified user name is registered for the specified domain, the get will succeed and the response will be similiar to:

MXbackup = NO
wildcard = NO
password = 34e24c964fa7adfb317e2444a94c4357
forwardurl =
allowmx = NO
MXvalue =
autourlon =
level = USER
currentip = 127.0.0.1
username = rob
allowwild = NO
updated = 2002-05-22 14:39:07
domain = dyn.yourhost.com
email = rob@elsewhere.com

The response codes are:

0 - User existed - get response returned
1 - User did not exist
2 - Invalid request - look for GnuDIP log messages

add

In this case the full message will be of the form:

add
user=user_name
domain=domain_name
password=clear_text_password
email=email_address

The "password" or "email" parameters may be omitted.

The response codes are:

0 - User did not exist - user was added
1 - User already existed
2 - Invalid request - look for GnuDIP log messages

mod

In this case the full message will be of the form:

mod
user=user_name
domain=domain_name
password=clear_text_password
hashedpw=MD5_hashed_password
email=email_address
allowwild={YES|NO}
allowmx={YES|NO}
removedns=YES

Any of the "password", "hashedpw", "email", "allowwild", "allowmx" or "removedns" parameters may be omitted.

The response codes are:

0 - User existed - user was updated
1 - User did not exist
2 - Invalid request - look for GnuDIP log messages

del

In this case the full message will be of the form:

del
user=user_name
domain=domain_name

The response codes are:

0 - User existed - user was deleted
1 - User did not exist
2 - Invalid request - look for GnuDIP log messages