6.2. ATM Overview

ATM is an emerging high-speed networking technology which is applicable to both LAN and WAN arenas. An ATM network simultaneously transports a wide variety of network traffic -- voice, data, image, and video. It provides users with a guaranteed quality of service on a per Virtual Channel (VC) basis.

A new address family, AF_ATM, is introduced for native ATM services, and the corresponding "sockaddr" structure, sockaddr_atm, is defined below. To open a socket for native ATM services, parameters in socket() should contain "AF_ATM", "SOCK_RAW", and "ATMPROTO_AAL5" or "ATMPROTO_AALUSER", respectively.

struct sockaddr_atm {

u_short satm_family; /* address family should be AF_ATM */

ATM_ADDRESS satm_number; /* ATM address */

ATM_BLLI satm_blli; /* B-LLI */

ATM_BHLI satm_bhli; /* B-HLI */

};

Identifies the address family, which is AF_ATM in this case.

Identifies the ATM address which could be either in E.164 or NSAP-style ATM End Systems Address format. See next section for more details about the ATM_ADDRESS structure. This field will be mapped to the Called Party Number IE(Information Element) if it is specified in bind()/WSPBind() for a listening socket, or in connect()/WSAConnect()/WSPConnect()/WSAJoinLeaf()/WSPJoinLeaf() for a connecting socket. It will be mapped to the Calling Party Number IE if specified in bind()/WSPBind() for a connecting socket.

Identifies the fields in the B-LLI Information Element which are used along with satm_bhli to identify an application. See the section below for more details about the ATM_BLLI structure. Note that the BLLI layer 2 information is treated as not present if its Layer2Protocol field contains "SAP_FIELD_ABSENT", or wildcard if it contains "SAP_FIELD_ANY". Similarly, the BLLI layer 3 information is treated as not present if its Layer3Protocol field contains "SAP_FIELD_ABSENT", or wildcard if it contains "SAP_FIELD_ANY".

Identifies the fields in the B-HLI Information Element which are used along with satm_blli to identify an application. See the section below for more details about the ATM_BHLI structure. Note that satm_bhli is treated as not present if its HighLayerInfoType field contains "SAP_FIELD_ABSENT", or wildcard if it contains "SAP_FIELD_ANY".

For listening sockets, the sockaddr_atm structure is used in bind()/WSPBind() to register a Service Access Point (SAP) to receive incoming connection requests destined to this SAP. SAP registration is used to match against the SAP specified in an incoming connection request in order to determine which listening socket to receive this request. In current version of this specification, overlapping registration is not allowed. Overlapping registration is defined as having more than one registered SAP to potentially match the SAP specified in any incoming connection request. listen()/WSPListen() will return the error code WSAEADDRINUSE if the SAP associated with the listening socket overlaps with any currently registered SAPs in the system.

The fields in a SAP to be registered must contain either a valid value, or one of two special manifest constants: "SAP_FIELD_ABSENT", or "SAP_FIELD_ANY". "SAP_FIELD_ABSENT" simply means that this field is not presented as part of a SAP. "SAP_FIELD_ANY" means wildcarding. Note that the requirement of non-overlapping registration does not preclude wildcarding. For example, it is possible to have two registered SAPs which both contain "SAP_FIELD_ANY" in some fields and different values in other fields. Note that the called party ATM number is mandatory, thus the satm_number field cannot contain "SAP_FIELD_ABSENT".

For connecting sockets, the sockaddr_atm structure is used to specify the destination SAP in connect()/WSAConnect()/WSPConnect() for point-to-point connections, and WSAJoinLeaf()/WSPJoinLeaf() for point-to-multipoint connections. The fields in the destination SAP of a connecting socket must contain either a valid value or "SAP_FIELD_ABSENT", i.e., "SAP_FIELD_ANY" is not allowed. Furthermore, "SAP_FIELD_ABSENT" is not allowed for the satm_number field. The destination SAP is used to match against all the registered SAPs in the destination machine to determine who to forward this connection request to. If each and every field of the destination SAP of an incoming request either equals to the corresponding field of a registered SAP, or the corresponding field contains the "SAP_FIELD_ANY", the listening socket associated with this registered SAP will receive the incoming connection request.

If bind()/WSPBind() is used on a connecting socket to specify the calling party ATM address, the satm_blli and satm_bhli fields should be ignored and the ones specified in connect()/WSAConnect()/WSPConnect() will be used.

/*

* values used for AddressType in struct ATM_ADDRESS

*/

#define ATM_E164 0x01 /* E.164 addressing scheme */

#define ATM_NSAP 0x02 /* NSAP-style ATM Endsystem Address scheme */

#define ATM_AESA 0x02 /* NSAP-style ATM Endsystem Address scheme */

typedef struct {

DWORD AddressType; /* E.164 or NSAP-style ATM Endsystem Address */

DWORD NumofDigits; /* number of digits; */

UCHAR Addr[20]; /* IA5 digits for E164, BCD encoding for NSAP */

/* format as defined in the ATM Forum UNI 3.1 */

} ATM_ADDRESS;

If the use of the E.164 addressing plan is indicated, the number digits appear in the same order in which they would be entered on a numeric keypad; i.e., the number digit which would be entered first is located in addr[0]. Digits are coded in IA5 characters. Bit 8 is set to 0.

If the use of NSAP-style ATM Endsystem Address (AESA) is indicated, the address is coded using Binary Coded Decimal (BCD) as defined in the ATM Forum UNI 3.1. The NumofDigits field will be ignored in this case, and the NSAP-style address always contains 20 bytes.

A value of "SAP_FIELD_ANY" in AddressType indicates that the satm_number field is a wildcard. There are two more specialized wildcard values: "SAP_FIELD_ANY_AESA_SEL" and "SAP_FIELD_ANY_AESA_REST". "SAP_FIELD_ANY_AESA_SEL" means that this is a NSAP-style ATM Endsystem Address and the selector octet is "wildcarded". "SAP_FIELD_ANY_AESA_REST" means that this is a NSAP-style ATM Endsystem Address and all the octets except for the selector octet are "wildcarded".

/*

* values used for Layer2Protocol in struct B-LLI

*/

#define BLLI_L2_ISO_1745 0x01 /* Basic mode ISO 1745 */

#define BLLI_L2_Q921 0x02 /* CCITT Rec. Q.921 */

#define BLLI_L2_X25L 0x06 /* CCITT Rec. X.25, link layer */

#define BLLI_L2_X25M 0x07 /* CCITT Rec. X.25, multi-link */

#define BLLI_L2_ELAPB 0x08 /* Extended LAPB; for half duplex operation */

#define BLLI_L2_HDLC_NRM 0x09 /* HDLC NRM (ISO 4335) */

#define BLLI_L2_HDLC_ABM 0x0A /* HDLC ABM (ISO 4335) */

#define BLLI_L2_HDLC_ARM 0x0B /* HDLC ARM (ISO 4335) */

#define BLLI_L2_LLC 0x0C /* LAN logical link control (ISO 8802/2) */

#define BLLI_L2_X75 0x0D /* CCITT Rec. X.75, single link procedure */

#define BLLI_L2_Q922 0x0E /* CCITT Rec. Q.922 */

#define BLLI_L2_USER_SPECIFIED 0x10 /* User Specified */

#define BLLI_L2_ISO_7776 0x11 /* ISO 7776 DTE-DTE operation */

/*

* values used for Layer3Protocol in struct B-LLI

*/

#define BLLI_L3_X25 0x06 /* CCITT Rec. X.25, packet layer */

#define BLLI_L3_ISO_8208 0x07 /* ISO/IEC 8208 (X.25 packet layer for DTE */

#define BLLI_L3_X223 0x08 /* X.223/ISO 8878 */

#define BLLI_L3_SIO_8473 0x09 /* ISO/IEC 8473 (OSI connectionless) */

#define BLLI_L3_T70 0x0A /* CCITT Rec. T.70 min. network layer */

#define BLLI_L3_ISO_TR9577 0x0B /* ISO/IEC TR 9577 Network Layer Protocol ID*/

#define BLLI_L3_USER_SPECIFIED 0x10 /* User Specified */

/*

* values used for Layer3IPI in struct B-LLI

*/

#define BLLI_L3_IPI_SNAP 0x80 /* IEEE 802.1 SNAP identifier */

#define BLLI_L3_IPI_IP 0xCC /* Internet Protocol (IP) identifier */

typedef struct {

DWORD Layer2Protocol; /* User information layer 2 protocol */

DWORD Layer2UserSpecifiedProtocol; /* User specified layer 2 protocol information */

DWORD Layer3Protocol; /* User information layer 3 protocol */

DWORD Layer3UserSpecifiedProtocol; /* User specified layer 3 protocol information */

DWORD Layer3IPI; /* ISO/IEC TR 9577 Initial Protocol Identifier */

UCHAR SnapID[5]; /* SNAP ID consisting of OUI and PID */

} ATM_BLLI;

Identifies the layer 2 protocol. Corresponds to the User information layer 2 protocol field in the B-LLI information element. A value of "SAP_FIELD_ABSENT" indicates that this field is not used, and a value of "SAP_FIELD_ANY" means wildcard.

Identifies the user specified layer 2 protocol. Only used if the Layer2Protocol parameter is set to "BLLI_L2_USER_SPECIFIED". The valid values range from 0 to 127. Corresponds to the User specified layer 2 protocol information field in the B-LLI information element.

Identifies the layer 3 protocol. Corresponds to the User information layer 3 protocol field in the B-LLI information element. A value of "SAP_FIELD_ABSENT" indicates that this field is not used, and a value of "SAP_FIELD_ANY" means wildcard.

Identifies the user specified layer 3 protocol. Only used if the Layer3Protocol parameter is set to "BLLI_L3_USER_SPECIFIED." The valid values range from 0 to 127. Corresponds to the User specified layer 3 protocol information field in the B-LLI information element.

Identifies the layer 3 Initial Protocol Identifier. Only used if the Layer3Protocol parameter is set to "BLLI_L3_ISO_TR9577". Corresponds to the ISO/IEC TR 9577 Initial Protocol Identifier field in the B-LLI information element.

Identifies the 802.1 SNAP identifier. Only used if the Layer3Protocol parameter is set to "BLLI_L3_ISO_TR9577" and Layer3IPI is set to "BLLI_L3_IPI_SNAP", indicating an IEEE 802.1 SNAP identifier. Corresponds to the OUI and PID fields in the B-LLI information element.

