# 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