windows-nt/Source/XPSP1/NT/inetsrv/iis/svcs/loadbal/driver/ipnat.h

/*++

Copyright (c) 1997, Microsoft Corporation

Module Name:

    ipnat.h

Abstract:

    Contains semi-public IOCTLS and data-structures related to
    the IP Network Address Translator.

Author:

    Abolade Gbadegesin (t-abolag) 11-July-1997

Revision History:

--*/

#ifndef _ROUTING_IP_NAT_H_
#define _ROUTING_IP_NAT_H_


#include <rtinfo.h>             // for RTR_INFO_BLOCK_HEADER
#include <ipinfoid.h>           // for IP_GENERAL_INFO_BASE

//
// Moved to ipinfoid.h
//
// #define IP_NAT_INFO             IP_GENERAL_INFO_BASE + 8


//
// MISCELLANEOUS DECLARATIONS
//

#define IP_NAT_VERSION          1

#define IP_NAT_SERVICE_NAME     "IPNAT"

#define DD_IP_NAT_DEVICE_NAME   L"\\Device\\IPNAT"


//
// IP header protocol-field constants
//

#define NAT_PROTOCOL_ICMP       0x01
#define NAT_PROTOCOL_IGMP       0x02
#define NAT_PROTOCOL_TCP        0x06
#define NAT_PROTOCOL_UDP        0x11
#define NAT_PROTOCOL_PPTP       0x2F



//
// IOCTL DECLARATIONS
//

#define FSCTL_IP_NAT_BASE       FILE_DEVICE_NETWORK

#define _IP_NAT_CTL_CODE(function, method, access) \
    CTL_CODE(FSCTL_IP_NAT_BASE, function, method, access)


//
// NAT-supported IOCTL constant declarations
//

#define IOCTL_IP_NAT_SET_GLOBAL_INFO \
    _IP_NAT_CTL_CODE(0, METHOD_BUFFERED, FILE_WRITE_ACCESS)

#define IOCTL_IP_NAT_GET_GLOBAL_INFO \
    _IP_NAT_CTL_CODE(1, METHOD_BUFFERED, FILE_WRITE_ACCESS)

#define IOCTL_IP_NAT_CREATE_INTERFACE \
    _IP_NAT_CTL_CODE(2, METHOD_BUFFERED, FILE_WRITE_ACCESS)

#define IOCTL_IP_NAT_DELETE_INTERFACE \
    _IP_NAT_CTL_CODE(3, METHOD_BUFFERED, FILE_WRITE_ACCESS)

#define IOCTL_IP_NAT_BIND_INTERFACE \
    _IP_NAT_CTL_CODE(4, METHOD_BUFFERED, FILE_WRITE_ACCESS)

#define IOCTL_IP_NAT_UNBIND_INTERFACE \
    _IP_NAT_CTL_CODE(5, METHOD_BUFFERED, FILE_WRITE_ACCESS)

#define IOCTL_IP_NAT_SET_INTERFACE_INFO \
    _IP_NAT_CTL_CODE(6, METHOD_BUFFERED, FILE_WRITE_ACCESS)

#define IOCTL_IP_NAT_GET_INTERFACE_INFO \
    _IP_NAT_CTL_CODE(7, METHOD_BUFFERED, FILE_WRITE_ACCESS)

#define IOCTL_IP_NAT_REGISTER_EDITOR \
    _IP_NAT_CTL_CODE(8, METHOD_BUFFERED, FILE_WRITE_ACCESS)

#define IOCTL_IP_NAT_GET_INTERFACE_STATISTICS \
    _IP_NAT_CTL_CODE(9, METHOD_BUFFERED, FILE_WRITE_ACCESS)

#define IOCTL_IP_NAT_ENUMERATE_SESSION_MAPPINGS \
    _IP_NAT_CTL_CODE(10, METHOD_BUFFERED, FILE_WRITE_ACCESS)

#define IOCTL_IP_NAT_REGISTER_DIRECTOR \
    _IP_NAT_CTL_CODE(11, METHOD_BUFFERED, FILE_WRITE_ACCESS)



//
// IOCTL_IP_NAT_SET_GLOBAL_INFO
//
// Invoked by the IP router-manager to supply the NAT with its configuration.
//


//
// IOCTL_IP_NAT_GET_GLOBAL_INFO
//
// Invoked by the IP router-manager to retrieve the NAT's configuration.
//


//
// Structure:   IP_NAT_GLOBAL_INFO
//
// Holds global configuration information for the NAT.
//