/*

* values used for the HighLayerInfoType field in struct ATM_BHLI

*/

#define BHLI_ISO 0x00 /* ISO */

#define BHLI_UserSpecific 0x01 /* User Specific */

#define BHLI_HighLayerProfile 0x02 /* High layer profile (only in UNI3.0) */

#define BHLI_VendorSpecificAppId 0x03 /* Vendor-Specific Application ID */

typedef struct {

DWORD HighLayerInfoType; /* High Layer Information Type */

DWORD HighLayerInfoLength; /* number of bytes in HighLayerInfo */

UCHAR HighLayerInfo[8]; /* the value dependent on the */

/* HighLayerInfoType field */

} ATM_BHLI;

Identifies the high layer information type field in the B-LLI information element. Note that the type BHLI_HighLayerProfile has been eliminated in UNI 3.1. A value of "SAP_FIELD_ABSENT" indicates that B-HLI is not present, and a value of "SAP_FIELD_ANY" means wildcard.

Identifies the number of bytes from 1 to 8 in the HighLayerInfo array. Valid values include 8 for the cases of BHLI_ISO and BHLI_UserSpecific, 4 for BHLI_HighLayerProfile, and 7 for BHLI_VendorSpecificAppId.

Identifies the high layer information field in the B-LLI information element. In the case HighLayerInfoType being BHLI_VendorSpecificAppId, the first three bytes consist of a globally-administered Organizationally Unique Identifier (OUI)(as per IEEE standard 802-1990), followed by a four-byte application identifier, which is administered by the vendor identified by the OUI. Value for the case of BHLI_UserSpecific is user defined and requires bilateral agreement between two end users.

ATM point-to-point and point-to-multipoint connection setup and teardown are natively supported by the WinSock 2 specification. In fact, WinSock 2 QOS spec and protocol-independent multipoint/multicast mechanisms were designed with ATM in mind, along with other protocols. See section 2.7 and appendix D of the WinSock 2 API specification for WinSock 2 QOS and multipoint support, respectively. Therefore, no ATM specific ioctls need to be introduced in this document.

Based on the taxonomy defined for WinSock 2 protocol-independent multipoint/multicast schemes, ATM falls into the category of "rooted data" and "rooted control" planes. (See WinSock 2 API specification, Appendix D for more information.) An application acting as the root would create c_root sockets and counterparts running on leaf nodes would utilize c_leaf sockets. The root application will use WSAJoinLeaf() to add new leaf nodes. The corresponding applications on the leaf nodes will have set their c_leaf sockets into the listening mode. WSAJoinLeaf() with a c_root socket specified will be mapped to the Q.2931 SETUP message (for the first leaf) or ADD PARTY message (for any subsequent leaves). Note that the QOS parameters specified in WSAJoinLeaf() for any subsequent leaves should be ignored per the ATM Forum UNI specification.

The leaf-initiated join is not part of the ATM UNI 3.1, but will be supported in the ATM UNI 4.0. Thus WSAJoinLeaf() with a c_leaf socket specified will be mapped to the appropriate ATM UNI 4.0 message.

The AAL Parameter and B-LLI negotiation is supported via the modification of the corresponding IEs in the lpSQOS parameter upon the invocation of the condition function specified in WSAAccept(). Note that only certain fields in those two IEs can be modified. See the ATM Forum UNI specification Appendix C and F for details.

This section describes the protocol-specific QOS structure for ATM, which is contained in the ProviderSpecific.buf field of the QOS structure. Note that the use of this ATM-specific QOS structure is optional by WinSock 2 clients, and the ATM service provider is required to map the generic FLOWSPEC structure to appropriate Q.2931 Information Elements. However, if both the generic FLOWSPEC structure and ATM-specific QOS structure are specified, the value specified in the ATM-specific QOS structure should take precedence should there be any conflicts. See WinSock 2 API specification section 2.7 for more information about the QOS provisions and FLOWSPEC structure.

The protocol-specific QOS structure for ATM is a concatenation of Q.2931 Information Element (IE) structures, which are defined below. If an application omits an IE that UNI 3.x mandates, the service provider should insert a reasonable default value, taking the information in the FLOWSPEC structure into account if applicable.

The handling of repeated IEs is dependent on the IE itself. If an IE is repeated and it is one that is allowed to be repeated per ATM Forum UNI spec then the provider must handle it properly. In this case, order in the list determines preference order, with elements appearing earlier in the list being more preferred. If an IE is repeated and this is not allowed per ATM Forum UNI spec, the provider may either fail the request from the client (the preferred option) or use the last IE of that type found.

Each individual IE structure is formatted in the following fashion and identified by the IEType field:

typedef struct {

Q2931_IE_TYPE IEType;

ULONG IELength;

UCHAR IE[1];

} Q2931_IE;

Legal values for the IEType field are defined below:

typedef enum {

IE_AALParameters,

IE_TrafficDescriptor,

IE_BroadbandBearerCapability,

IE_BHLI,

IE_BLLI,

IE_CalledPartyNumber,

IE_CalledPartySubaddress,

IE_CallingPartyNumber,

IE_CallingPartySubaddress,

IE_Cause,

IE_QOSClass,

IE_TransitNetworkSelection,

} Q2931_IE_TYPE;

The IE field is overlaid by a specific IE structure defined below, and the IELength field is the total length in bytes of the IE structure including the IEType and IELength fields. The semantics and legal values for each element of these IE structures are per ATM UNI 3.x specification. "SAP_FIELD_ABSENT" can be used for those elements which are optional for a given IE structure, per ATM UNI 3.x specification.

/*

* manifest constants for the AALType field in struct AAL_PARAMETERS_IE

*/

typedef enum {

AALTYPE_5 = 5, /* AAL 5 */

AALTYPE_USER = 16 /* user-defined AAL */

} AAL_TYPE;

/*

* values used for the Mode field in struct AAL5_PARAMETERS

*/

#define AAL5_MODE_MESSAGE 0x01

#define AAL5_MODE_STREAMING 0x02

/*

* values used for the SSCSType field in struct AAL5_PARAMETERS

*/

#define AAL5_SSCS_NULL 0x00

#define AAL5_SSCS_SSCOP_ASSURED 0x01

#define AAL5_SSCS_SSCOP_NON_ASSURED 0x02

#define AAL5_SSCS_FRAME_RELAY 0x04

typedef struct {

ULONG ForwardMaxCPCSSDUSize;

ULONG BackwardMaxCPCSSDUSize;

UCHAR Mode; /* only available in UNI 3.0 */

UCHAR SSCSType;

} AAL5_PARAMETERS;

typedef struct {

ULONG UserDefined;

} AALUSER_PARAMETES;

typedef struct {

AAL_TYPE AALType;

union {

AAL5_PARAMETERS AAL5Parameters;

AALUSER_PARAMETERS AALUserParameters;

} AALSpecificParameters;

} AAL_PARAMETERS_IE;

typedef struct {

ULONG PeakCellRate_CLP0;

ULONG PeakCellRate_CLP01;

ULONG SustainableCellRate_CLP0;

ULONG SustainableCellRate_CLP01;

ULONG MaxBurstSize_CLP0;

ULONG MaxBurstSize_CLP01;

BOOL Tagging;

} ATM_TD;

typedef struct {

ATM_TD Forward;

ATM_TD Backward;

BOOL BestEffort;

} ATM_TRAFFIC_DESCRIPTOR_IE;

/*

* values used for the BearerClass field in struct ATM_BROADBAND_BEARER_CAPABILITY_IE

*/

#define BCOB_A 0x00 /* Bearer class A */

#define BCOB_C 0x03 /* Bearer class C */

#define BCOB_X 0x10 /* Bearer class X */

/*

* values used for the TrafficType field in struct ATM_BROADBAND_BEARER_CAPABILITY_IE

*/

#define TT_NOIND 0x00 /* No indication of traffic type */

#define TT_CBR 0x04 /* Constant bit rate */

#define TT_VBR 0x06 /* Variable bit rate */

/*

* values used for the TimingRequirements field in struct ATM_BROADBAND_BEARER_CAPABILITY_IE

*/

#define TR_NOIND 0x00 /* No timing requirement indication */

#define TR_END_TO_END 0x01 /* End-to-end timing required */

#define TR_NO_END_TO_END 0x02 /* End-to-end timing not required */

/*

* values used for the ClippingSusceptability field in struct ATM_BROADBAND_BEARER_CAPABILITY_IE

*/

#define CLIP_NOT 0x00 /* Not susceptible to clipping */

#define CLIP_SUS 0x20 /* Susceptible to clipping */

/*

• values used for the UserPlaneConnectionConfig field in
• struct ATM_BROADBAND_BEARER_CAPABILITY_IE

*/

#define UP_P2P 0x00 /* Point-to-point connection */

#define UP_P2MP 0x01 /* Point-to-multipoint connection */

typedef struct {

UCHAR BearerClass;

UCHAR TrafficType;

UCHAR TimingRequirements;

UCHAR ClippingSusceptability;

UCHAR UserPlaneConnectionConfig;

} ATM_BROADBAND_BEARER_CAPABILITY_IE;

typedef ATM_BHLI ATM_BHLI_IE;

/*

* values used for the Layer2Mode field in struct ATM_BLLI_IE

*/

#define BLLI_L2_MODE_NORMAL 0x40

#define BLLI_L2_MODE_EXT 0x80

/*

* values used for the Layer3Mode field in struct ATM_BLLI_IE

*/

#define BLLI_L3_MODE_NORMAL 0x40

#define BLLI_L3_MODE_EXT 0x80

/*

* values used for the Layer3DefaultPacketSize field in struct ATM_BLLI_IE

*/

#define BLLI_L3_PACKET_16 0x04

#define BLLI_L3_PACKET_32 0x05

#define BLLI_L3_PACKET_64 0x06

#define BLLI_L3_PACKET_128 0x07

#define BLLI_L3_PACKET_256 0x08

#define BLLI_L3_PACKET_512 0x09

#define BLLI_L3_PACKET_1024 0x0A

#define BLLI_L3_PACKET_2048 0x0B

#define BLLI_L3_PACKET_4096 0x0C

