/// <reference path="../../../third_party/typings/browser.d.ts" />
import net = require('../net/net.types');
/**
 * Utilities for decoding and encoding STUN messages.
 * TURN uses STUN messages, adding some methods and attributes.
 *
 * http://tools.ietf.org/html/rfc5389#section-6
 */
/** A STUN/TURN message, used for requests and responses. */
export interface StunMessage {
    method: MessageMethod;
    clazz: MessageClass;
    transactionId: Uint8Array;
    attributes: StunAttribute[];
}
/** A STUN/TURN attribute, which carries data in a message. */
export interface StunAttribute {
    type: number;
    value?: Uint8Array;
}
/**
 * Primary purpose of a request.
 * The values here are a subset of what's defined for STUN and TURN.
 * STUN only defines one method: BIND.
 * TURN adds several more methods:
 *   http://tools.ietf.org/html/rfc5766#section-13
 */
export declare enum MessageMethod {
    BIND = 1,
    ALLOCATE = 3,
    REFRESH = 4,
    SEND = 6,
    DATA = 7,
    CREATE_PERMISSION = 8,
    CHANNEL_BIND = 9,
}
/**
 * This is orthogonal to method. Probably best to read:
 *   http://tools.ietf.org/html/rfc5389#section-6
 */
export declare enum MessageClass {
    REQUEST = 1,
    SUCCESS_RESPONSE = 2,
    FAILURE_RESPONSE = 3,
    INDICATION = 4,
}
/**
 * STUN/TURN attributes in which we are interested:
 *   http://tools.ietf.org/html/rfc5389#section-15
 *   http://tools.ietf.org/html/rfc5766#section-14
 */
export declare enum MessageAttribute {
    MAPPED_ADDRESS = 1,
    USERNAME = 6,
    MESSAGE_INTEGRITY = 8,
    ERROR_CODE = 9,
    XOR_PEER_ADDRESS = 18,
    DATA = 19,
    REALM = 20,
    NONCE = 21,
    XOR_RELAYED_ADDRESS = 22,
    REQUESTED_TRANSPORT = 25,
    XOR_MAPPED_ADDRESS = 32,
    LIFETIME = 13,
    /**
     * This attribute is appended to messages sent from one side of the
     * TURN server to the other. For performance reasons we do not always
     * strip this attribute before a message is relayed to a client; the
     * value chosen lies within the "comprehension-optional" and undefined
     * ranges which means that TURN clients should feel free to ignore it
     * and the attribute should not interfere with ICE:
     *   http://tools.ietf.org/html/rfc5389#section-18.2
     *   http://www.iana.org/assignments/stun-parameters/stun-parameters.xhtml
     */
    IPC_TAG = 61183,
}
/**
 * Username with which our HMAC_KEY was generated. Clients will need to use
 * this to access the server.
 */
export declare var USERNAME: string;
/**
 * Password with which our HMAC_KEY was generated. Clients will need to use
 * this to access the server.
 */
export declare var PASSWORD: string;
/**
 * Realm for this server. Has no real meaning -- but this is used as part of
 * message signing (see HMAC_KEY).
 */
export declare var REALM: string;
/**
 * Parses a byte array, returning a StunMessage object.
 * Throws an error if this is not a STUN request.
 */
export declare function parseStunMessage(bytes: Uint8Array): StunMessage;
/**
 * Constructs a byte array from a StunMessage object.
 */
export declare function formatStunMessage(message: StunMessage): Uint8Array;
/**
 * As formatStunMessage() but appends a MESSAGE-INTEGRITY attribute.
 * Normally, this is the function you should call; the exceptions are tests
 * and send/data indications (which do not require a checksum).
 */
export declare function formatStunMessageWithIntegrity(message: StunMessage): Uint8Array;
/**
 * Computes the hash for the MESSAGE-INTEGRITY attribute:
 *   http://tools.ietf.org/html/rfc5389#section-15.4
 *
 * From the RFC:
 *   "The text used as input to HMAC is the STUN message, including
 *   the header, up to and including the attribute preceding the
 *   MESSAGE-INTEGRITY attribute."
 *
 * The supplied bytes should be a STUN message, including a MESSAGE-INTEGRITY
 * attribute (which must be the final attribute), with length including that
 * attribute.
 *
 * Callers of this method should copy the computed hash into the
 * supplied byte array.
 */
export declare function computeHash(bytes: Uint8Array): Uint8Array;
/**
 * Converts the supplied attribute to bytes, placing the result in the
 * supplied byte array. Throws an error if the byte array is too small
 * to contain the attribute but otherwise ignores any trailing bytes.
 */
export declare function formatStunAttribute(attr: StunAttribute, bytes: Uint8Array): number;
/**
 * Parses a STUN attribute:
 *   http://tools.ietf.org/html/rfc5389#section-15
 */
export declare function parseStunAttribute(bytes: Uint8Array): StunAttribute;
/**
 * Returns bytes suitable for use in a ERROR_CODE-typed StunAttribute:
 *   http://tools.ietf.org/html/rfc5389#section-15.6
 */
export declare function formatErrorCodeAttribute(code: number, reason: string): Uint8Array;
/**
 * Returns bytes suitable for use in a MAPPED-ADDRESS attribute:
 *   http://tools.ietf.org/html/rfc5389#section-15.1
 * Although we never send MAPPED-ADDRESS attributes, this function is
 * useful for testing and formatting XOR-MAPPED-ADDRESS attributes.
 * TODO: support IPv6 (assumes IPv4)
 */
export declare function formatMappedAddressAttribute(address: string, port: number): Uint8Array;
/**
 * Parses a MAPPED-ADDRESS attribute:
 *   http://tools.ietf.org/html/rfc5389#section-15.1
 * Again, although we never parse MAPPED-ADDRESS attributes, this function is
 * useful for testing and for parsing XOR-MAPPED-ADDRESS attributes.
 * TODO: support IPv6 (assumes IPv4)
 */
export declare function parseMappedAddressAttribute(bytes: Uint8Array): net.Endpoint;
/**
 * Parses an XOR-MAPPED-ADDRESS attribute:
 *   http://tools.ietf.org/html/rfc5389#section-15.2
 * TODO: support IPv6 (assumes IPv4)
 */
export declare function parseXorMappedAddressAttribute(bytes: Uint8Array): net.Endpoint;
/**
 * Returns bytes suitable for use in XOR-MAPPED-ADDRESS and
 * XOR-RELAYED-ADDRESS attributes:
 *   http://tools.ietf.org/html/rfc5389#section-15.2
 * TODO: support IPv6 (assumes IPv4)
 */
export declare function formatXorMappedAddressAttribute(address: string, port: number): Uint8Array;
/**
 * Returns the first attribute in the supplied array having the
 * specified type. Raises an error if the attribute is not found.
 */
export declare function findFirstAttributeWithType(type: MessageAttribute, attributes: StunAttribute[]): StunAttribute;
/** Rounds x up to the nearest b, e.g. calculatePadding(5, 4) == 8. */
export declare function calculatePadding(x: number, b: number): number;