typedef struct _IP_NAT_GLOBAL_INFO {

    BOOL NATEnabled;            // used by IPRTRMGR
    ULONG TCPTimeoutSeconds;
    ULONG UDPTimeoutSeconds;

} IP_NAT_GLOBAL_INFO, *PIP_NAT_GLOBAL_INFO;




//
// IOCTL_IP_NAT_CREATE_INTERFACE
//
// Invoked by the IP router-manager to add router-interfaces to the NAT.
//


//
// Structure:   IP_NAT_CREATE_INTERFACE
//
// On output, 'NatInterfaceContext' contains the new interface's NAT-created
// context.
//

typedef struct _IP_NAT_CREATE_INTERFACE {

    IN ULONG RtrMgrIndex;
    IN PVOID RtrMgrContext;
    OUT PVOID NatInterfaceContext;

} IP_NAT_CREATE_INTERFACE, *PIP_NAT_CREATE_INTERFACE;




//
// IOCTL_IP_NAT_DELETE_INTERFACE
//
// Invoked by the IP router-manager to delete router-interfaces from the NAT.
//

//
// Structure:   IP_NAT_DELETE_INTERFACE
//
// On input, 'NatInterfaceContext' should contain the context for the interface
// to be deleted, as obtained from IOCTL_IP_NAT_CREATE_INTERFACE.
//

typedef struct _IP_NAT_DELETE_INTERFACE {

    IN PVOID NatInterfaceContext;

} IP_NAT_DELETE_INTERFACE, *PIP_NAT_DELETE_INTERFACE;




//
// IOCTL_IP_NAT_BIND_INTERFACE
//
// Invoked by the IP router-manager to set the interface's binding.
//

//
// Structure:   IP_NAT_BIND_INTERFACE
//
// Holds the binding for the specified interface.
// The field 'BindingInfo' should be the beginning of
// an IP_ADAPTER_BINDING_INFO structure (see routprot.h) which
// contains the interface's binding.
//

typedef struct _IP_NAT_BIND_INTERFACE {

    IN PVOID NatInterfaceContext;
    IN ULONG BindingInfo[1];

} IP_NAT_BIND_INTERFACE, *PIP_NAT_BIND_INTERFACE;





//
// IOCTL_NAT_UNBIND_INTERFACE
//
// Invoked by the IP router-manager to remove binding from an interface.
//


//
// Structure:   IP_NAT_UNBIND_INTERFACE
//
// Used to indicate to the NAT which interface should be unbound.
//

typedef struct _IP_NAT_UNBIND_INTERFACE {

    IN PVOID NatInterfaceContext;

} IP_NAT_UNBIND_INTERFACE, *PIP_NAT_UNBIND_INTERFACE;




//
// IOCTL_IP_NAT_SET_INTERFACE_INFO
//
// Invoked by the IP router-manager to set configuration information
// on boundary-interfaces, i.e. interfaces over which translation takes place.
//
// Uses 'IP_NAT_INTERFACE_INFO' for input.
//

//
// IOCTL_IP_NAT_GET_INTERFACE_INFO
//
// Invoked by the IP router-manager to get configuration information on
// boundary interfaces.
//
// uses 'IP_NAT_INTERFACE_INFO' for input and output.
//

// 
// Structure:   IP_NAT_INTERFACE_INFO
//
// 'NatInterfaceContext' identifies the interface to be configured or whose
// configuration is being retrieved, and is the context supplied on output from
// 'IOCTL_IP_NAT_CREATE_INTERFACE'.
//
// The configuration information uses the RTR_INFO_BLOCK_HEADER structure
// of rtinfo.h. See below for the type-codes for structures which may appear
// after IP_NAT_INTERFACE_INFO.Header within the RTR_TOC_ENTRY.InfoType field.
//

typedef struct _IP_NAT_INTERFACE_INFO {

    IN PVOID NatInterfaceContext;
    IN ULONG Flags;
    IN RTR_INFO_BLOCK_HEADER Header;

} IP_NAT_INTERFACE_INFO, *PIP_NAT_INTERFACE_INFO;



//
// Flags for IP_NAT_INTERFACE_INFO.Flags
//
// _BOUNDARY: set to mark interface as boundary-interface.
// _NAPT: set to enable address-sharing via port-translation.
//

#define IP_NAT_INTERFACE_FLAGS_BOUNDARY 0x00000001

#define IP_NAT_INTERFACE_FLAGS_NAPT     0x00000002

#define IP_NAT_INTERFACE_FLAGS_ALL      0x00000003



//
// Type-codes for the IP_NAT_INTERFACE_INFO.Header.TocEntry[] array.
//
// The structures which correspond to each info-type are given below.
//