typedef struct {

DWORD Layer2Protocol; /* User information layer 2 protocol */

UCHAR Layer2Mode;

UCHAR Layer2WindowSize;

DWORD Layer2UserSpecifiedProtocol; /* User specified layer 2 protocol information */

DWORD Layer3Protocol; /* User information layer 3 protocol */

UCHAR Layer3Mode;

UCHAR Layer3DefaultPacketSize;

UCHAR Layer3PacketWindowSize;

DWORD Layer3UserSpecifiedProtocol; /* User specified layer 3 protocol information */

DWORD Layer3IPI; /* ISO/IEC TR 9577 Initial Protocol Identifier */

UCHAR SnapID[5]; /* SNAP ID consisting of OUI and PID */

} ATM_BLLI_IE;

typedef ATM_ADDRESS ATM_CALLED_PARTY_NUMBER_IE;

typedef ATM_ADDRESS ATM_CALLED_PARTY_SUBADDRESS_IE;

/*

• values used for the Presentation_Indication field in
• struct ATM_CALLING_PARTY_NUMBER_IE

*/

#define PI_ALLOWED 0x00

#define PI_RESTRICTED 0x40

#define PI_NUMBER_NOT_AVAILABLE 0x80

/*

• values used for the Screening_Indicator field in
• struct ATM_CALLING_PARTY_NUMBER_IE

*/

#define SI_USER_NOT_SCREENED 0x00

#define SI_USER_PASSED 0x01

#define SI_USER_FAILED 0x02

#define SI_NETWORK 0x03

typedef struct {

ATM_ADDRESS ATM_Number;

UCHAR Presentation_Indication;

UCHAR Screening_Indicator;

} ATM_CALLING_PARTY_NUMBER_IE;

typedef ATM_ADDRESS ATM_CALLING_PARTY_SUBADDRESS_IE;

/*

• values used for the QOSClassForward and QOSClassBackward
• field in struct ATM_QOS_CLASS_IE

*/

#define QOS_CLASS0 0x00

#define QOS_CLASS1 0x01

#define QOS_CLASS2 0x02

#define QOS_CLASS3 0x03

#define QOS_CLASS4 0x04

typedef struct {

UCHAR QOSClassForward;

UCHAR QOSClassBackward;

} ATM_QOS_CLASS_IE;

/*

* values used for the TypeOfNetworkId field in struct ATM_TRANSIT_NETWORK_SELECTION_IE

*/

#define TNS_TYPE_NATIONAL 0x40

/*

* values used for the NetworkIdPlan field in struct ATM_TRANSIT_NETWORK_SELECTION_IE

*/

#define TNS_PLAN_CARRIER_ID_CODE 0x01

typedef struct {

UCHAR TypeOfNetworkId;

UCHAR NetworkIdPlan;

UCHAR NetworkIdLength;

UCHAR NetworkId[1];

} ATM_TRANSIT_NETWORK_SELECTION_IE;

In addition to all the IEs described above, which could be specified in the ATM-specific QOS structure while calling WSAConnect(), there is a Cause IE which can only be used during the call release. Upon disconnecting, WinSock 2 applications can optionally specify this IE as the disconnect data in WSASendDisconnect(). The remote party can retrieve this IE via WSARecvDisconnect() after receiving the FD_CLOSE notification.

/*

* values used for the Location field in struct ATM_CAUSE_IE

*/

#define CAUSE_LOC_USER 0x00

#define CAUSE_LOC_PRIVATE_LOCAL 0x01

#define CAUSE_LOC_PUBLIC_LOCAL 0x02

#define CAUSE_LOC_TRANSIT_NETWORK 0x03

#define CAUSE_LOC_PUBLIC_REMOTE 0x04

#define CAUSE_LOC_PRIVATE_REMOTE 0x05

#define CAUSE_LOC_INTERNATIONAL_NETWORK 0x06

#define CAUSE_LOC_BEYOND_INTERWORKING 0x0A

/*

* values used for the Cause field in struct ATM_CAUSE_IE

*/

#define CAUSE_UNALLOCATED_NUMBER 0x01

#define CAUSE_NO_ROUTE_TO_TRANSIT_NETWORK 0x02

#define CAUSE_NO_ROUTE_TO_DESTINATION 0x03

#define CAUSE_VPI_VCI_UNACCEPTABLE 0x0A

#define CAUSE_NORMAL_CALL_CLEARING 0x10

#define CAUSE_USER_BUSY 0x11

#define CAUSE_NO_USER_RESPONDING 0x12

#define CAUSE_CALL_REJECTED 0x15

#define CAUSE_NUMBER_CHANGED 0x16

#define CAUSE_USER_REJECTS_CLIR 0x17

#define CAUSE_DESTINATION_OUT_OF_ORDER 0x1B

#define CAUSE_INVALID_NUMBER_FORMAT 0x1C

#define CAUSE_STATUS_ENQUIRY_RESPONSE 0x1E

#define CAUSE_NORMAL_UNSPECIFIED 0x1F

#define CAUSE_VPI_VCI_UNAVAILABLE 0x23

#define CAUSE_NETWORK_OUT_OF_ORDER 0x26

#define CAUSE_TEMPORARY_FAILURE 0x29

#define CAUSE_ACCESS_INFORMAION_DISCARDED 0x2B

#define CAUSE_NO_VPI_VCI_AVAILABLE 0x2D

#define CAUSE_RESOURCE_UNAVAILABLE 0x2F

#define CAUSE_QOS_UNAVAILABLE 0x31

#define CAUSE_USER_CELL_RATE_UNAVAILABLE 0x33

#define CAUSE_BEARER_CAPABILITY_UNAUTHORIZED 0x39

#define CAUSE_BEARER_CAPABILITY_UNAVAILABLE 0x3A

#define CAUSE_OPTION_UNAVAILABLE 0x3F

#define CAUSE_BEARER_CAPABILITY_UNIMPLEMENTED 0x41

#define CAUSE_UNSUPPORTED_TRAFFIC_PARAMETERS 0x49

#define CAUSE_INVALID_CALL_REFERENCE 0x51

#define CAUSE_CHANNEL_NONEXISTENT 0x52

#define CAUSE_INCOMPATIBLE_DESTINATION 0x58

#define CAUSE_INVALID_ENDPOINT_REFERENCE 0x59

#define CAUSE_INVALID_TRANSIT_NETWORK_SELECTION 0x5B

#define CAUSE_TOO_MANY_PENDING_ADD_PARTY 0x5C

#define CAUSE_AAL_PARAMETERS_UNSUPPORTED 0x5D

#define CAUSE_MANDATORY_IE_MISSING 0x60

#define CAUSE_UNIMPLEMENTED_MESSAGE_TYPE 0x61

#define CAUSE_UNIMPLEMENTED_IE 0x63

#define CAUSE_INVALID_IE_CONTENTS 0x64

#define CAUSE_INVALID_STATE_FOR_MESSAGE 0x65

#define CAUSE_RECOVERY_ON_TIMEOUT 0x66

#define CAUSE_INCORRECT_MESSAGE_LENGTH 0x68

#define CAUSE_PROTOCOL_ERROR 0x6F

/*

• values used for the Condition portion of the Diagnostics field
• in struct ATM_CAUSE_IE, for certain Cause values

*/

#define CAUSE_COND_UNKNOWN 0x00

#define CAUSE_COND_PERMANENT 0x01

#define CAUSE_COND_TRANSIENT 0x02

/*

• values used for the Rejection Reason portion of the Diagnostics field
• in struct ATM_CAUSE_IE, for certain Cause values

*/

#define CAUSE_REASON_USER 0x00

#define CAUSE_REASON_IE_MISSING 0x04

#define CAUSE_REASON_IE_INSUFFICIENT 0x08

/*

• values used for the P-U flag of the Diagnostics field
• in struct ATM_CAUSE_IE, for certain Cause values

*/

#define CAUSE_PU_PROVIDER 0x00

#define CAUSE_PU_USER 0x08

/*

• values used for the N-A flag of the Diagnostics field
• in struct ATM_CAUSE_IE, for certain Cause values

*/

#define CAUSE_NA_NORMAL 0x00

#define CAUSE_NA_ABNORMAL 0x04

typedef struct {

UCHAR Location;

UCHAR Cause;

UCHAR DiagnosticsLength;

UCHAR Diagnostics[4];

} ATM_CAUSE_IE;

#ifndef _WS2ATM_H_

#define _WS2ATM_H_

#pragma pack(1)

#define ATMPROTO_AALUSER 0x00 /* User-defined AAL */

#define ATMPROTO_AAL1 0x01 /* AAL 1 */

#define ATMPROTO_AAL2 0x02 /* AAL 2 */

#define ATMPROTO_AAL34 0x03 /* AAL 3/4 */

#define ATMPROTO_AAL5 0x05 /* AAL 5 */

#define SAP_FIELD_ABSENT 0xFFFFFFFE

#define SAP_FIELD_ANY 0xFFFFFFFF

#define SAP_FIELD_ANY_AESA_SEL 0xFFFFFFFA

#define SAP_FIELD_ANY_AESA_REST 0xFFFFFFFB

/*

* values used for AddressType in struct ATM_ADDRESS

*/

#define ATM_E164 0x01 /* E.164 addressing scheme */

#define ATM_NSAP 0x02 /* NSAP-style ATM Endsystem Address scheme */

#define ATM_AESA 0x02 /* NSAP-style ATM Endsystem Address scheme */

typedef struct {

DWORD AddressType; /* E.164 or NSAP-style ATM Endsystem Address */

DWORD NumofDigits; /* number of digits; */

UCHAR Addr[20]; /* IA5 digits for E164, BCD encoding for NSAP */

/* format as defined in the ATM Forum UNI 3.1 */

} ATM_ADDRESS;

/*

* values used for Layer2Protocol in B-LLI

*/

#define BLLI_L2_ISO_1745 0x01 /* Basic mode ISO 1745 */

#define BLLI_L2_Q921 0x02 /* CCITT Rec. Q.921 */

#define BLLI_L2_X25L 0x06 /* CCITT Rec. X.25, link layer */

#define BLLI_L2_X25M 0x07 /* CCITT Rec. X.25, multi-link */

#define BLLI_L2_ELAPB 0x08 /* Extended LAPB; for half duplex operation */

