1 /***************************************************************************
2  * Copyright (c) 2024 Microsoft Corporation
3  *
4  * This program and the accompanying materials are made available under the
5  * terms of the MIT License which is available at
6  * https://opensource.org/licenses/MIT.
7  *
8  * SPDX-License-Identifier: MIT
9  **************************************************************************/
10 
11 
12 /**************************************************************************/
13 /**************************************************************************/
14 /**                                                                       */
15 /** NetX Component                                                        */
16 /**                                                                       */
17 /**   Internet Control Message Protocol (ICMP)                            */
18 /**                                                                       */
19 /**************************************************************************/
20 /**************************************************************************/
21 
22 
23 /**************************************************************************/
24 /*                                                                        */
25 /*  COMPONENT DEFINITION                                   RELEASE        */
26 /*                                                                        */
27 /*    nx_icmpv4.h                                         PORTABLE C      */
28 /*                                                           6.1.9        */
29 /*  AUTHOR                                                                */
30 /*                                                                        */
31 /*    Yuxin Zhou, Microsoft Corporation                                   */
32 /*                                                                        */
33 /*  DESCRIPTION                                                           */
34 /*                                                                        */
35 /*    This file defines the NetX Internet Control Message Protocol (ICMP) */
36 /*    component, including all data types and external references.  It is */
37 /*    assumed that nx_api.h and nx_port.h have already been included.     */
38 /*                                                                        */
39 /*  RELEASE HISTORY                                                       */
40 /*                                                                        */
41 /*    DATE              NAME                      DESCRIPTION             */
42 /*                                                                        */
43 /*  05-19-2020     Yuxin Zhou               Initial Version 6.0           */
44 /*  09-30-2020     Yuxin Zhou               Modified comment(s),          */
45 /*                                            resulting in version 6.1    */
46 /*  10-15-2021     Yuxin Zhou               Modified comment(s), included */
47 /*                                            necessary header file,      */
48 /*                                            resulting in version 6.1.9  */
49 /*                                                                        */
50 /**************************************************************************/
51 
52 #ifndef NX_ICMPV4_H
53 #define NX_ICMPV4_H
54 
55 #include "nx_api.h"
56 
57 #ifndef NX_DISABLE_IPV4
58 /* Define ICMP types and codes.  According to RFC792.  */
59 
60 /* Define ICMP types.  */
61 #define NX_ICMP_ECHO_REPLY_TYPE       0
62 #define NX_ICMP_DEST_UNREACHABLE_TYPE 3
63 /*
64 #define NX_ICMP_SOURCE_QUENCH_TYPE    4
65 #define NX_ICMP_REDIRECT_TYPE         5
66  */
67 #define NX_ICMP_ECHO_REQUEST_TYPE     8
68 #define NX_ICMP_TIME_EXCEEDED_TYPE    11
69 #define NX_ICMP_PARAMETER_PROB_TYPE   12
70 #define NX_ICMP_TIMESTAMP_REQ_TYPE    13
71 /*
72 #define NX_ICMP_TIMESTAMP_REP_TYPE    14
73 #define NX_ICMP_INFORMATION_REQ_TYPE  15
74 #define NX_ICMP_INFORMATION_REP_TYPE  16
75 #define NX_ICMP_ADDRESS_MASK_REQ_TYPE 17
76 #define NX_ICMP_ADDRESS_MASK_REP_TYPE 18
77  */
78 
79 /* Define the ICMP Destination Unreachable Message codes.  */
80 /*
81 #define NX_ICMP_NETWORK_UNREACH_CODE  0
82 #define NX_ICMP_HOST_UNREACH_CODE     1
83  */
84 #define NX_ICMP_PROTOCOL_UNREACH_CODE 2
85 #define NX_ICMP_PORT_UNREACH_CODE     3
86 /*
87 #define NX_ICMP_FRAMENT_NEEDED_CODE   4
88 #define NX_ICMP_SOURCE_ROUTE_CODE     5
89  */
90 
91 /* Define the TIME Exceeded codes.  */
92 /*
93 #define NX_ICMP_TTL_EXCEEDED_CODE     0
94  */
95 #define NX_ICMP_FRT_EXCEEDED_CODE     1
96 
97 /* Define the Zero Code for Parameter Problem Message, Source Quench Message, Redirect Message,
98    Echo Request/Reply, Timestamp Request/Reply and Information Request/Reply Message .  */
99 #define NX_ICMP_ZERO_CODE             0
100 
101 /* Define Basic ICMP packet header data type.  This will be used to
102    build new ICMP packets and to examine incoming packets into NetX.  */
103 
104 typedef  struct NX_ICMP_HEADER_STRUCT
105 {
106     /* Define the first 32-bit word of the ICMP header.  This word contains
107        the following information:
108 
109             bits 31-24  ICMP 8-bit type defined as follows:
110 
111                                         Type Field      ICMP Message Type
112 
113                                             0           Echo Reply
114                                             3           Destination Unreachable
115                                             4           Source Quench
116                                             5           Redirect (change a route)
117                                             8           Echo Request
118                                             11          Time exceeded for Datagram
119                                             12          Parameter Problem on a Datagram
120                                             13          Timestamp Request
121                                             14          Timestamp Reply
122                                             17          Address Mask Request
123                                             18          Address Mask Reply
124 
125             bits 23-16  ICMP 8-bit code defined as follows:
126 
127                                         Code Field      ICMP Code Meaning
128 
129                                             0           Network unreachable
130                                             1           Host unreachable
131                                             2           Protocol unreachable
132                                             3           Port unreachable
133                                             4           Fragmentation needed and DF is set
134                                             5           Source route failed
135                                             6           Destination network unknown
136                                             7           Destination host unknown
137                                             8           Source host isolated
138                                             9           Communication with destination network
139                                                             administratively prohibited
140                                             10          Communication with destination host
141                                                             administratively prohibited
142                                             11          Network unreachable for type of service
143                                             12          Host unreachable for type of service
144 
145             bits 15-0   ICMP 16-bit checksum
146 
147      */
148 
149     ULONG nx_icmp_header_word_0;
150 
151     /* Define the second and final word of the ICMP header.  This word contains
152        the following information:
153 
154             bits 31-16  ICMP 16-bit Identification
155             bits 15-0   ICMP 16-bit Sequence Number
156      */
157     ULONG nx_icmp_header_word_1;
158 } NX_ICMP_HEADER;
159 
160 /* Define the ICMP echo request header message size.  */
161 
162 #define NX_ICMP_HEADER_SIZE sizeof(NX_ICMP_HEADER)
163 
164 
165 /* Define basic ICMPv4 packet header data type. */
166 
167 typedef  struct NX_ICMPV4_HEADER_STRUCT
168 {
169 
170     /*  Header field for ICMPv4 message type */
171     UCHAR   nx_icmpv4_header_type;
172 
173     /*  Header field for ICMPv4 message code (type context specific) */
174     UCHAR   nx_icmpv4_header_code;
175 
176     /*  Header field for ICMPv4 header checksum */
177     USHORT  nx_icmpv4_header_checksum;
178 } NX_ICMPV4_HEADER;
179 
180 /* Define ICMPv4 error message type. */
181 
182 typedef struct NX_ICMPV4_ERROR_STRUCT
183 {
184     /* General ICMP header. */
185     NX_ICMPV4_HEADER nx_icmpv4_error_header;
186 
187     /* Pointer to the original IPv4 packet where error is detected. */
188     ULONG            nx_icmpv4_error_pointer;
189 } NX_ICMPV4_ERROR;
190 
191 /* ICMP echo request message type. */
192 
193 typedef struct NX_ICMPV4_ECHO_STRUCT
194 {
195 
196     /* General ICMP header. */
197     /*lint -esym(768,NX_ICMPV4_ECHO_STRUCT::nx_icmpv4_echo_header) suppress member not referenced. It is used before casting from NX_ICMPV4_HEADER. */
198     NX_ICMPV4_HEADER nx_icmpv4_echo_header;
199 
200     /* Echo request message ID */
201     /*lint -esym(768,NX_ICMPV4_ECHO_STRUCT::nx_icmpv4_echo_identifier) suppress member not referenced. It is not used as a host. */
202     USHORT           nx_icmpv4_echo_identifier;
203 
204     /* Echo request message sequence number */
205     USHORT           nx_icmpv4_echo_sequence_num;
206 } NX_ICMPV4_ECHO;
207 
208 
209 #ifndef NX_DISABLE_ICMPV4_ERROR_MESSAGE
210 /* Define macros for sending out ICMPv4 error messages. */
211 #define NX_ICMPV4_SEND_DEST_UNREACHABLE(ip_ptr, packet, code) \
212     _nx_icmpv4_send_error_message((ip_ptr), (packet), (ULONG)((NX_ICMP_DEST_UNREACHABLE_TYPE << 24) | ((code) << 16)), 0)
213 
214 #define NX_ICMPV4_SEND_TIME_EXCEED(ip_ptr, packet, code) \
215     _nx_icmpv4_send_error_message((ip_ptr), (packet), (ULONG)((NX_ICMP_TIME_EXCEEDED_TYPE << 24) | ((code) << 16)), 0)
216 
217 #define NX_ICMPV4_SEND_PARAMETER_PROBLEM(ip_ptr, packet, code, offset) \
218     _nx_icmpv4_send_error_message((ip_ptr), (packet), (ULONG)((NX_ICMP_PARAMETER_PROB_TYPE << 24) | ((code) << 16)), (offset))
219 
220 #endif /* NX_DISABLE_ICMPV4_ERROR_MESSAGE */
221 
222 
223 /* Define service for sending ICMPv4 error messages. */
224 
225 #ifndef NX_DISABLE_ICMPV4_ERROR_MESSAGE
226 VOID _nx_icmpv4_send_error_message(NX_IP *ip_ptr, NX_PACKET *packet, ULONG word1, ULONG pointer);
227 #endif /* NX_DISABLE_ICMPV4_ERROR_MESSAGE */
228 
229 /* Define internal ICMPv4 handling functions. */
230 
231 VOID _nx_icmp_packet_process(NX_IP *ip_ptr, NX_PACKET *packet_ptr);
232 VOID _nx_icmp_queue_process(NX_IP *ip_ptr);
233 VOID _nx_icmpv4_packet_process(NX_IP *ip_ptr, NX_PACKET *packet_ptr);
234 VOID _nx_icmpv4_process_echo_reply(NX_IP *ip_ptr, NX_PACKET *packet_ptr);
235 VOID _nx_icmpv4_process_echo_request(NX_IP *ip_ptr, NX_PACKET *packet_ptr);
236 UINT _nx_icmp_interface_ping(NX_IP *ip_ptr, ULONG ip_address,
237                              NX_INTERFACE *interface_ptr, ULONG next_hop_address,
238                              CHAR *data_ptr, ULONG data_size,
239                              NX_PACKET **response_ptr, ULONG wait_option);
240 #endif /* NX_DISABLE_IPV4 */
241 
242 
243 /* Define ICMPv4 API function prototypes. */
244 
245 UINT _nx_icmp_enable(NX_IP *ip_ptr);
246 UINT _nx_icmp_info_get(NX_IP *ip_ptr, ULONG *pings_sent, ULONG *ping_timeouts,
247                        ULONG *ping_threads_suspended, ULONG *ping_responses_received,
248                        ULONG *icmp_checksum_errors, ULONG *icmp_unhandled_messages);
249 UINT _nx_icmp_ping(NX_IP *ip_ptr, ULONG ip_address, CHAR *data, ULONG data_size,
250                    NX_PACKET **response_ptr, ULONG wait_option);
251 
252 /* Define error checking shells for API services.  These are only referenced by the
253    application.  */
254 
255 UINT _nxe_icmp_enable(NX_IP *ip_ptr);
256 UINT _nxe_icmp_info_get(NX_IP *ip_ptr, ULONG *pings_sent, ULONG *ping_timeouts,
257                         ULONG *ping_threads_suspended, ULONG *ping_responses_received,
258                         ULONG *icmp_checksum_errors, ULONG *icmp_unhandled_messages);
259 UINT _nxe_icmp_ping(NX_IP *ip_ptr, ULONG ip_address, CHAR *data, ULONG data_size,
260                     NX_PACKET **response_ptr, ULONG wait_option);
261 
262 
263 #endif
264 
265