-
Notifications
You must be signed in to change notification settings - Fork 0
/
pktsio.html
204 lines (180 loc) · 9.93 KB
/
pktsio.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
---
title: The Protocol
layout: default
menu: pkts.html
active_element: pktsio
pktsio_version: 3.0.2
---
<div class="row row-offcanvas row-offcanvas-right">
<div>
<p class="pull-right visible-xs">
<button type="button" class="btn btn-primary btn-xs" data-toggle="offcanvas">Toggle nav</button>
</p>
<div class="row col-md-9">
<!-- Pkts.io Intro Section -->
<!-- <div id="intro" class="col-9 col-sm-9 col-lg-9"> -->
<div class="col-xs-12">
<div id="intro">
<h1>pkts.io</h1>
<p> pkts.io is a pure java library for reading and writing pcaps. It's primary
purpose is to manipulate/analyze existing pcaps, allowing you to build various
tools around pcaps.
</p>
</div>
<div id="intro-load-pcap">
<h3>Load a pcap</h3>
<p>
Example, load a pcap from file and print the content of each UDP packet to
standard out.
</p>
{% highlight java %}
final Pcap pcap = Pcap.openStream("my_traffic.pcap");
pcap.loop(new PacketHandler() {
@Override
public void nextPacket(final Packet packet) throws IOException {
if (packet.hasProtocol(Protocol.UDP)) {
System.out.println(packet.getPacket(Protocol.UDP).getPayload());
}
}
});
{% endhighlight %}
<p>
<a href="https://gist.github.com/aboutsip/5896046">View gist</a> which also contains comments.
</p>
</div>
<div id="intro-streams">
<h3>Streams</h3>
<p>
Pkts.io also contains a higher level of abstraction – streams. Quite often you may want to manipulate a stream of related messages and by using the stream support offered by pkts.io, you can do so. What a stream represents depends on the underlying protocol. E.g., for UDP, a stream is all the messages that is sent/received from the same local and remote port-pair. If you deal with SIP, all SIP messages that belongs to the same SIP Dialog are considered to belong to the same stream.
</p>
<p>Example, load a pcap from file and consume all SIP Streams. </p>
{% highlight java %}
final Pcap pcap = Pcap.openStream("my_traffic.pcap");
final StreamHandler streamHandler = new DefaultStreamHandler();
streamHandler.addStreamListener(new StreamListener<SipPacket>() {
@Override
public void startStream(final Stream<SipPacket> stream, final SipPacket packet) {
System.out.println("New SIP stream detected. Stream id: "
+ stream.getStreamIdentifier());
System.out.println("SipMessage was: " + packet.getInitialLine());
}
@Override
public void packetReceived(final Stream<SipPacket> stream, final SipPacket packet) {
System.out.println("Received a new SIP message for stream: "
+ stream.getStreamIdentifier());
System.out.println("SipMessage was: " + packet.getInitialLine());
}
@Override
public void endStream(final Stream<SipPacket> stream) {
System.out.println("The stream ended. Stream id: "
+ stream.getStreamIdentifier());
}
});
pcap.loop(streamHandler);
{% endhighlight %}
<p>
<a href="https://gist.github.com/aboutsip/5896237">View gist</a> which also contains comments.
</p>
</div>
</div><!--/span-->
<div class="col-xs-12" id="intro-consume-it">
<h3>Consume It</h3>
<p>pkts.io is available through Maven Central so just include the following Maven artifact and you are good to go:
</p>
{% highlight xml %}
<dependency>
<groupId>io.pkts</groupId>
<artifactId>pkts-core</artifactId>
<version>{{ page.pktsio_version }}</version>
<type>jar</type>
</dependency>
{% endhighlight %}
<p> Or if you want to use the stream support, then just include the following:
</p>
{% highlight xml %}
<dependency>
<groupId>io.pkts</groupId>
<artifactId>pkts-streams</artifactId>
<version>{{ page.pktsio_version }}</version>
<type>jar</type>
</dependency>
{% endhighlight %}
</div><!--/span-->
<div class="col-xs-12" id="intro-javadoc">
<h3>Javadoc</h3>
<p>Javadocs for all releases are hosted by our friends at <a href="www.javadoc.io">javadoc.io</a> and the current release of pkts.io is accessed through the following links:
<ul>
<li><a href="http://www.javadoc.io/doc/io.pkts/pkts-buffers/{{page.pktsio_version}}"><code>Buffers</code></a></li>
<li><a href="http://www.javadoc.io/doc/io.pkts/pkts-core/{{page.pktsio_version}}"><code>Core</code></a></li>
<li><a href="http://www.javadoc.io/doc/io.pkts/pkts-sip/{{page.pktsio_version}}"><code>SIP</code></a></li>
<li><a href="http://www.javadoc.io/doc/io.pkts/pkts-streams/{{page.pktsio_version}}"><code>Streams</code></a></li>
</ul>
</p>
</div><!--/span-->
<div class="col-xs-12" id="examples">
<h1>Examples</h1>
<p>The pkts-examples contains a bunch of different examples showing the various features of the raw frame handling as well as the higher abstraction of streams. Please see the pkts.io example repository on <a href="https://github.com/aboutsip/pkts/tree/master/pkts-examples/src/main/java/io/pkts/examples">github.com/aboutsip/pkts</a> for the examples.
</p>
</div><!--/span-->
<div class="col-xs-12" id="contributing">
<h1>Contributing</h1>
<p> Contributions are more than welcome and highly encouraged. Everything in pkts.io are following the general guidelines of Maven so if you are familiar with Maven you should have no problem getting started.
</p>
</div><!--/span-->
<div class="col-xs-12" id="contributing-build-it">
<h3>Build it</h3>
<p>
<ol>
<li>Clone it</li>
<li>mvn install</li>
<li>done</li>
</ol>
</p>
</div><!--/span-->
<div class="col-xs-12" id="contributing-ide">
<h3>IDE</h3>
<p> Most Java IDE:s are capable of importing Maven based projects, allowing for a smooth integration with the IDE and Maven. Remember, Maven is the source of truth so please do not check in any IDE specific files (such as .project and .classpath for Eclipse).
</p>
</div><!--/span-->
<div class="col-xs-12" id="contributing-start-coding">
<h3>Start Coding</h3>
<p> So, you have succerssfully loaded all the code so what is the next steps. Well, check out the readme files under each sub-project to get a description of what that module is supposed to do and how to get started with the project. If you want to contribute to any project, please read the section about contribution, specifially, please checkout the section about coding principles and the style guide.
</p>
<p> If you have ideas of your own, please file a ticket so when you do submit a pull request, we know what the intent of this feature is, this also gives us a way of communicating about features.
</p>
<p> If you just want to get your hands dirty then feel free to check out the open issues. If there is anything you would like to start tackling, just assign the task to yourself and get cranking.
</p>
</div><!--/span-->
<div class="col-xs-12" id="contributing-code-principals">
<h3>Code Principals</h3>
<p> At aboutsip, we try to follow these general principles and by adhering to these simple guidelines, we feel that our code is more readable, easier to follow and is testable (even though we can always do better so please give us constructive feedback):
<ul>
<li>Write code so others can read and understand it.</li>
<li>Write testable code.</li>
<li>Unit tests everything, but no need to strive for 100%.</li>
<li>A method should not be longer than a page (if it is, you probably can split it up).</li>
<li>Javadoc everything! Please describe what each class/interface is supposed to do. If you cannot explain it, then no one else will be able to understand it either. Each method should be documented. Describe what the method is supposed to do. If you end up writing an essay about the method, perhaps it is too complicated?</li>
</ul>
</p>
</div><!--/span-->
<div class="col-xs-12" id="contributing-style-guide">
<h3>Style Guide</h3>
<p> Please follow the style already in place. If you are an Eclipse user, follow the guidelines for Eclipse below and please load the formatting template and then you won't even have to think about it, Eclipse will do it for you.
</p>
<p>In general, the aboutsip code base is following regular java style convention but here are the more important points (and some differences)
<ul>
<li>No tabs – ever</li>
<li>Indent is 4 spaces</li>
<li>The line width is 120 characters so please do not cut it off at 80 (we all have screens with high enough resolution these days).</li>
<li>Use final everywhere! (once again, you can have Eclipse fix this for you).</li>
<li>Use this everywhere! (Eclipse will fix it for you)</li>
</ul>
</p>
</div><!--/span-->
<div class="col-xs-12" id="license">
<h1>License</h1>
<p>pkts.io and all projects under aboutsip.com are released under the terms of the <a href="http://en.wikipedia.org/wiki/MIT_License">MIT license</a>
</p>
</div><!--/span-->
</div><!--/row-->
</div><!--/span-->