#define BLLI_L2_HDLC_NRM 0x09 /* HDLC NRM (ISO 4335) */

#define BLLI_L2_HDLC_ABM 0x0A /* HDLC ABM (ISO 4335) */

#define BLLI_L2_HDLC_ARM 0x0B /* HDLC ARM (ISO 4335) */

#define BLLI_L2_LLC 0x0C /* LAN logical link control (ISO 8802/2) */

#define BLLI_L2_X75 0x0D /* CCITT Rec. X.75, single link procedure */

#define BLLI_L2_Q922 0x0E /* CCITT Rec. Q.922 */

#define BLLI_L2_USER_SPECIFIED 0x10 /* User Specified */

#define BLLI_L2_ISO_7776 0x11 /* ISO 7776 DTE-DTE operation */

/*

* values used for Layer3Protocol in B-LLI

*/

#define BLLI_L3_X25 0x06 /* CCITT Rec. X.25, packet layer */

#define BLLI_L3_ISO_8208 0x07 /* ISO/IEC 8208 (X.25 packet layer for DTE */

#define BLLI_L3_X223 0x08 /* X.223/ISO 8878 */

#define BLLI_L3_SIO_8473 0x09 /* ISO/IEC 8473 (OSI connectionless) */

#define BLLI_L3_T70 0x0A /* CCITT Rec. T.70 min. network layer */

#define BLLI_L3_ISO_TR9577 0x0B /* ISO/IEC TR 9577 Network Layer Protocol ID*/

#define BLLI_L3_USER_SPECIFIED 0x10 /* User Specified */

/*

* values used for Layer3IPI in B-LLI

*/

#define BLLI_L3_IPI_SNAP 0x80 /* IEEE 802.1 SNAP identifier */

#define BLLI_L3_IPI_IP 0xCC /* Internet Protocol (IP) identifier */

typedef struct {

DWORD Layer2Protocol; /* User information layer 2 protocol */

DWORD Layer2UserSpecifiedProtocol; /* User specified layer 2 protocol information */

DWORD Layer3Protocol; /* User information layer 3 protocol */

DWORD Layer3UserSpecifiedProtocol; /* User specified layer 3 protocol information */

DWORD Layer3IPI; /* ISO/IEC TR 9577 Initial Protocol Identifier */

UCHAR SnapID[5]; /* SNAP ID consisting of OUI and PID */

} ATM_BLLI;

/*

* values used for the HighLayerInfoType field in ATM_BHLI

*/

#define BHLI_ISO 0x00 /* ISO */

#define BHLI_UserSpecific 0x01 /* User Specific */

#define BHLI_HighLayerProfile 0x02 /* High layer profile (only in UNI3.0) */

#define BHLI_VendorSpecificAppId 0x03 /* Vendor-Specific Application ID */

typedef struct {

DWORD HighLayerInfoType; /* High Layer Information Type */

DWORD HighLayerInfoLength; /* number of bytes in HighLayerInfo */

UCHAR HighLayerInfo[8]; /* the value dependent on the */

/* HighLayerInfoType field */

} ATM_BHLI;

struct sockaddr_atm {

u_short satm_family; /* address family should be AF_ATM */

ATM_ADDRESS satm_number; /* ATM address */

ATM_BLLI satm_blli; /* B-LLI */

ATM_BHLI satm_bhli; /* B-HLI */

};

typedef enum {

IE_AALParameters,

IE_TrafficDescriptor,

IE_BroadbandBearerCapability,

IE_BHLI,

IE_BLLI,

IE_CalledPartyNumber,

IE_CalledPartySubaddress,

IE_CallingPartyNumber,

IE_CallingPartySubaddress,

IE_Cause,

IE_QOSClass,

IE_TransitNetworkSelection,

} Q2931_IE_TYPE;

typedef struct {

Q2931_IE_TYPE IEType;

ULONG IELength;

UCHAR IE[1];

} Q2931_IE;

/*

* manifest constants for the AALType field in struct AAL_PARAMETERS_IE

*/

typedef enum {

AALTYPE_5 = 5, /* AAL 5 */

AALTYPE_USER = 16, /* user-defined AAL */

} AAL_TYPE;

/*

* values used for the Mode field in struct AAL5_PARAMETERS

*/

#define AAL5_MODE_MESSAGE 0x01

#define AAL5_MODE_STREAMING 0x02

/*

* values used for the SSCSType field in struct AAL5_PARAMETERS

*/

#define AAL5_SSCS_NULL 0x00

#define AAL5_SSCS_SSCOP_ASSURED 0x01

#define AAL5_SSCS_SSCOP_NON_ASSURED 0x02

#define AAL5_SSCS_FRAME_RELAY 0x04

typedef struct {

ULONG ForwardMaxCPCSSDUSize;

ULONG BackwardMaxCPCSSDUSize;

UCHAR Mode; /* only available in UNI 3.0 */

UCHAR SSCSType;

} AAL5_PARAMETERS;

typedef struct {

ULONG UserDefined;

} AALUSER_PARAMETERS;

typedef struct {

AAL_TYPE AALType;

union {

AAL5_PARAMETERS AAL5Parameters;

AALUSER_PARAMETERS AALUserParameters;

} AALSpecificParameters;

} AAL_PARAMETERS_IE;

typedef struct {

ULONG PeakCellRate_CLP0;

ULONG PeakCellRate_CLP01;

ULONG SustainableCellRate_CLP0;

ULONG SustainableCellRate_CLP01;

ULONG MaxBurstSize_CLP0;

ULONG MaxBurstSize_CLP01;

BOOL Tagging;

} ATM_TD;

typedef struct {

ATM_TD Forward;

ATM_TD Backward;

BOOL BestEffort;

} ATM_TRAFFIC_DESCRIPTOR_IE;

/*

* values used for the BearerClass field in struct ATM_BROADBAND_BEARER_CAPABILITY_IE

*/

#define BCOB_A 0x01 /* Bearer class A */

#define BCOB_C 0x03 /* Bearer class C */

#define BCOB_X 0x10 /* Bearer class X */

/*

* values used for the TrafficType field in struct ATM_BROADBAND_BEARER_CAPABILITY_IE

*/

#define TT_NOIND 0x00 /* No indication of traffic type */

#define TT_CBR 0x04 /* Constant bit rate */

#define TT_VBR 0x06 /* Variable bit rate */

/*

* values used for the TimingRequirements field in struct ATM_BROADBAND_BEARER_CAPABILITY_IE

*/

#define TR_NOIND 0x00 /* No timing requirement indication */

#define TR_END_TO_END 0x01 /* End-to-end timing required */

#define TR_NO_END_TO_END 0x02 /* End-to-end timing not required */

/*

* values used for the ClippingSusceptability field in struct ATM_BROADBAND_BEARER_CAPABILITY_IE

*/

#define CLIP_NOT 0x00 /* Not susceptible to clipping */

#define CLIP_SUS 0x20 /* Susceptible to clipping */

/*

• values used for the UserPlaneConnectionConfig field in
• struct ATM_BROADBAND_BEARER_CAPABILITY_IE

*/

#define UP_P2P 0x00 /* Point-to-point connection */

#define UP_P2MP 0x01 /* Point-to-multipoint connection */

typedef struct {

UCHAR BearerClass;

UCHAR TrafficType;

UCHAR TimingRequirements;

UCHAR ClippingSusceptability;

UCHAR UserPlaneConnectionConfig;

} ATM_BROADBAND_BEARER_CAPABILITY_IE;

typedef ATM_BHLI ATM_BHLI_IE;

/*

* values used for the Layer2Mode field in struct ATM_BLLI_IE

*/

#define BLLI_L2_MODE_NORMAL 0x40

#define BLLI_L2_MODE_EXT 0x80

/*

* values used for the Layer3Mode field in struct ATM_BLLI_IE

*/

#define BLLI_L3_MODE_NORMAL 0x40

#define BLLI_L3_MODE_EXT 0x80

/*

* values used for the Layer3DefaultPacketSize field in struct ATM_BLLI_IE

*/

#define BLLI_L3_PACKET_16 0x04

#define BLLI_L3_PACKET_32 0x05

#define BLLI_L3_PACKET_64 0x06

#define BLLI_L3_PACKET_128 0x07

#define BLLI_L3_PACKET_256 0x08

#define BLLI_L3_PACKET_512 0x09

#define BLLI_L3_PACKET_1024 0x0A

#define BLLI_L3_PACKET_2048 0x0B

#define BLLI_L3_PACKET_4096 0x0C

typedef struct {

DWORD Layer2Protocol; /* User information layer 2 protocol */

UCHAR Layer2Mode;

UCHAR Layer2WindowSize;

DWORD Layer2UserSpecifiedProtocol; /* User specified layer 2 protocol information */

DWORD Layer3Protocol; /* User information layer 3 protocol */

UCHAR Layer3Mode;

UCHAR Layer3DefaultPacketSize;

UCHAR Layer3PacketWindowSize;

DWORD Layer3UserSpecifiedProtocol; /* User specified layer 3 protocol information */

DWORD Layer3IPI; /* ISO/IEC TR 9577 Initial Protocol Identifier */

UCHAR SnapID[5]; /* SNAP ID consisting of OUI and PID */

} ATM_BLLI_IE;

typedef ATM_ADDRESS ATM_CALLED_PARTY_NUMBER_IE;

typedef ATM_ADDRESS ATM_CALLED_PARTY_SUBADDRESS_IE;

/*

• values used for the Presentation_Indication field in
• struct ATM_CALLING_PARTY_NUMBER_IE

*/

#define PI_ALLOWED 0x00

#define PI_RESTRICTED 0x40

#define PI_NUMBER_NOT_AVAILABLE 0x80

/*

• values used for the Screening_Indicator field in
• struct ATM_CALLING_PARTY_NUMBER_IE

*/

#define SI_USER_NOT_SCREENED 0x00

#define SI_USER_PASSED 0x01

#define SI_USER_FAILED 0x02

#define SI_NETWORK 0x03

typedef struct {

ATM_ADDRESS ATM_Number;

UCHAR Presentation_Indication;

UCHAR Screening_Indicator;

} ATM_CALLING_PARTY_NUMBER_IE;

typedef ATM_ADDRESS ATM_CALLING_PARTY_SUBADDRESS_IE;