#define IP_NAT_PORT_RANGE_TYPE          IP_GENERAL_INFO_BASE + 1
#define IP_NAT_ADDRESS_RANGE_TYPE       IP_GENERAL_INFO_BASE + 2
#define IP_NAT_PORT_MAPPING_TYPE        IP_GENERAL_INFO_BASE + 3
#define IP_NAT_ADDRESS_MAPPING_TYPE     IP_GENERAL_INFO_BASE + 4


//
// Structure:   IP_NAT_PORT_RANGE
//
// Holds a range of port numbers which the NAT is allowed to use
// on a boundary interface.
//
// In the case of an interface with a pool of addresses, 'PublicAddress'
// should specify which of those addresses this static-mapping applies to.
//

typedef struct _IP_NAT_PORT_RANGE {

    UCHAR Protocol;
    ULONG PublicAddress;  // OPTIONAL - see IP_NAT_ADDRESS_UNSPECIFIED
    USHORT StartPort;
    USHORT EndPort;

} IP_NAT_PORT_RANGE, *PIP_NAT_PORT_RANGE;



//
// Structure:   IP_NAT_ADDRESS_RANGE
//
// Holds a range of addresses which are part of the address-pool
// for a boundary interface.
//
// An address-pool consists of a list of these structures.
//
// Note: overlapping address-ranges are not supported;
//  discontiguous subnet masks are also unsupported.
//

typedef struct _IP_NAT_ADDRESS_RANGE {

    ULONG StartAddress;
    ULONG EndAddress;
    ULONG SubnetMask;

} IP_NAT_ADDRESS_RANGE, *PIP_NAT_ADDRESS_RANGE;



//
// Structure:   IP_NAT_PORT_MAPPING
//
// Holds a static mapping which ties a public-side port on this NAT interface
// to a particular private machine's address/port.
//
// In the case of an interface with a pool of addresses, 'PublicAddress'
// should specify which of those addresses this static-mapping applies to.
//

typedef struct _IP_NAT_PORT_MAPPING {

    UCHAR Protocol;
    USHORT PublicPort;
    ULONG PublicAddress;  // OPTIONAL - see IP_NAT_ADDRESS_UNSPECIFIED
    USHORT PrivatePort;
    ULONG PrivateAddress;

} IP_NAT_PORT_MAPPING, *PIP_NAT_PORT_MAPPING;


//
// Constant for 'PublicAddress' in IP_NAT_PORT_RANGE and IP_NAT_PORT_MAPPING;
// may be specified for boundary-interfaces which have no address-pool, in
// which case the range/mapping is for the boundary-interface's sole address.
//

#define IP_NAT_ADDRESS_UNSPECIFIED  ((ULONG)0)


//
// Structure:   IP_NAT_ADDRESS_MAPPING
//
// Holds a static mapping which ties an address from this NAT interface's
// address pool to a particular private-machine's address.
//
// Note that this address must fall within one of the ranges comprising
// the pool as specified by the IP_NAT_ADDRESS_RANGE structures.
//

typedef struct _IP_NAT_ADDRESS_MAPPING {

    ULONG PrivateAddress;
    ULONG PublicAddress;
    BOOL AllowInboundSessions;

} IP_NAT_ADDRESS_MAPPING, *PIP_NAT_ADDRESS_MAPPING;




//
// IOCTL_IP_NAT_REGISTER_EDITOR
//
// This IOCTL is invoked by a kernel-mode component which wishes to act
// as an editor for packets which match a particular session-description.
//

//
// Enum:        IP_NAT_DIRECTION
//
// Lists the session-flow directions for which an editor may register.
// IpNatInbound refers to the 'public-to-private' flow, while 
// IpNatOutbound refers to the 'private-to-public' flow.
//

typedef enum _IP_NAT_DIRECTION {

    IpNatInbound = 0,
    IpNatOutbound = 1

} IP_NAT_DIRECTION, *PIP_NAT_DIRECTION;


//
// Editor function prototypes
//

//
// For synchronization reasons, 'CreateHandler' and 'DeleteHandler' 
// CANNOT invoke any helper functions other than 'QueryInfoSession'.
//

typedef NTSTATUS
(*PNAT_EDITOR_CREATE_HANDLER)(
    IN PVOID EditorContext,
    IN ULONG PrivateAddress,
    IN USHORT PrivatePort,
    IN ULONG PublicAddress,
    IN USHORT PublicPort,
    IN ULONG RemoteAddress,
    IN USHORT RemotePort,
    OUT PVOID* EditorSessionContextp   OPTIONAL
    );

typedef NTSTATUS
(*PNAT_EDITOR_DELETE_HANDLER)(
    IN PVOID InterfaceHandle,
    IN PVOID SessionHandle,
    IN PVOID EditorContext,
    IN PVOID EditorSessionContext
    );

