Merge pull request #3 from rtckit/v0.6.2

v0.6.2

Author: cdosoftei

CHANGELOG.md

@@ -1,13 +1,15 @@
 ### To Do
  * Failed operations to throw Exceptions over issuing PHP warnings (via a toggle)
+ * Improved documentation
+ * IPv6 oriented tests
  * Expose useful data pointers via `stream_metadata` (accessible through `stream_get_meta_data`)
- * Add tests covering stream closing
- * Add tests covering packet injection
- * Validate `php_url_parse` returns a `host` property (the network device name)
 
-### Upcoming Release
+### 0.6.2
  * Improved UDP/DNS tests
  * Selectable file descriptor (for `stream_cast`) is now cached
+ * Validates `php_url_parse` succeeds and returns a `host` property (the network device name)
+ * Packet injection tests, via ARP
+ * Strict type enforcement within tests
 
 ### 0.6.0
  * First public release

Makefile

@@ -4,8 +4,5 @@ REPOSITORY=rtckit/php-pcap-ext-dev
 image:
 	docker build -t ${REPOSITORY} .
 
-local-image:
-	docker build -v `pwd`:/usr/src/php-pcap-ext:rw -t ${REPOSITORY} .
-
 run: image
-	docker run --rm -t ${REPOSITORY}
+	docker run --rm -it ${REPOSITORY}

README.md

@@ -2,13 +2,13 @@
 
 Stream driven PHP packet capture extension.
 