/*

* values used for the Location field in struct ATM_CAUSE_IE

*/

#define CAUSE_LOC_USER 0x00

#define CAUSE_LOC_PRIVATE_LOCAL 0x01

#define CAUSE_LOC_PUBLIC_LOCAL 0x02

#define CAUSE_LOC_TRANSIT_NETWORK 0x03

#define CAUSE_LOC_PUBLIC_REMOTE 0x04

#define CAUSE_LOC_PRIVATE_REMOTE 0x05

#define CAUSE_LOC_INTERNATIONAL_NETWORK 0x06

#define CAUSE_LOC_BEYOND_INTERWORKING 0x0A

/*

* values used for the Cause field in struct ATM_CAUSE_IE

*/

#define CAUSE_UNALLOCATED_NUMBER 0x01

#define CAUSE_NO_ROUTE_TO_TRANSIT_NETWORK 0x02

#define CAUSE_NO_ROUTE_TO_DESTINATION 0x03

#define CAUSE_VPI_VCI_UNACCEPTABLE 0x0A

#define CAUSE_NORMAL_CALL_CLEARING 0x10

#define CAUSE_USER_BUSY 0x11

#define CAUSE_NO_USER_RESPONDING 0x12

#define CAUSE_CALL_REJECTED 0x15

#define CAUSE_NUMBER_CHANGED 0x16

#define CAUSE_USER_REJECTS_CLIR 0x17

#define CAUSE_DESTINATION_OUT_OF_ORDER 0x1B

#define CAUSE_INVALID_NUMBER_FORMAT 0x1C

#define CAUSE_STATUS_ENQUIRY_RESPONSE 0x1E

#define CAUSE_NORMAL_UNSPECIFIED 0x1F

#define CAUSE_VPI_VCI_UNAVAILABLE 0x23

#define CAUSE_NETWORK_OUT_OF_ORDER 0x26

#define CAUSE_TEMPORARY_FAILURE 0x29

#define CAUSE_ACCESS_INFORMAION_DISCARDED 0x2B

#define CAUSE_NO_VPI_VCI_AVAILABLE 0x2D

#define CAUSE_RESOURCE_UNAVAILABLE 0x2F

#define CAUSE_QOS_UNAVAILABLE 0x31

#define CAUSE_USER_CELL_RATE_UNAVAILABLE 0x33

#define CAUSE_BEARER_CAPABILITY_UNAUTHORIZED 0x39

#define CAUSE_BEARER_CAPABILITY_UNAVAILABLE 0x3A

#define CAUSE_OPTION_UNAVAILABLE 0x3F

#define CAUSE_BEARER_CAPABILITY_UNIMPLEMENTED 0x41

#define CAUSE_UNSUPPORTED_TRAFFIC_PARAMETERS 0x49

#define CAUSE_INVALID_CALL_REFERENCE 0x51

#define CAUSE_CHANNEL_NONEXISTENT 0x52

#define CAUSE_INCOMPATIBLE_DESTINATION 0x58

#define CAUSE_INVALID_ENDPOINT_REFERENCE 0x59

#define CAUSE_INVALID_TRANSIT_NETWORK_SELECTION 0x5B

#define CAUSE_TOO_MANY_PENDING_ADD_PARTY 0x5C

#define CAUSE_AAL_PARAMETERS_UNSUPPORTED 0x5D

#define CAUSE_MANDATORY_IE_MISSING 0x60

#define CAUSE_UNIMPLEMENTED_MESSAGE_TYPE 0x61

#define CAUSE_UNIMPLEMENTED_IE 0x63

#define CAUSE_INVALID_IE_CONTENTS 0x64

#define CAUSE_INVALID_STATE_FOR_MESSAGE 0x65

#define CAUSE_RECOVERY_ON_TIMEOUT 0x66

#define CAUSE_INCORRECT_MESSAGE_LENGTH 0x68

#define CAUSE_PROTOCOL_ERROR 0x6F

/*

• values used for the Condition portion of the Diagnostics field
• in struct ATM_CAUSE_IE, for certain Cause values

*/

#define CAUSE_COND_UNKNOWN 0x00

#define CAUSE_COND_PERMANENT 0x01

#define CAUSE_COND_TRANSIENT 0x02

/*

• values used for the Rejection Reason portion of the Diagnostics field
• in struct ATM_CAUSE_IE, for certain Cause values

*/

#define CAUSE_REASON_USER 0x00

#define CAUSE_REASON_IE_MISSING 0x04

#define CAUSE_REASON_IE_INSUFFICIENT 0x08

/*

• values used for the P-U flag of the Diagnostics field
• in struct ATM_CAUSE_IE, for certain Cause values

*/

#define CAUSE_PU_PROVIDER 0x00

#define CAUSE_PU_USER 0x08

/*

• values used for the N-A flag of the Diagnostics field
• in struct ATM_CAUSE_IE, for certain Cause values

*/

#define CAUSE_NA_NORMAL 0x00

#define CAUSE_NA_ABNORMAL 0x04

typedef struct {

UCHAR Location;

UCHAR Cause;

UCHAR DiagnosticsLength;

UCHAR Diagnostics[4];

} ATM_CAUSE_IE;

/*

• values used for the QOSClassForward and QOSClassBackward
• field in struct ATM_QOS_CLASS_IE

*/

#define QOS_CLASS0 0x00

#define QOS_CLASS1 0x01

#define QOS_CLASS2 0x02

#define QOS_CLASS3 0x03

#define QOS_CLASS4 0x04

typedef struct {

UCHAR QOSClassForward;

UCHAR QOSClassBackward;

} ATM_QOS_CLASS_IE;

/*

* values used for the TypeOfNetworkId field in struct ATM_TRANSIT_NETWORK_SELECTION_IE

*/

#define TNS_TYPE_NATIONAL 0x40

/*

* values used for the NetworkIdPlan field in struct ATM_TRANSIT_NETWORK_SELECTION_IE

*/

#define TNS_PLAN_CARRIER_ID_CODE 0x01

typedef struct {

UCHAR TypeOfNetworkId;

UCHAR NetworkIdPlan;

UCHAR NetworkIdLength;

UCHAR NetworkId[1];

} ATM_TRANSIT_NETWORK_SELECTION_IE;

#pragma pack()

#endif /* _WS2ATM_H_ */

7. SSL Security Protocol

7.1. SSL Introduction

This section covers extensions to WinSock 2 that are specific to the Secure Sockets Layer security protocol (SSL). It also describes aspects of base WinSock 2 functions that require special consideration or which may exhibit unique behavior when using SSL.

Address comments or questions regarding this material to:

Elgamal Taher

Netscape Corp.

taher@netscape.com

30 May 1995

Network security has become a major consideration in recent times as the scope of networks and their uses continues to grow and expand into the commercial world. Application users and developers want to be assured that their data is private and that they are communicating with the party they intended to. The Secure Sockets Layer (SSL) protocol is intended to address these needs.

WinSock 2's WOSA architecture allows any number of underlying transport protocols to be accessed by applications. While SSL is not itself a complete transport protocol, it is designed to work in conjunction with existing transports that offer reliable, connection-oriented services. From an application's perspective, the addition of SSL causes additional entries to be returned in the WSAEnumProtocols() function. These additional entries are identical to the underlying transport protocol entries (e.g. TCP or SPX), but are distinguished by having SSL indicated in the iSecurityScheme field of the PROTOCOL_INFO struct. Having discovered and selected a transport that offers SSL security, the application creates sockets and sends data over them in exactly the same manner as is done for the underlying transport without security. Through this mechanism application developers are able to take advantage of security provisions without having to make extensive modifications to their applications.

This section describes how an applications developer can discover and effectively utilize transports that have been enhanced with the SSL security protocol. We begin by providing some background information which is necessary to explain the goals and techniques which are integral in any security discussion.

For many years, private encrypted messages were communicated between two or more users using keys that are shared among them. Under this model, any two users wishing to communicate privately need to establish a "secure" or protected channel of some kind to share the secret key. This traditional model for cryptography introduces many complications from key management point of view since each user would have to keep numerous secret keys to be used for communicating with all the needed users.

In 1977, the concept of public-key cryptography was invented where two parties can communicate privately without the need to share any secrets. Each party establishes a key-pair, one private key and one public key. The public key, as the name implies, is published to all nodes on a network and is used to encrypt messages to the node. The private key performs the inverse operation and enables the receiving node to decrypt the messages. The private key never leaves the node that "owns" it. This model for private communications simplifies the key management problem to a great extent.

Public-key cryptography can also be used to exchange a secret key between two (or more) nodes without having to communicate any secrets. But, perhaps the most prevalent application for public-key cryptography is a technology referred to as "digital signatures." This technology allows nodes to sign documents or messages using the private key allowing all other nodes to verify the signature using the published public key. The mathematics of public-key cryptosystems make it possible for one node to create a signature for a particular message, allowing others to verify the signature while ensuring that "forging" someone else's signature is computationally infeasible.

The only issue left with the above model for public-key cryptography is the following question:

Why should one believe that a published public key actually belongs to a given user?

This question can be answered using the notion of a digital certificate. The digital certificate of a user is a message composed of the name and other information about the user together with the user's public key. This entire message is digitally signed by an authority that is known to many users and that has the capacity of verifying the identity of a user. A user generates a public-private keypair, safely stores the private key and takes the public key to an authority with proof of identity. The authority generates a digital signature for the user and hands back a digital certificate. The certificate can then be published in a directory or attached to any message being signed by the user. Any other user can then verify the signature of the user using the attached certificate while ensuring the authenticity of the user's identity.

The RSA public-key cryptosystem is the most commonly used in commercial applications and systems. It provides capability for both encryption/decryption operations as well as digital signature and verification operations. The X.509 standard defines a format for digital certificates using the RSA algorithm which SSL supports.

It is also important to note that for performance reasons, public key encryption and decryption is usually constrained to signature applications and encryption of short data blocks such as data encryption keys. Traditional symmetric-key encryption algorithms are usually used for bulk data encryption. SSL supports a variety of symmetric-key algorithms including the DES standard and exportable versions of RC2 and RC4. Refer to the SSL specification document for a complete list of the supported encryption algorithms.