typedef NTSTATUS
(*PNAT_EDITOR_DATA_HANDLER)(
    IN PVOID InterfaceHandle,
    IN PVOID SessionHandle,
    IN PVOID DataHandle,
    IN PVOID EditorContext,
    IN PVOID EditorSessionContext,
    IN PVOID RecvBuffer,
    IN ULONG DataOffset
    );


//
// Helper function prototypes
//

typedef NTSTATUS
(*PNAT_HELPER_CREATE_TICKET)(
    IN PVOID InterfaceHandle,
    IN UCHAR Protocol,
    IN ULONG PrivateAddress,
    IN USHORT PrivatePort,
    IN ULONG TimeoutSeconds,
    OUT PULONG PublicAddress,
    OUT PUSHORT PublicPort
    );

typedef NTSTATUS
(*PNAT_HELPER_DELETE_TICKET)(
    IN PVOID InterfaceHandle,
    IN ULONG PublicAddress,
    IN UCHAR Protocol,
    IN USHORT PublicPort
    );

typedef NTSTATUS
(*PNAT_HELPER_DEREGISTER_EDITOR)(
    IN PVOID EditorHandle
    );


typedef NTSTATUS
(*PNAT_HELPER_DISSOCIATE_SESSION)(
    IN PVOID EditorHandle,
    IN PVOID SessionHandle
    );

typedef NTSTATUS
(*PNAT_HELPER_EDIT_SESSION)(
    IN PVOID DataHandle,
    IN PVOID RecvBuffer,
    IN ULONG OldDataOffset,
    IN ULONG OldDataLength,
    IN PUCHAR NewData,
    IN ULONG NewDataLength
    );

typedef VOID
(*PNAT_HELPER_QUERY_INFO_SESSION)(
    IN PVOID SessionHandle,
    IN PULONG PrivateAddress  OPTIONAL,
    IN PUSHORT PrivatePort     OPTIONAL,
    IN PULONG RemoteAddress   OPTIONAL,
    IN PUSHORT RemotePort      OPTIONAL,
    IN PULONG PublicAddress   OPTIONAL,
    IN PUSHORT PublicPort      OPTIONAL
    );

typedef VOID
(*PNAT_HELPER_TIMEOUT_SESSION)(
    IN PVOID EditorHandle,
    IN PVOID SessionHandle
    );


//
// Structure:   IP_NAT_REGISTER_EDITOR
//
// The editor uses this structure to register itself with the NAT,
// and to obtain entrypoints of helper-functions provided by the NAT.
//
// On input, 'EditorContext' should contain a value which the NAT will
// pass to the editor's provided functions to serve as identification.
//
// On output, 'EditorHandle' contains the handle which the editor should
// pass to the NAT's helper functions to identify itself.
// 

typedef struct _IP_NAT_REGISTER_EDITOR {

    IN ULONG Version;
    IN ULONG Flags;
    IN UCHAR Protocol;
    IN USHORT Port;
    IN IP_NAT_DIRECTION Direction;

    IN PVOID EditorContext;

    IN PNAT_EDITOR_CREATE_HANDLER CreateHandler;            // OPTIONAL
    IN PNAT_EDITOR_DELETE_HANDLER DeleteHandler;            // OPTIONAL
    IN PNAT_EDITOR_DATA_HANDLER InboundDataHandler;         // OPTIONAL
    IN PNAT_EDITOR_DATA_HANDLER OutboundDataHandler;        // OPTIONAL

    OUT PVOID EditorHandle;

    OUT PNAT_HELPER_CREATE_TICKET CreateTicket;
    OUT PNAT_HELPER_DELETE_TICKET DeleteTicket;
    OUT PNAT_HELPER_DEREGISTER_EDITOR Deregister;
    OUT PNAT_HELPER_DISSOCIATE_SESSION DissociateSession;
    OUT PNAT_HELPER_EDIT_SESSION EditSession;
    OUT PNAT_HELPER_QUERY_INFO_SESSION QueryInfoSession;
    OUT PNAT_HELPER_TIMEOUT_SESSION TimeoutSession;

} IP_NAT_REGISTER_EDITOR, *PIP_NAT_REGISTER_EDITOR;


#define IP_NAT_EDITOR_FLAGS_RESIZE      0x00000001


//
// IOCTL_IP_NAT_REGISTER_DIRECTOR
//
// This IOCTL is invoked by a kernel-mode component that wishes to be consulted
// about the direction of incoming TCP/UDP sessions.
// 
// Such a component, if installed, is consulted by the NAT
// to determine dynamically how to direct inbound sessions. The module
// could, for instance, be installed to direct sessions destined for
// a cluster of HTTP servers in such a way as to balance the load across
// the servers via round-robin or other means.
//

