Chapter 1. Introduction

The DDTP protocol is used for remote athenticated DNS updates via UDP. Two types of packets are defined in the protocol: update and keepalive operations. The updates contain one of the three possible states for an host: online, offline and static, the IP address (if applicable) of the host and the account ID and password for authentication. These queries are encrypted in blowfish using as key the md5 hash of the user's password. The user's password must be obtained in a secure manner which is usually at registration with an https server. The second type of packets (keepalive) is used by the server to verify that a given user is still online. These queries are not encrypted now but may be in a future version of the protocol.

Here's how a communication occurs. The client sends an update query with a status. The server receives the query, parses it and returns either an error or confirmation message. The server is responsible for sending keepalive queries to the clients on a regular basis to verify their status. The client returns an alive reply upon reception of the query to signify its presence on the network.

Chapter 2. Packets

There are five possible messages: update query, update reply, alive queries, alive replies and status. The client is allowed to send only update query and alive reply. The server on his side is responsible for update replies, alive queries and status packets. All packets structures are represented in the packets.x file included below.

-- FIXME Here goes a clear description of opcodes and packet structures. The .x file is probably not best suited for the spec file.

/* Update Query and Reply */
enum DDTPv1UpdateQueryOpCode
{
    MARK_ONLINE,
    MARK_OFFLINE
};

struct DDTPv1UpdateQuery
{
    DDTPv1UpdateQueryOpCode opCode;
    unsigned long           ipAddress;
    opaque                  updatePassword[9];
};

enum DDTPv1UpdateReplyStatus
{
    UPDATE_SUCCEEDED,
    UPDATE_FAILED,
    INVALID_PASSWORD,
    INVALID_ACCOUNT,
    INVALID_OPCODE
};

struct DDTPv1UpdateReply
{
    DDTPv1UpdateReplyStatus status;
};

/* Alive Query and Reply */
struct DDTPv1AliveQuery
{
    int dummy;
};

struct DDTPv1AliveReply
{
    int dummy;
};

/****** ******/
enum DDTPv1MessageType
{
    MESSAGE_ERROR,
    UPDATE_QUERY,
    UPDATE_REPLY,
    ALIVE_QUERY,
    ALIVE_REPLY
};

enum DDTPv1MessageStatus
{
    INVALID_MESSAGE_TYPE
};

union DDTPv1Message switch (DDTPv1MessageType messageType)
{
    case UPDATE_QUERY:
        DDTPv1UpdateQuery   updateQuery;
    case UPDATE_REPLY:
        DDTPv1UpdateReply   updateReply;
    case ALIVE_QUERY:
        DDTPv1AliveQuery    aliveQuery;
    case ALIVE_REPLY:
        DDTPv1AliveReply    aliveReply;
    default:
        DDTPv1MessageStatus status;
};

/****** ******/
struct DDTPv1Plaintext
{
    int             accountId;
    DDTPv1Message   msg;
};

struct DDTPv1Blowfish
{
    int             accountId;      /* DDT user account ID                  */
    opaque          msg[64];        /* blowfish encrypted DDTPv1Message     */
                                    /* ensure that this is big enough to    */
                                    /* hold the entire encrypted message    */
    opaque          iv[8];          /* blowfish cbc initialization vector   */
    opaque          check[8];       /* the iv encrypted -- encryption check */
};

/****** ******/
enum EncryptionType
{
    ENCRYPTION_ERROR,
    PLAINTEXT,
    BLOWFISH
};

enum DDTPv1PacketStatus
{
    INVALID_ENCRYPTION_TYPE,
    ACCOUNT_INVALID,
    PASSWORD_INVALID,
    XDR_DECODE_FAILURE
};

union DDTPv1Packet switch (EncryptionType encryptionType)
{
    case PLAINTEXT:
        DDTPv1Plaintext     pt;
    case BLOWFISH:
        DDTPv1Blowfish      bf;
    default:
        DDTPv1PacketStatus  status;
};

/****** ******/
enum ProtocolVersion
{
    PROTOCOL_ERROR,
    DDTPv1,
    DDTPv2
};

enum DdtpPacketStatus
{
    INVALID_PROTOCOL
};

union DdtpPacket switch (ProtocolVersion protocolVersion)
{
    case DDTPv1:
        DDTPv1Packet ddtpv1;
    /* case DDTPv2:                 */
    /*     DDTPv2Packet ddtpv2;     */
    default:
        DdtpPacketStatus status;
};