SSL operates by layering a security protocol on top of an underlying reliable connection-oriented transport protocol. The combined protocol establishes a connection with a remote host and then performs a handshake between the two nodes to establish a secure session. Once the security handshake is complete, the protocol then encrypts and authenticates data sent from the local host and decrypts and verifies data received from the remote host. This will all be done in a manner transparent to the application utilizing the SSL protocol.

Using this technology, an application developer can quickly convert a client or a server to provide a variety of security functions. By virtue of this technology being accessible using the WinSock 2.0 API, an end-user application developer can easily provide very strong security within an application.The application can simply enumerate the protocols supported by the system and if any of them provides SSL security, security can be enabled on arbitrary sockets.

As mentioned previously, application programmers use the standard WinSock 2 protocol enumeration method to discover SSL-enabled transports. Invoking WSAEnumProtocols() returns a buffer filled with PROTOCOL_INFO structs, with one such struct for each available transport protocol. Transports which have been enhanced with SSL capabilities have this indicated in the iSecurityScheme field of their PROTOCOL_INFO struct. This field will contain the value:

SSL works with the underlying transport protocol in such a manner as to be largely invisible to the application. Socket creation, connection establishment and data transfers are all invoked in the usual manner. The SSL protocol injects extra steps in the connection sequence so that its security handshake can occur, but this does not require any overt action on the application's part. Similarly, send and receive operations cause data to be encrypted and decrypted in a transparent fashion.

SSL data structures are introduced along with the ioctl's that they are used in.

All SSL controls make use of the WSAIoctl() function, with a set of dwIoControlCode values that are specific to SSL. The values for the dwIoControlCode are defined as follows:

/*

• * This value is the SSL protocol tag and WSAIoctl dwIoControlCode
• * "T" value.

*/

#define _SO_SSL ((2L << 27) | (0x73L << 16))

/*

• * These values are used to form the WSAIoctl dwIoControlCode
• * "Code" value.

*/

#define _SO_SSL_FLAGS 0x01

#define _SO_SSL_CIPHERS 0x02

#define _SO_SSL_CLIENT 0x03

#define _SO_SSL_SERVER 0x04

#define _SO_SSL_AUTH_CERT_HOOK 0x08

#define _SO_SSL_RSA_ENCRYPT_HOOK 0x10

#define _SO_SSL_RSA_DECRYPT_HOOK 0x20

/*

** Actual SSL Ioctl commands

*/

#define SO_SSL_GET_FLAGS (IOC_IN |_SO_SSL|_SO_SSL_FLAGS)

#define SO_SSL_SET_FLAGS (IOC_OUT|_SO_SSL|_SO_SSL_FLAGS)

#define SO_SSL_GET_CIPHERS (IOC_IN |_SO_SSL|_SO_SSL_CIPHERS)

#define SO_SSL_SET_CIPHERS (IOC_OUT|_SO_SSL|_SO_SSL_CIPHERS)

#define SO_SSL_GET_CLIENT (IOC_IN |_SO_SSL|_SO_SSL_CLIENT)

#define SO_SSL_SET_CLIENT (IOC_OUT|_SO_SSL|_SO_SSL_CLIENT)

#define SO_SSL_GET_SERVER (IOC_IN |_SO_SSL|_SO_SSL_SERVER)

#define SO_SSL_SET_SERVER (IOC_OUT|_SO_SSL|_SO_SSL_SERVER)

#define SO_SSL_GET_AUTH_CERT_HOOK

(IOC_IN |_SO_SSL|_SO_SSL_AUTH_CERT_HOOK)

#define SO_SSL_SET_AUTH_CERT_HOOK (IOC_OUT|_SO_SSL|_SO_SSL_AUTH_CERT_HOOK)

#define SO_SSL_GET_RSA_ENCRYPT_HOOK

(IOC_IN |_SO_SSL|_SO_SSL_RSA_ENCRYPT_HOOK)

#define SO_SSL_SET_RSA_ENCRYPT_HOOK (IOC_OUT|_SO_SSL|_SO_SSL_RSA_ENCRYPT_HOOK)

#define SO_SSL_GET_RSA_DECRYPT_HOOK

(IOC_IN |_SO_SSL|_SO_SSL_RSA_DECRYPT_HOOK)

#define SO_SSL_SET_RSA_DECRYPT_HOOK (IOC_OUT|_SO_SSL|_SO_SSL_RSA_DECRYPT_HOOK)

This WSAIoctl command is used to get/set the SSL flags associated with the socket. The lpvInBuffer points to a "WORD". The following flags exist:

#define SO_SSL_ENABLE 0x0001

#define SO_SSL_SERVER 0x0002

#define SO_SSL_AUTH_CLIENT 0x0004

#define SO_SSL_ACCEPT_WEAK 0x0008

The flags are set using the SO_SSL_SET_FLAGS command, while the status of the flags can be queried using the SO_SSL_GET_FLAGS command.

Setting the SO_SSL_ENABLE flag enables security on the socket. If this is done after a connection has already been established, then the SSL handshake protocol is performed before the next byte of data is transferred.

The SO_SSL_SERVER flag, when set, indicates that the socket is to be configured for server operation. In addition, the SO_SSL_AUTH_CLIENT flag indicates that the server will authenticate the client.

The SO_SSL_ACCEPT_WEAK flag, when set, instructs SSL to accept weakly checked certificates.

Strong certificate checking means that the SSL implementation has contacted the certificate issuer online and verified the validity of the certificate. Weak certificate checking means that no online check was performed.

This WSAIoctl command is used to get/set the privacy ciphers that SSL should attempt to use for the socket. The lpvInBuffer points to the following structure:

struct sslcipheropts {

int n;

char specs[3]; /* 3 bytes per n */

};

The value n specifies the number of ciphers (not the number of bytes of ciphers) and specs is an array of 3 byte values that contain the cipher specs. When SO_SSL_GET_CIPHERS is used, the structure is filled in with the ciphers that are supported by the socket. If WSAIoctl with SO_SSL_GET_CIPHERS is called before any changes are made to the socket via SO_SSL_SET_CIPHERS then the value returned will represent the underlying implementations abilities. If SO_SSL_SET_CIPHERS is used then the values are used as a replacement for the built in ciphers for the given socket.

For SO_SSL_SET_CIPHERS, the error EINVAL will be returned if a cipher is specified that is not supported by the implementation. The legal values for the ciphers specs are defined in the SSL specification document.

This WSAIoctl command is used to get/set the client data that SSL will use for the socket. The lpvInBuffe points to the following structure:

struct sslclientopts {

char *cert;

int certlen;

time_t sidtimeout;

int32 sidentries;

char *siddir;

};

cert and certlen are used to define the clients certificate. sidtimeout specifies the number of seconds that session-id's are allowed to live. sidentries defines the maximum number of entries to keep in the session-id cache. siddir defines the location of the temporary file used to hold the session-id cache when a temporary file is needed by the implementation.

The SSL implementation requires and guarantees MT-safe access to the session-id cache.

This WSAIoctl command is used to get/set the server data that SSL will use for the socket. The lpvInBuffer points to the following structure:

struct sslserveropts {

char *cert;

int certlen;

time_t sidtimeout;

int32 sidentries;

char *siddir;

};

cert and certlen are used to define the servers certificate. sidtimeout specifies the number of seconds that session-id's are allowed to live. sidentries defines the maximum number of entries to keep in the session-id cache. siddir defines the location of the temporary file used to hold the session-id cache when a temporary file is needed by the implementation.

The SSL implementation requires and guarantees MT-safe access to the session-id cache.

This WSAIoctl command is used to get/set the certificate authentication hook that SSL will use for the socket. The lpvInBuffer points to the following structure:

struct sslauthcertopts {

int type;

int (*func)(void *arg, char *cert, int len);

void *arg;

};

The SSL implementation will invoke the function with the supplied argument when a certificate arrives (either for server or client authentication). Only certificates of type will be authenticated using this function (see the SSL specification for a list of the supported certificate types). If no function exists for a given certificate type presented to the SSL implementation, the connection/handshake attempt will fail. Otherwise, the function authenticates the certificate and returns one of the following values:

#define SSL_ACH_OK 0

#define SSL_ACH_WEAK_OK 1

#define SSL_ACH_SHORT_DATA 2

#define SSL_ACH_LONG_DATA 3

#define SSL_ACH_BAD_DATA 4

#define SSL_ACH_BAD_SIG 5

#define SSL_ACH_CERT_EXPIRED 6

The SSL_ACH_OK value is returned when the certificate is good (the signature and validity periods are acceptable) and when the certificate has been verified through some external mechanism (for example, an online check with a certificate authority). The SSL_ACH_WEAK_OK value is returned under the same circumstances, except that no online verification has been performed.

The remaining values represent the kind of error conditions that might occur during certificate verification. SSL_ACH_BAD_DATA is returned when the data presented is improperly formatted. SSL_ACH_BAD_SIG is returned if the signature check fails. SSL_ACH_CERT_EXPIRED is returned if the certificate has expired.

This WSAIoctl command is used to get/set the RSA encryption hook that SSL will use for the socket. The lpvInBuffer points to the following structure:

struct sslrsaencrypthook {

int (*func)(void *arg, int blockType, char *dest, int *destlen,

char *src, int srclen);

void *arg;

};