//
// Director function prototypes
//

typedef NTSTATUS
(*PNAT_DIRECTOR_QUERY_SESSION)(
    IN PVOID DirectorContext,
    IN UCHAR Protocol,
    IN ULONG PublicAddress,
    IN USHORT PublicPort,
    IN ULONG RemoteAddress,
    IN USHORT RemotePort,
    OUT PULONG PrivateAddress,
    OUT PUSHORT PrivatePort,
    OUT PVOID* Contextp OPTIONAL
    );

typedef NTSTATUS
(*PNAT_DIRECTOR_DELETE_SESSION)(
    IN PVOID SessionHandle,
    IN PVOID DirectorContext,
    IN PVOID DirectorSessionContext
    );

//
// Director-helper function prototypes
//

typedef NTSTATUS
(*PNAT_HELPER_DEREGISTER_DIRECTOR)(
    IN PVOID DirectorHandle
    );


//
// Structure:   IP_NAT_REGISTER_DIRECTOR
//
// The director uses this structure to register itself with the NAT.
//

typedef struct _IP_NAT_REGISTER_DIRECTOR {

    IN ULONG Version;
    IN ULONG Flags;
    IN UCHAR Protocol;
    IN USHORT Port;

    IN PVOID DirectorContext;

    IN PNAT_DIRECTOR_QUERY_SESSION QueryHandler;
    IN PNAT_DIRECTOR_DELETE_SESSION DeleteHandler;

    OUT PVOID DirectorHandle;
    OUT PNAT_HELPER_QUERY_INFO_SESSION QueryInfoSession;
    OUT PNAT_HELPER_DEREGISTER_DIRECTOR Deregister;

} IP_NAT_REGISTER_DIRECTOR, *PIP_NAT_REGISTER_DIRECTOR;



//
// IOCTL_IP_NAT_GET_INTERFACE_STATISTICS
//
// This IOCTL is invoked to retrieve per-interface statistics.
//


//
// Structure:   IP_NAT_INTERFACE_STATISTICS
//
// Used for retrieving statistics. On input, 'NatInterfaceContext'
// should contain the context of the NAT interface whose statistics
// are to be obtained.
//

typedef struct _IP_NAT_INTERFACE_STATISTICS {

    IN PVOID NatInterfaceContext;
    OUT ULONG TotalMappings;
    OUT ULONG InboundMappings;
    OUT ULONG InboundPacketsRejected;
    OUT ULONG OutboundPacketsRejected;

} IP_NAT_INTERFACE_STATISTICS, *PIP_NAT_INTERFACE_STATISTICS;



//
// IOCTL_IP_NAT_ENUMERATE_SESSION_MAPPINGS
//
// This IOCTL is invoked to enumerate the dynamic TCP and UDP mappings
// for an interface.
//

//
// Structure:   IP_NAT_SESSION_MAPPING
//
// This structure holds information for a single mapping
//

typedef struct _IP_NAT_SESSION_MAPPING {

    IP_NAT_DIRECTION Direction;
    UCHAR Protocol;       // see NAT_PROTOCOL_* above
    ULONG PrivateAddress;
    USHORT PrivatePort;
    ULONG PublicAddress;
    USHORT PublicPort;
    ULONG RemoteAddress;
    USHORT RemotePort;
    ULONG IdleTime;       // in seconds
    
} IP_NAT_SESSION_MAPPING, *PIP_NAT_SESSION_MAPPING;


//
// Structure:   IP_NAT_ENUMERATE_SESSION_MAPPINGS
//
// Used for enumerate session mappings. On input, 'NatInterfaceContext'
// should hold the context for the interface whose mappings are to be
// enumerated. On the first call to this routine, 'EnumerateContext'
// should be zeroed out; it will be filled by the NAT with information
// to be passed back down as the enumeration continues. To indicate
// there are no items remaining, the NAT will set EnumerateContext[0] to 0.
//

typedef struct _IP_NAT_ENUMERATE_SESSION_MAPPINGS {

    IN PVOID NatInterfaceContext;
    IN OUT ULONG EnumerateContext[4];
    OUT ULONG EnumerateCount;
    OUT IP_NAT_SESSION_MAPPING EnumerateTable[1];
    
} IP_NAT_ENUMERATE_SESSION_MAPPINGS, *PIP_NAT_ENUMERATE_SESSION_MAPPINGS;



#endif // _ROUTING_IP_NAT_H_