-[![Build Status](https://travis-ci.com/rtckit/php-pcap-ext.svg?branch=master)](https://travis-ci.com/rtckit/php-pcap-ext) ![Version](https://img.shields.io/badge/version-v0.6.0-green) ![License](https://img.shields.io/badge/license-MIT-blue)
+[![Build Status](https://travis-ci.com/rtckit/php-pcap-ext.svg?branch=master)](https://travis-ci.com/rtckit/php-pcap-ext) ![Version](https://img.shields.io/badge/version-v0.6.2-green) ![License](https://img.shields.io/badge/license-MIT-blue)
 
 ## Usage
 
-The `pcap` extension has been developed against PHP 7.4+ and regularly tested against the upcoming PHP 8.
+The `pcap` extension has been developed against PHP 7.4+ and regularly tested against the nightly PHP 8 build; from an operating system perspective, the ubiquity of Linux makes it the only target. The supported architectures are x86_64 and arm64.
 
-The extension provides bindings for [libpcap](https://github.com/the-tcpdump-group/libpcap) and exposes its functionality via PHP streams; the packet formatting is consistent with the `pcap` file format (learn more [here](https://wiki.wireshark.org/Development/LibpcapFileFormat) and [here](https://formats.kaitai.io/pcap/index.html)). The functionality is deliberately limited to I/O operations, the actual packet parsing/crafting should be performed using pure PHP; such supporting libraries will be open sourced soon.
+The extension provides bindings for [libpcap](https://github.com/the-tcpdump-group/libpcap) and exposes its functionality via PHP streams; the packet formatting is consistent with the `pcap` file format (learn more [here](https://wiki.wireshark.org/Development/LibpcapFileFormat) and [here](https://formats.kaitai.io/pcap/index.html)). The functionality is deliberately limited to I/O operations, the actual packet parsing/crafting should be performed using pure PHP (some relevant supporting libraries to be published soon).
 
 It's also worth familiarizing yourself with [libpcap and tcpdump](https://www.tcpdump.org/index.html).
 
@@ -60,6 +60,9 @@ array(4) {
 */
 
 // process($frame) ...
+
+// Inject raw packets (including the link layer data) by writing to the stream
+$count = fwrite($fp, $packet);
 ```
 
 The [tests](https://github.com/rtckit/php-pcap-ext/tree/master/tests) directory show cases some usage examples.
@@ -76,19 +79,23 @@ make
 
 ## Tests
 
-Before running the test suite, make sure the user has the ability to capture network packets (root or CAP_RAW).
+Before running the test suite, make sure the user has the ability to capture network packets (root or `CAP_NET_RAW`).
 
 ```sh
 make test
 ```
 
+## FFI Alternative
+
+A fully compilable [FFI packet capture](https://github.com/rtckit/php-pcap-ffi) package is also available; the underlying environment would still have the provide the libpcap library as well as the FFI dependencies (libffi and the PHP FFI extension). Otherwise, the FFI package can be used as a drop-in replacement when it makes sense to do so.
+
 ## License
 
 MIT, see [LICENSE file](LICENSE).
 
 ### Acknowledgments
 
-* [libpcap](https://github.com/the-tcpdump-group/libpcap)
+* [libpcap](https://github.com/the-tcpdump-group/libpcap) by The Tcpdump Group, BSD licensed.
 
 ### Contributing
 

pcap.c

@@ -332,7 +332,19 @@ static php_stream *php_pcap_fopen(php_stream_wrapper *wrapper, const char *path,
   close(raw);
 
   php_url *parsed_url = php_url_parse(path);
-  pcap_if_t* alldevsp = NULL;
+
+  if (!parsed_url) {
+    php_error_docref(NULL, E_WARNING, "Cannot parse pcap URL");
+
+    return NULL;
+  }
+
+  if (!parsed_url->host || !strlen(parsed_url->host->val)) {
+    php_error_docref(NULL, E_WARNING, "Missing host, should be device's name");
+    php_url_free(parsed_url);
+
+    return NULL;
+  }
 
   if (!parsed_url->scheme) {
     php_error_docref(NULL, E_WARNING, "Missing scheme, should be 'pcap'");
@@ -381,6 +393,8 @@ static php_stream *php_pcap_fopen(php_stream_wrapper *wrapper, const char *path,
 
   php_url_free(parsed_url);
 
+  pcap_if_t* alldevsp = NULL;
+
   if (pcap_findalldevs(&alldevsp, sess->errbuf)) {
     php_error_docref(NULL, E_WARNING, "Cannot enumerate network devices: %s", sess->errbuf);
     pcap_close_session(sess);

php_pcap.h

@@ -9,7 +9,7 @@
 extern zend_module_entry pcap_module_entry;
 # define phpext_pcap_ptr &pcap_module_entry
 
-# define PHP_PCAP_VERSION "0.6.0"
+# define PHP_PCAP_VERSION "0.6.2"
 
 # if defined(ZTS) && defined(COMPILE_DL_PCAP)
 ZEND_TSRMLS_CACHE_EXTERN()

tests/001.phpt

@@ -5,6 +5,8 @@ extension_loaded pcap
 --FILE--
 <?php
 
+declare(strict_types = 1);
+
 var_dump(extension_loaded('pcap'));
 
 print "done!";

tests/002.phpt

@@ -5,6 +5,8 @@ stream_get_wrappers pcap
 --FILE--
 <?php
 
+declare(strict_types = 1);
+
 var_dump(in_array('pcap', stream_get_wrappers()));
 
 print "done!";

tests/003.phpt

@@ -5,6 +5,8 @@ fopen devices from net_get_interfaces
 --FILE--
 <?php
 
+declare(strict_types = 1);
+
 $devs = 0;
 
 foreach (array_keys(net_get_interfaces()) as $dev) {

tests/004.phpt

@@ -5,6 +5,8 @@ fopen against bogus devices
 --FILE--
 <?php
 
+declare(strict_types = 1);
+
 $fp = fopen('pcap://' . uniqid('bogus'), 'r');
 var_dump($fp);
 

tests/005.phpt

@@ -5,6 +5,8 @@ fopen against bogus URLs
 --FILE--
 <?php
 
+declare(strict_types = 1);
+
 $dev = current(array_keys(net_get_interfaces()));
 if (!$dev) {
   die('Cannot find any viable network devices');
@@ -13,6 +15,15 @@ if (!$dev) {
 $fp = fopen('pcap.bogus://' . $dev, 'r');
 var_dump($fp);
 
+$fp = fopen('pcap://', 'r');
+var_dump($fp);
+
+$fp = fopen('pcap:///', 'r');
+var_dump($fp);
+
+$fp = fopen('pcap:///path', 'r');
+var_dump($fp);
+
 $fp = fopen('pcap://' . $dev . '/path', 'r');
 var_dump($fp);
 
@@ -27,6 +38,21 @@ Warning: fopen(): Unable to find the wrapper "pcap.bogus" - did you forget to en
 Warning: fopen(pcap.bogus://%s): %s to open stream: No such file or directory in %s on line %d
 bool(false)
 
+Warning: fopen(): Cannot parse pcap URL in %s on line %d
+
+Warning: fopen(pcap://): %s to open stream: operation failed in %s on line %d
+bool(false)
+
+Warning: fopen(): Cannot parse pcap URL in %s on line %d
+
+Warning: fopen(pcap:///): %s to open stream: operation failed in %s on line %d
+bool(false)
+
+Warning: fopen(): Cannot parse pcap URL in %s on line %d
+
+Warning: fopen(pcap:///path): %s to open stream: operation failed in %s on line %d
+bool(false)
+
 Warning: fopen(): Unsupported path: /path in %s on line %d
 
 Warning: fopen(pcap://%s/path): %s to open stream: operation failed in %s on line %d

tests/006.phpt

@@ -5,6 +5,8 @@ fopen without privileges
 --FILE--
 <?php
 
+declare(strict_types = 1);
+
 $dev = current(array_keys(net_get_interfaces()));
 if (!$dev) {
   die('Cannot find any viable network devices');

tests/007.phpt

@@ -5,6 +5,8 @@ fread ICMP ping traffic
 --FILE--
 <?php
 
+declare(strict_types = 1);
+
 require('helpers.php');
 
 $ip = gethostbyname('example.com');

tests/008.phpt

@@ -5,6 +5,8 @@ fread UDP DNS traffic
 --FILE--
 <?php
 
+declare(strict_types = 1);
+
 require('helpers.php');
 
 // Use OpenDNS public nameservers

tests/009.phpt

@@ -5,6 +5,8 @@ fread TCP HTTP traffic
 --FILE--
 <?php
 
+declare(strict_types = 1);
+
 require('helpers.php');
 
 $ip = gethostbyname('example.com');

tests/010.phpt

@@ -0,0 +1,134 @@
+--TEST--
+fwrite/fread ARP to IPv4 gateway
+--SKIPIF--
+<?php if (!extension_loaded('pcap')) { echo 'skip'; } ?>
+--FILE--
+<?php
+
+declare(strict_types = 1);
+
+require('helpers.php');
+
+$dev = $gw = null;
+
+foreach (getRoutingTable() as $record) {
+  if (!empty($record['Iface']) && !empty($record['Gateway']) && ($record['Gateway'] !== '00000000')) {
+    $dev = $record['Iface'];
+    $hex = $record['Gateway'];
+    $gw = [];
+
+    while (strlen($hex)) {
+      $byte = hexdec(substr($hex, -2));
+      $hex = substr($hex, 0, -2);
+      $gw[] = $byte;
+    }
+
+    $gw = implode('.', $gw);
+    break;
+  }
+}
+
+if (is_null($dev)) {
+  die('Cannot find a suitable network device');
+}
+
+$mac = trim(file_get_contents('/sys/class/net/' . $dev . '/address'));
+$ip = null;
+
+foreach (net_get_interfaces()[$dev]['unicast'] as $config) {
+  if ($config['family'] == 2) {
+    $ip = $config['address'];
+    break;
+  }
+}
+
+var_dump($dev);
+var_dump($mac);
+var_dump($ip);
+var_dump($gw);
+
+$packet = craftEthernet2Frame([
+  'destination' => 'ff:ff:ff:ff:ff:ff',
+  'source' => $mac,
+  'etherType' => 0x0806,
+  'data' => craftArpFrame([
+    'htype' => 1,
+    'ptype' => 0x0800,
+    'hsize' => 6,
+    'psize' => 4,
+    'opcode' => 1,
+    'senderEtherAddress' => $mac,
+    'senderProtoAddress' => $ip,
+    'targetEtherAddress' => '00:00:00:00:00:00',
+    'targetProtoAddress' => $gw,
+  ]),
+]);
+
+var_dump(strlen($packet));
+
+$context = stream_context_create([
+  'pcap' => [
+    'snaplen'   => 2048,
+    'immediate' => true,
+    'timeout'   => 0.100,
+    'filter'    => 'arp',
+  ],
+]);
+
+$fp = fopen('pcap://' . $dev, 'rw', false, $context);
+
+if (!$fp) {
+  die('Cannot initiate packet capture');
+}
+
+var_dump($fp);
+
+// Trigger capture activation, expect nothing to read
+var_dump(fread($fp, 16));
+
+$bytes = fwrite($fp, $packet);
+var_dump($bytes);
+
+$captures = [$fp];
+$read = [];
+$write = $except = null;
+
+$gwMac = null;
+
+while (!$gwMac) {
+  $read = $captures;
+
+  if (stream_select($read, $write, $except, 0, 100000)) {
+    foreach ($read as $r) {
+      while ($_header = fread($r, 16)) {
+        $header = unpack('LtsSec/LtsUsec/LcapLen/Llen', $_header);
+        $frame = parseEthernet2Frame(fread($r, $header['capLen']));
+
+        if ($frame['etherType'] == 0x0806) { // ARP
+          $arp = parseArpFrame($frame['data']);
+
+          if (($arp['opcode'] == 2) && ($arp['senderProtoAddress'] == $gw) && ($arp['targetProtoAddress'] == $ip) && ($arp['targetEtherAddress'] == $mac)) {
+            $gwMac = $arp['senderEtherAddress'];
+            break;
+          }
+        }
+      }
+    }
+  }
+}
+
+var_dump($gwMac);
+
+print "done!";
+?>
+--EXPECTF--
+string(%d) "%s"
+string(17) "%x:%x:%x:%x:%x:%x"
+string(%d) "%d.%d.%d.%d"
+string(%d) "%d.%d.%d.%d"
+int(42)
+resource(%d) of type (stream)
+string(0) ""
+int(42)
+string(17) "%x:%x:%x:%x:%x:%x"
+done!