This hook is used when the SSL implementation requires an RSA private or public key encryption. The blockType determines if the operation is a private or public key operation (only block types 0x01 and 0x02 are used by SSL; see PKCS#1 for more information). The dest and destlen values are used to return the encryption results. destlen is an input/output parameter with the input value defining the maximum storage area available at dest, and the output value containing the actual stored length of the encryption results. The src and srclen values define the input data. The following values are returned by the hook:

#define SSL_REH_OK 0

#define SSL_REH_BAD_TYPE 1

#define SSL_REH_BAD_LEN 2

SSL_REH_OK is returned if the encryption succeeded. SSL_REH_BAD_TYPE is returned if the blockType value is unacceptable. SSL_REH_BAD_LEN is returned if the srclen is too large to be encrypted in a single encryption, or if the dstlen value is too small to hold the encryption results.

This WSAIoctl command is used to get/set the RSA decryption hook that SSL will use for the socket. The lpvInBuffer points to the following structure:

struct sslrsadecrypthook {

int (*func)(void *arg, int blockType, char *dest, int *destlen,

char *src, int srclen);

void *arg;

};

This hook is used when the SSL implementation requires an RSA private or public key decryption. The blockType determines if the operation is a private or public key operation (only block types 0x01 and 0x02 are used by SSL; see PKCS#1 for more information). The dest and destlen values are used to return the decryption results. destlen is an input/output parameter with the input value defining the maximum storage area available at dest, and the output value containing the actual stored length of the decryption results. The src and srclen values define the input data. The following values are returned by the hook:

#define SSL_RDH_OK 0

#define SSL_RDH_BAD_TYPE 1

#define SSL_RDH_BAD_LEN 2

SSL_RDH_OK is returned if the decryption succeeded. SSL_RDH_BAD_TYPE is returned if the blockType value is unacceptable. SSL_RDH_BAD_LEN is returned if the srclen doesn't match the key's modulus length, or if the dstlen value is too small to hold the decryption results.

<Describe the recommended sequence for using SSL controls and standard WinSock calls to establish a secure connection>

<To be supplied>

Editors Note: The WinSock 2 wireless group is currently re-evaluating the planned definition of the NetDev device control API as a means to meet the requirements of wireless-aware applications. Other alternatives such as Desktop Management Interface (DMI) are under active consideration. The material which appeared here in the previous edition of this Annex has been elided until such time as these discussions produce a clear direction.

This section covers extensions to WinSock 2 that are specific to the use of wireless networks. It also describes aspects of base WinSock 2 functions that require special consideration or which may exhibit unique behavior when using such networks.

Address comments or questions regarding this material to:

Dale Buchholz

Motorola

drbuchholz@mot.com

Editors Note: After extensive consultations between experts on both WinSock and TAPI, a general consensus has emerged that networking applications can best meet their telephony needs by utilizing the Remote Network Access (also known as Remote Access Services) facilities of Windows ™ instead of directly accessing Windows Telephony API. Therefore, the material which appeared here in previous versions of the Annex has been elided.

This section describes mechanisms for using the Windows Sockets interface in conjunction with the Windows Telephony interface (TAPI). It was prepared by the WinSock Forum's Connection Oriented Media functionality group.

Address comments or questions regarding this material to:

Charlie Tai

Intel Architecture Labs

charlie_tai@ccm.jf.intel.com

18 April 1995

This section covers extensions to WinSock 2 that are specific to RSVP protocol. These extensions are needed to allow applications to request an enhanced quality-of-service (QoS) for their data flows using the RSVP protocol. The document assumes that the reader is familiar with the RSVP protocol as defined in

the RSVP version 1 specification (Internet draft draft-ietf-rsvp-spec-08 available from ftp://www.isi.edu/internet-drafts/draft-ietf-rsvp-spec-08.ps).

Address comments or questions regarding this material to:

Raj Yavatkar

Intel Corporation

yavatkar@ibeam.intel.com

RSVP protocol version 1, an IETF proposed standard, is a resource reservation setup protocol designed for an integrated services Internet. It provides support for reservation of resources for simplex, multicast or unicast data flows. An application uses the RSVP protocol to identify a data flow and to request a specific quality of service (QoS) from the network.

RSVP is a simplex protocol (i.e., it reserves resources in one direction) and the receiver(s) of a data flow are responsible for the initiation of resource reservation. RSVP operates on top of the Internet Protocol (IPv4 or IPv6) and is a control protocol similar to ICMP and routing protocols. RSVP is identified as a separate protocol (IP protocol id 46) within the AF_INET domain.

Under RSVP, requests for reservation are handled separately from the data transfer. Thus, an application establishes a data flow using an AF_INET socket (datagram or stream) in a conventional way and uses the data socket for transferring data over a unicast or multicast flow. In addition, for multicast applications, the application must specify appropriate options for the data socket to join/leave a multicast group. All the resource reservation transactions for a data flow must, however, be carried out using a separate, non-blocking RSVP socket (a SOCK_DGRAM socket with protocol id IPPROTO_RSVP)(1). All data packets addressed to the same destination belong to the same RSVP session, where the destination is defined by an IP destination (unicast or multicast) address, IP protocol identifier (i.e., UDP or TCP), and a port number. A given session may have several senders and, in the case of a multicast session, may also have multiple receivers; a sender or a receiver in a session is identified by an IP address and a port number.

Under RSVP, resource reservation requests are made by the data receivers. A reservation request contains a flowspec together with a filterspec. The flowspec specifies the desired QoS and the filterspec specifies which packets are to receive the specified QoS (e.g., based on the identity of a sender of data packets).

The data structures used in conjunction with WSAIoctl() call are defined in WS2RSVP.H (included at the end of the annex). These data structures describe the formats for session addresses, flowspecs, and filterspecs.

Due to the asynchronous nature of interaction between sender(s) and receivers in a RSVP session, all the RSVP calls are performed over the RSVP socket in a non-blocking mode. The RSVP API consists of a set of RSVP-specific control opcodes (dwIoControlCode parameter) specified as part of WSAIoctl() or WSPIoctl() calls over the RSVP socket as described below. It should be noted that an application may use a single RSVP socket to perform RSVP-related operations for multiple sessions and it need not open a separate RSVP socket for each data socket.

The soft-state nature of RSVP reservations inside the network requires end-systems to periodically generate refresh messages (PATH and RESERVE) and these messages can trigger errors or status notifications from the network at any time during a session. An application is notified of such status notifications and other changes in traffic or QoS specifications via FD_QOS event understood by WSAEventSelect and WSAAsyncSelect calls.

The following table describes RSVP-specific control codes and their meaning in the WSAIoctl()/WSPIoctl() call. The parameters lpOverlapped and lpCompletionRoutine are ignored in all the calls. An application must ensure that the lpvOutBuffer parameter contains address of the output buffer of appropriate size depending on the call. On successful return from the WSAIoctl() call, lpvOutBuffer is ignored unless specified otherwise in the following table. In case of an error in the WSAIoctl call, error-specific information is returned using the RSVP_ERROR structure in the output buffer lpvOutBuffer. In the case of retrieve and query_ QOS calls, the output buffer passed should be of size RSVP_RETURN_SIZE (defined in rsvp.h).

An RSVP sender or receiver must register with RSVP to create a RSVP session before it can make any QoS-related requests for the session. As part of the call, an application must indicate whether it wishes to be a sender or a receiver or both.

A sender uses the call to specify its traffic specifications (Tspec). The sender of a data flow is identified by its source address (IP address and port number binding in its data socket) and must be specified as a parameter. Other optional parameters include a policy object and an IP TTL (Time To Live) scope for the data packets.

A receiver initiates resource reservation(s) using this call. In case of a multi-homed host, the receiver may specify the interface address over which the requested reservation needs to be made. In the case of shared explicit and fixed filter style of reservations, several flow descriptors (one per reservation) may be supplied. An optional parameter includes a policy object.

A sender uses the call to leave a session.

A receiver uses this call to tear down one or more reservations for the session. For example, a receiver can tear down its reservations over a particular interface (host address), or tear down a particular reservation based on a filter specification.

An application makes this call when it receives a FD_QOS event notification. FD_QOS event is signaled when events such as receipt of new traffic specifications, errors in reservation, or changes in installed flow specifications have occurred. An application passes a pointer to RSVP_RETURN structure in outBuffer argument for the call to retrieve the cause of the event and more details about the event. The RSVP SP returns the relevant information as part of a RSVP_RETURN structure. RSVP_RETURN structure identifies the type of event and provide event-specific information (see the data structure definition in the header file). When the call is made, it is possible that more than one event notification is pending for the session. In that case, RSVP SP returns information about one event at a time and the application should make repeated retrieve calls to retrieve information about each event. The retrieve call returns WSAEWOULDBLOCK if no more event notifications are pending.

Information returned in a RSVP_RETURN structure may contain pointers to descriptors allocated by RSVP SP; these pointers point to areas separately allocated per session (and per socket) and are valid only until the next RSVP-specific ioctl call is made for the session. An application must be careful in using this information and must copy it to its own data area if it intends to use it beyond a single retrieve call.

The call is used to retrieve flow specifications (i.e., Tspecs and Rspecs) for one or more current senders in a session. Application passes a pointer to the RSVP_ QOSLIST structure in the argument outBuffer to retrieve the information. If number of filter specifications supplied (noFilts parameter) is zero in the Query_ QOS_DATA argument, the call returns the flow descriptors for all the current senders. Otherwise, the flow descriptors that match the specified filterspecs are returned. As in the case of the retrieve call, the RSVP_ QOSLIST returned in OutBuffer may contain pointers to descriptors allocated by SP and such pointers are valid only until the next RSVP-specific ioctl call is made for the session.

To allow policy-based input to the admission control process, RSVP assumes a policy component at each node. As input to the policy-based admission decision, RSVP messages may carry a policy object that includes information such as user credentials, account numbers, quotas, and so on. An application may pass a policy object as an optional argument to the RSVP_SENDER and RSVP_RESERVE calls.

An RSVP application can expect to receive the following status notifications in an asynchronous manner. It should be noted that these status notifications should not be treated as fatal errors. Instead, they should be viewed as advisory messages about the state of the reservation. For instance, a reservation error may simply indicate that the reservation you requested could not be installed (resulting in best effort service) and repeating the request with different parameter values may install the reservation.

· ResvErr - notification to a receiver is generated when a RESV request fails inside the network typically due to an admission control failure.

· PathErr - notification to a sender is generated in case of an error in propagation or installation of a PATH message from the sender.

· PathTear - notification arrives at a receiver when a sender initiates a teardown or a router on the path initiates a teardown as a result of state timeout.

· Confirm - notification arrives at a receiver in response to its reservation request. The notification is not necessarily a confirmation that the requested reservation is installed successfully at all the routers along the path of a reservation. Instead, it only indicates that the reservation request successfully reached some router along the path and was not rejected at the point when the conformation was sent.

· PathChange - a receiver is notified when new traffic specifications arrive from a sender.

· ResvChange - a receiver is notified when a previously installed reservation changes due to merging of multiple reservations from different receivers.

/*

** WS2RSVP.H - WinSock2 Extension for RSVP protocol

**

• * This file contains RSVP specific information for use
• * by WinSock2 compatible applications.

**

*/

/////////////////////////////////////////////////////////////////////////////////

//

// $Workfile: ws2rsvp.h $

// $Revision: 1.0 $

//

//

// DESCRIPTION:

// The API header file

//

////////////////////////////////////////////////////////////////////////////////

#ifndef _W2RSVPAPI

#define _W2RSVPAPI

#ifndef _WINSOCK2SPI

#include <w2spi.h>

#endif

// RSVP protocol specific number

#define IPPROTO_RSVP 0x2e

// Protocol specific commands for WSAIoctl()

#define SIO_RSVP_REGISTER 0xd02e0001

#define SIO_RSVP_SENDER 0xd02e0002

#define SIO_RSVP_RESERVE 0xd02e0003

#define SIO_RSVP_REL_SENDER 0xd02e0004

#define SIO_RSVP_REL_RESERVE 0xd02e0005

#define SIO_RSVP_RETRIEVE 0xd02e0006

#define SIO_RSVP_QUERY_ QOS 0xd02e0007

// IP version 4 addr

typedef struct tag_AddrIPv4

{

struct in_addr addr;

USHORT srcport;

} ADDR_IPv4;

// Sender Template Structure

typedef struct tag_tmpl

{

ADDR_IPV4 tmpl;

}RSVP_TEMPLATE;

// Filter Spec Structure

typedef struct tag_rsvpFilt

{

ADDR_IPv4 ipv4Filt;

} RSVP_FILTERSPEC;

// Session structure

typedef struct tag_sess

{

struct in_addr addr;

USHORT destPort;

BYTE protId;

} RSVP_SESSION;

// Policy structure

typedef struct tag_policy

{

char polType[256];

}RSVP_POLICY;

// FLOWSPEC and QoS are defined in winsock2.h

#define RSVP_FLOWSPEC QoS

//Tspec Structure

typedef struct tag_tspec

{

FLOWSPEC options;

int32 minPoliced;

int32 maxPktSize;

} RSVP_TSPEC;

//Rspec Structure

typedef struct tag_rspec

{

FLOWSPEC options;

int32 slackTerm;

} RSVP_RSPEC;

// Adspec structure

typedef struct tag_adspec

{

int gLevel;

int32 errTermC;

int32 errTermD;

int clLevel;

} RSVP_ADSPEC;

// Flowdesc Structure

typedef struct tag_flowdesc

{

RSVP_FLOWSPEC flow;

RSVP_POLICY policy;

int numFilts;

RSVP_FILTERSPEC FiltsList[];

}RSVP_FLOWDESC;

// Structure to be used while calling WSAIoctl()

// with SIO_RSVP_REGISTER

typedef struct tag_register

{

RSVP_SESSION sess;

USHORT regopt;

}REGISTER_DATA;

#define RSVP_SENDER 0x01

#define RSVP_RECEIVER 0x02

#define RSVP_SENRECV 0x03

// Structure to be used while calling WSAIoctl()

// with SIO_RSVP_SENDER as command

typedef struct tag_sender

{

RSVP_SESSION sess;

struct in_addr hostAddr;

USHORT hostPort;

RSVP_TSPEC tspec;

RSVP_POLICY policy; //Optional

int dataTTL; //Optional

}SENDER_DATA;

// Structure to be used while calling WSAIoctl()

// with SIO_RSVP_RESERVE as command

typedef struct tag_reserve

{

RSVP_SESSION sess;

struct in_addr hostAddr; //Optional

RSVP_POLICY policy; //Optional

int style;

int numFds;

RSVP_FLOWDESC fdList[]; // Required if style is SE, FF

}RESERVE_DATA;

// Structure to be used while calling WSAIoctl()

// with SIO_RSVP_RELEASE as command

typedef struct tag_relsender

{

RSVP_SESSION sess;

RSVP_TEMPLATE tmpl;

} REL_SENDER_DATA;

// Structure to be used while calling WSAIoctl()

// with SIO_RSVP_RELEASE as command

typedef struct tag_relreserve

{

RSVP_SESSION sess;

struct in_addr hostAddr; //Optional

int style;

int numFilts;

RSVP_FILTERSPEC filtList[];

} REL_RESERVE_DATA;

// Structure to be used while calling WSAIoctl()

// with SIO_RSVP_QUERY_ QOS as command

typedef struct tag_queryQOS

{

RSVP_SESSION sess;

int numFilts ; //Optional, if NULL, all filterspecs

RSVP_FILTERSPEC filtList[]; //for the session are returned

} QUERY_ QOS_DATA;

// Error Structure

typedef struct tag_error

{

RSVP_SESSION sess;

int errCode;

}RSVP_ERROR;

#define RSVP_RETURN_SIZE (sizeof(RSVP_ERROR))

// Return Structure. Used by service provider

// to return information to the application. This could be information about a

// path, path err,path tear, resv err, resv change

typedef struct tag_return

{

int infoType;

union

{

RSVP_SNDDESC *rsdesc; // for a path or path tear

RSVP_PATHERR rpatherr;

RSVP_RESVERR *rresverr;

RSVP_FLOWDESC *rresvchg;

}

} RSVP_RETURN;

// Sender Descriptor structure

typedef struct tag_snddesc

{

RSVP_SESSION sess;

RSVP_TMPL tmpl;

RSVP_TSPEC tspec;

RSVP_ADSPEC adspec;

} RSVP_SNDDESC;

typedef struct tag_patherr

{

BYTE ecode;

int evalue;

ADDR_IPv4 enodeadr;

RSVP_TMPL esnd;

RSVP_POLICY epolicy;

}RSVP_PATHERR;

typedef struct tag_resverr

{

BYTE ecode;

int evalue;

ADDR_IPv4 enodeadr;

RSVP_FLOWDESC rfds;

}RSVP_RESVERR;

// QOS List Structure

typedef struct taq_QOSlist

{

int numFds;

RSVP_FLOWDESC *fdList;

}RSVP_ QOSLIST;

// Error Codes.

#define RS_OK 01

#define RS_ADM_DELAY 02

#define RS_ADM_BW 03

#define RS_ADM_SERC 04

#define RS_ADM_SERU 05

#define RS_ADM_UNR 06

#define RS_POLICY_CRED 07

#define RS_POLICY_LAR 08

#define RS_POLICY_QUOTA 09

#define RS_POLICY_PREMPT 10

#define RS_PATH 11

#define RS_SENDER 12

#define RS_AMB 13

#define RS_FILT 14

#define RS_STYLE 15

#define RS_DSTP 16

#define RS_SRCP 17

#define RS_MISS_SESS 18

#define RS_MISS_STMPL 19

#define RS_MISS_STSPEC 20

#define RS_MISS_STYLE 21

#define RS_MISS_FLOW 22

#define RS_UNKN_SESS 23

#define RS_UNKN_STYLE 24

#define RS_UNKN_FLOWSPEC 25

#define RS_UNKN_FILT 26

#define RS_UNKN_STMPL 27

#define RS_UNKN_STSPEC 28

#define RS_UNKN_ADSPEC 29

#define RS_UNKN_POLICY 30

#define RS_UNKN_INTGR 31

#define RS_TC 32

#define RS_SYS 33

#define RS_ADMINC 34

// Explanation of the error codes mentioned above

// RS_OK Message interpreted successfully.

//

// RS_ADM_DELAY Admission control failure. This is returned when the

// reservation is rejected by admission control because the

// delay cannot be met.

// RS_ADM_BW Admission control failure.Returned when Requested bw not available

// RS_ADM_SERC Admission control failure.Returned when Service conflicts

// RS_ADM_SERU Admission control failure.Returned when Service is unsupported

// RS_ADM_UNR Admission control failure.Returned when there is an unreasonable request

//

// RS_POLICY_CRED Administrative Rejection, returned when the error is rejected

// for policy or administrative reason and the Required credentials

// are not present

// RS_POLICY_LAR Administrative Rejection, returned when Request is too large for

// policy reasons

// RS_POLICY_QUOTA Administrative Rejection, returned when there is Insufficient quota

// or balance (accounting)

// RS_POLICY_PREMPT Administrative Rejection, returned when there is Administrative preemption

//

//

// RS_PATH No Path Information for this RESV, returned after a

// reservation is requested and RSVP waits for a certain timeout

// to receive PATH information.

//

// RS_SENDER No sender information for this RESV. returned when the there

// is path state but it does not include the sender specified in

// one of the Filterspecs.

//

// RS_AMB Ambiguous Path, Sender port appears to be both zero and non zero

// in the same session.

//

// RS_FILT Ambiguous FilterSpec, Filterspec matches more than one sender

// in a style that requires a unique match.

//

// RS_STYLE Conflicting or Unknown Style,Reservation style conflicts with

// the style of an existing reservation or it is an unknown style.

//

// RS_DSTP Conflicting dest. port. Sessions for the same destination

// address and protocol have appeared with both zero and

// non zero dest. port fields.

//

// RS_SRCP Conflicting source port, the source port is non zero in a

// filterspec or a sender template for a destination with port

// zero.

//

// RS_MISS_SESS Missing a required object, RSVP was unable to construct a message

// since a required object,SESSION was missing.

// RS_MISS_STSPEC Missing a required object, RSVP was unable to construct a message

// since a required object,sender TSPEC was missing

// RS_MISS_STMPL For a multi-homed host, the hostaddr field was missing.

// RS_MISS_STYLE The reserve message did not contain a style

// RS_MISS_FLOW The reserve message did not contain a FLOWSPEC object

// RS_UNKN_SESS Unknown object, RSVP cannot recognise a field sent in the message

// or there is an error in one of the fields.Unknown SESSION

// RS_UNKN_STYLE Unknown object,STYLE

// RS_UNKN_FLOW Unknown object,FLOWSPEC

// RS_UNKN_FILT Unknown object,FILTERSPEC

// RS_UNKN_STMPL Unknown object,SENDER_TEMPLATE

// RS_UNKN_STSPEC Unknown object,SENDER_TSPEC

// RS_UNKN_ADSPEC Unknown object,SENDER_ADSPEC

// RS_UNKN_POLICY Unknown object,POLICY

// RS_UNKN_INTGR Unknown object,INTEGRITY

//

//

//

// RS_TC Error reported by traffic control module.

//

// RS_SYS An RSVP system error,any implementation specific error of

// required.

//

// RS_ADMINC Reservation made is greater than requested due to merging.

(1) A single RSVP socket may be shared among multiple sessions.

Go To WinSock 2 Annex, Part 1, Chapters 1 - 5