Add some information about how/why this dissector is (partially) machine-generated...
[obnox/wireshark/wip.git] / plugins / opcua / README
1 OpcUa Plugin:
2 =============
3
4 This plugin implements the dissection of the OpcUa Binary Protocol.
5 Author: Gerhard Gappmeier
6         ascolab GmbH
7         http://www.ascolab.com
8         
9 Overview:
10 =========
11
12 OpcUa (OPC Unified Architecture) is a vendor and platform independent
13 protocol for automation technology. It is the successor of the
14 COM/DCOM based specifications OPC DA, OPC Alarm & Events, OPC HDA, etc.
15 It unifies all this technologies into a single protocol.
16
17 The specification describes abstract services that are independent
18 of the underlying protocol. For now there exist protocol mappings
19 to a Binary TCP based protocol and a SOAP based Webservice.
20 Also a hybrid version will be available where the Binary messages are transported
21 by a single webservice command called "Invoke".
22
23 More information about the technology you can find on
24 http://www.ascolab.com/index.php?file=ua&lang=en.
25
26 Protocol Mappings:
27 ==================
28
29 Binary (TCP): The fastest and most flexible version (small footprint, no XML and SOAP necessary)
30               can easily be tunneled (SSH, IPSEC, etc.), redirected, ...
31 SOAP version: Easy to implement with verious tools like .Net, JAVA, gSOAP, etc.
32               Better to communicate through firewalls via HTTP.
33 SOAP with Binary Attchment: Combines the advantages of both.
34               The messages are encoded as Binary, and transported via SOAP as binary
35               attachment.
36
37 The OPC Foundation offers a free Opc Ua stack implementation in ANSI C
38 for all members. This stack implements the binary protocol as well
39 as the SOAP version. It's easily portable to different kinds of operating
40 systems from embedded devices to servers.
41 This makes it easy to implement Opc Ua applications based on this stack
42 and it is expected that the binary protocol will be the most used
43 protocol.
44 Nevertheless it's free to everbody to implement an own stack according
45 to the specification. An own implementation of the SOAP version 
46 should be easy with the various SOAP toolkits.
47
48 For more information see http://www.opcfoundation.org
49
50 Known limitations:
51 ==================
52
53 * Only the security policy http://opcfoundation.org/UA/SecurityPolicy#None is
54   supported, which means the encryption and signing is turned off.
55   
56 Machine-generated dissector:
57 ============================
58 Parts of the OpcUa dissector are machine generated.  Several of the files are
59 marked "DON'T MODIFY THIS FILE!" for this reason.
60
61 However, the code to create this dissector is not part of the Wireshark source
62 source code distribution.  This was discussed prior to the plugin's inclusion.
63 From http://www.wireshark.org/lists/wireshark-dev/200704/msg00025.html :
64
65 ~~~
66 > a lot of the code seems to be autogenerated (as the comments suggest)
67 > It might make sense to include the sources and the build process instead 
68 > of the intermediate files (if the amount of code/tools to build the 
69 > files seems reasonable). The reason: When people start to hack your code 
70 > (e.g. to remove warnings on a compiler you don't even think about), 
71 > you'll might get into annoying trouble with merging code the next time 
72 > you've update the upcua files.
73 >
74 >   
75 I'm sorry, but I cannot give you the sources of the code generator,
76 because they are owned by the OPC Foundation.
77 I only extended the existing code generator to produce also wireshark code.
78 It's .Net based so I guess you don't want to have it anyway ;-)
79 ~~~
80
81 So, if changes must be made to the machine-generated files, it just means the
82 upstream source will have to be modified before pushing any updates back to
83 Wireshark.
84
85 Of course it also means that care must be taken when applying patches from
86 upstream to ensure local changes aren't reversed.