From edd25e17dcc7cc0d9bcfdfa721ae18986959e316 Mon Sep 17 00:00:00 2001 From: mitshell Date: Tue, 4 Jul 2017 22:40:44 +0200 Subject: [PATCH] initial commit --- README.md | 510 ++++++++++++++++++++++++++++++++++++++++++++++++++++ license.txt | 280 +++++++++++++++++++++++++++++ 2 files changed, 790 insertions(+) create mode 100644 README.md create mode 100644 license.txt diff --git a/README.md b/README.md new file mode 100644 index 0000000..9b0b53c --- /dev/null +++ b/README.md @@ -0,0 +1,510 @@ +What is pycrate +=============== + +Pycrate is a french word for qualifying bad wine. +The present software library has nothing to do with bad wine, it is simply a +Python library for manipulating various digital formats in an easy way. +It is the glorious successor of [libmich](https://github.com/mitshell/libmich), +which was started 8 years ago and served well. + + +Installation +============ + +Operating systems and Python version +------------------------------------ + +The library is designed to work with both Python 2 (2.7) and Python 3 (3.4, 3.5 and greater), +from the official Python implementation [CPython](https://www.python.org/). +It is also supporting alternative Python engine such as [pypy](http://pypy.org/) or +[nuitka](http://nuitka.net/). +It is regularly tested both on Linux and Windows, and should actually work on any +operating system which has [r|d]ecent Python support (as in 2017). + + +Dependencies +------------ + +Currently none. Only the Python builtins and few internal modules of Python +(e.g. os, system, re) are required. + + +Automatic installation +---------------------- + +An installation script is available. +It installs the library within your Python package directory: + +``` +python setup.py install +``` + +It is also possible to test the library before installing it +(this will create two local directories *./test_asn/* and *./pycrate.egg-info/* that +you can just delete afterwards): + +``` +python setup.py test +``` + +Or to build the library without installing it in the system: + +``` +python setup.py build +``` + +It is also possible to recompile all ASN.1 modules, this will take few minutes +(but if I did not do any mistake, all ASN.1 modules provided in *./pycrate_asn1dir/* +should have been compiled with the last version nof the compiler): + +``` +python -m pycrate_asn1c.proc +``` + + +License +======= + +The whole library is licensed under GPLv2 and is compatible with more recent version +of the GPL: all licensed files have an header making it self-explanatory. + + +Contact and support +================== + +As the unique developper of the library, I am the only person to contact: +michau \[dot\] benoit \[at\] gmail \[dot\] com + + +Extending the library +===================== + +If you are willing to extend the library, do not hesitate to contact me by +email or through the github service. Any patch or submission is very welcome! +Moreover, in case you are using this library in any of your project and you +find it useful, do not hesitate to drop me an email. +It is always a pleasure to know where code provided on the Internet can end +up... + + +Components +========== + +Pycrate is actually more a software suite than a single library. It is composed +of several subdirectories, each providing specific services. + + +pycrate_core +------------ + +The core of the library. +* *utils* provides basics functions to manipulate integers, bytes and bits +* *charpy* provides the Charpy class to handle easily the consumption of a bit-stream +* *elt* and *base* are providing several classes to help when building complex + data structures +* *repr* provides simple functions to help with the representation of instances + from the *elt* and *base* modules + +Some of the most useful features are provided by the *pack_val()* functions from +the *utils* module and the *Charpy* class from the *charpy* module. +They help to deal easily with packing and unpacking bytes and integers +(signed / unsigned, little / big endian) in an aligned and unaligned way. +All lengths of fields are provided in bits, hence facilitating the handling of +unaligned structures. + + +pycrate_ether +------------- + +The modules provided here implement Ethernet and IP-oriented protocols and formats. +* *Ethernet* with structures for Ethernet and VLAN headers +* *ARP* simply providing the structure for ARP +* *IP* with structures for IPv4, IPv6, ICMP, UDP and TCP +* *PCAP* with structures for the PCAP global header and the record header + + +pycrate_media +------------- + +The modules here implement various multimedia formats. +* *JPEG* with detailed structures used in the JPEG format +* *GIF* with detailed structures used in the GIF format +* *TIFF* with detailed structures used in the TIFF format +* *BMP* with structures used in the BMP format +* *PNG* with the basic structure used in the PNG format +* *MPEG4* with the basic structure used in the MPEG4 file format +* *MP3* with detailed structures used in the MP3 format, including ID3v1 and ID3v2 tags + +Most of the classes here implement complete recipe to parse all of those format in a +single shot, by using their *from_char()* method. + + +pycrate_asn1c +------------- + +All the modules here serve the sole purpose of compiling ASN.1 specifications. +The most important ones are: +* *asnobj* which is the almighty class when parsing any ASN.1 definition +* *generator* which provides two distinct generators to produce source files from + the ASN.1 objects processed in Python: *PycrateGenerator* which produces source + file to be used with the pycrate ASN.1 runtime (in *pycrate_asn1rt*), + and *JSONDepGraphGenerator* which produces json file listing object dependencies + (which then can be browsed dynamically thanks to D3). +* *proc* which is the top-level module for the compiler, it contains for example + the *compile_text()* function which compiles a serie of ASN.1 modules into + Python objects + +This compiler support most of the ASN.1 language features, including parameterization and +class objects and sets (especially useful when working with table constraints). +It has however few restrictions, the biggest being the need for the left part of the ASN.1 +assignment *::=* being on a single line. Also, old-school ASN.1 macros are not supported ; +hence, the compiler cannot parse SNMP MIBs. + + +pycrate_asn1dir +--------------- + +This subdirectory contains several ASN.1 specifications that are supported and +precompiled for pycrate. Very few specifications have been changed in order to +work with pycrate : +* Q.775, in which the terrible *AllPackagesAS* is commented out +* Q.773 and Q.775, in which the *TCInvokeIdSet* constraint is modified to be easier + used as a set of values +That's all ! + + +pycrate_asn1rt +-------------- + +This subdirectory contains the ASN.1 runtime, that is loaded and used by the ASN.1 +specifications that are compiler with the compiler in *pycrate_asn1c*. It supports +the PER encoding rules (aligned and not, canonical also), and the BER, CER and +DER encoding rules. + + +Usage +===== + +Most of the modules have doc strings. I try also to write readable sources and to +comment them as much as possible for understanding them easily (and to allow also +myself to understand my own code years after...). +In a near future, a wiki may be provided to bring examples and methods on how to +use the different modules (any contribution is welcome on this, too). +Finally, the code provided in the test/ subdirectory is also representative on +how to use the different modules. + + +ASN.1 usage +=========== + + +Tools +===== + +Two different tools are provided (yet): +* *pycrate_showmedia.py* parses some media files (jpg, bmp, gif, mp3, png, + tiff, mpeg4) and pretty print the file structure on the standard output. +* *pycrate_asn1compile.py* compiles ASN.1 source file(s) and produce a Python + source file that makes use of the ASN.1 runtime. This source file is then + usable to encode / decode any ASN.1 object from the compiled ASN.1 + specification. + +Examples +======== + +It is possible to test the *pycrate_showmedia.py* tool with media test files +provided in *./test/res/*, or any other supported media file. + +```console +$ ./tools/pycrate_showmedia.py --help +usage: pycrate_showmedia.py [-h] [-bl BL] [-wt] input + +print the internal structure of the input media file,supported formats are: +BMP, GIF, JPEG, MP3, MPEG4, PNG, TIFF + +positional arguments: + input input media file + +optional arguments: + -h, --help show this help message and exit + -bl BL maximum length for buffer representation + -wt show also absent / transparent fields + +$ ./tools/pycrate_showmedia.py ./test/res/xkcd_wireless_signal.png +### PNG ### + + ### PNGBody ### + ### PNGChunk ### + + + ### IHDR ### + + + + + + + + + ### PNGChunk ### + + + + + ### PNGChunk ### + + + \x081\x04H.-*\x83\x07%\x03\x83' + 00 83 02 83 01 83 03 43 00 43 22 43 3d c3 02 86 | '\x00\x83\x02\x83\x01\x83\x03C\x00C"C=\xc3\x02\x86' + a3 0c 6f 18 c5 19 5d 18 4b 19 57 30 de 63 12 63 | '\xa3\x0co\x18\xc5\x19]\x18K\x19W0\xdec\x12c' + 0a 62 9a c0 74 81 59 98 39 92 79 21 f3 1b 16 4b | '\nb\x9a\xc0t\x81Y\x989\x92y!\xf3\x1b\x16K' + 96 0e 96 5b ac 7a ac ad ac f7 d8 2c d9 a6 b1 7d | '\x96\x0e\x96[\xacz\xac\xad\xac\xf7\xd8,\xd9\xa6\xb1}' + 63 0f 67 df cd a1 c4 d1 c5 f1 85 33 91 f3 02 97 | 'c\x0fg\xdf\xcd\xa1\xc4\xd1\xc5\xf1\x853\x91\xf3\x02\x97' + 23 d7 16 6e 4d ee 05 3c 52 3c 53 79 85 78 27 f1 | "#\xd7\x16nM\xee\x054}' + 32 fd fc ea eb 82 ef e1 3f 05 7e 9d fa d3 fa cf | '2\xfd\xfc\xea\xeb\x82\xef\xe1?\x05~\x9d\xfa\xd3\xfa\xcf' + f1 ff 7f 00 0d 00 0f 34 | '\xf1\xff\x7f\x00\r\x00\x0f4'> + + ### PNGChunk ### + + + + + ### PNGChunk ### + + + g\xcc^Z\xd4\x18\\ws]' + 81 f8 a9 e4 40 ae f8 e1 8b b5 7d 25 49 26 38 f8 | '\x81\xf8\xa9\xe4@\xae\xf8\xe1\x8b\xb5}%I&8\xf8' + a6 90 e4 05 7b 98 f9 06 39 a1 7b e2 c6 b9 a3 7b | '\xa6\x90\xe4\x05{\x98\xf9\x069\xa1{\xe2\xc6\xb9\xa3{' + 74 71 73 0c ac ac 7e 85 85 f2 37 f5 d0 3c ed 21 | 'tqs\x0c\xac\xac~\x85\x85\xf27\xf5\xd0<\xed!' + 00 d6 53 8b 2a 4a d3 9e 9c db b9 68 e2 83 ea 07 | '\x00\xd6S\x8b*J\xd3\x9e\x9c\xdb\xb9h\xe2\x83\xea\x07' + af 0d 2e de 61 04 c0 29 56 47 92 7c 7d 54 47 f2 | '\xaf\r.\xdea\x04\xc0)VG\x92|}TG\xf2' + 1c 0e 90 19 11 4a a0 4f f6 f7 eb 00 63 4b 48 6e | '\x1c\x0e\x90\x19\x11J\xa0O\xf6\xf7\xeb\x00cKHn' + b2 7f 4f 92 fb 71 49 7f 24 b3 2d 30 b5 61 5c 9f | '\xb2\x7fO\x92\xfbqI\x7f$\xb3-0\xb5a\\\x9f' + 39 fa 4f f6 ed f6 20 93 24 57 7a 62 26 49 b2 c2 | '9\xfaO\xf6\xed\xf6 \x93$Wzb&I\xb2\xc2' + 1f 27 49 32 cf d2 18 3d 75 64 92 bc eb 0d 35 a9 | "\x1f'I2\xcf\xd2\x18=ud\x92\xbc\xeb\r5\xa9" + 0d 81 00 58 74 ec e2 21 1f 52 fd 52 09 f2 ee 9a | '\r\x81\x00Xt\xec\xe2!\x1fR\xfdR\t\xf2\xee\x9a' + d2 62 92 e4 7e cf 7c 52 d7 7b b5 74 e4 b1 a9 e9 | '\xd2b\x92\xe4~\xcf|R\xd7{\xb5t\xe4\xb1\xa9\xe9' + f4 5d cb 83 6d 57 98 88 6a 99 ca ca ba ff cd aa | '\xf4]\xcb\x83mW\x98\x88j\x99\xca\xca\xba\xff\xcd\xaa' + bf 9b 82 38 93 5e f7 92 0e 79 60 5c c5 e1 10 5d | '\xbf\x9b\x828\x93^\xf7\x92\x0ey`\\\xc5\xe1\x10]' + 91 2d d6 92 0c 43 3a 1f da 08 43 76 4e c0 a0 2a | '\x91-\xd6\x92\x0cC:\x1f\xda\x08CvN\xc0\xa0*' + 26 2f 00 fd 4b c9 de 88 24 c9 65 b8 af 3f 34 04 | '&/\x00\xfdK\xc9\xde\x88$\xc9e\xb8\xaf?4\x04' + ab bd 15 99 0d e2 76 74 d4 7f 32 ee 7a 08 7f 92 | '\xab\xbd\x15\x99\r\xe2vt\xd4\x7f2\xeez\x08\x7f\x92' + 64 90 51 77 ac 21 c9 09 88 22 49 ae c0 91 d9 b8 | 'd\x90Qw\xac!\xc9\t\x88"I\xae\xc0\x91\xd9\xb8' + 40 ae c1 61 92 d4 f9 2a 4d c7 56 90 a4 d8 3f b3 | '@\xae\xc1a\x92\xd4\xf9*M\xc7V\x90\xa4\xd8?\xb3' + c2 1e 93 64 7e 3b c5 bd f1 4a 58 44 15 52 6d af | '\xc2\x1e\x93d~;\xc5\xbd\xf1JXD\x15Rm\xaf' + fa 4c aa db 59 a9 49 92 5a 4f e5 13 92 e4 84 9e | '\xfaL\xaa\xdbY\xa9I\x92ZO\xe5\x13\x92\xe4\x84\x9e' + 53 30 ea d2 8b fc ee 42 5f 15 76 50 e3 b3 9b 24 | 'S0\xea\xd2\x8b\xfc\xeeB_\x15vP\xe3\xb3\x9b$' + fd 6d a6 0a 2f 48 96 8f c7 a6 70 05 af 00 e6 c5 | '\xfdm\xa6\n/H\x96\x8f\xc7\xa6p\x05\xaf\x00\xe6\xc5' + a4 87 3d 13 4d 4c 2f 93 5c 85 f7 e2 1d 6a 7b 63 | '\xa4\x87=\x13ML/\x93\\\x85\xf7\xe2\x1dj{c' + e3 3d 17 84 91 6e 50 66 93 0c c3 17 e9 e6 2f 63 | '\xe3=\x17\x84\x91nPf\x93\x0c\xc3\x17\xe9\xe6/c' + 84 ee 20 76 34 88 1b 8d 97 e2 87 62 04 5d c5 31 | '\x84\xee v4\x88\x1b\x8d\x97\xe2\x87b\x04]\xc51' + 92 8c 44 4a 7b 4c d1 70 17 fa 57 92 64 a5 95 ab | '\x92\x8cDJ{L\xd1p\x17\xfaW\x92d\xa5\x95\xab' + 36 cb bc ab 8e c9 d8 48 92 eb 10 81 b9 d5 2e f1 | '6\xcb\xbc\xab\x8e\xc9\xd8H\x92\xeb\x10\x81\xb9\xd5.\xf1' + cc d4 e4 15 c9 49 58 ef 0f a7 80 1e f0 2d 4f c5 | '\xcc\xd4\xe4\x15\xc9IX\xef\x0f\xa7\x80\x1e\xf0-O\xc5' + 78 92 1c 2f 5d fb 1a 96 49 63 8d 89 d8 45 de c7 | 'x\x92\x1c/]\xfb\x1a\x96Ic\x8d\x89\xd8E\xde\xc7' + 0c be 75 56 a5 e5 41 95 4a d2 aa cf 72 64 91 a4 | '\x0c\xbeuV\xa5\xe5A\x95J\xd2\xaa\xcfrd\x91\xa4' + d6 a5 fd 78 68 f6 23 0c fb 49 74 2b 70 36 be 4f | '\xd6\xa5\xfdxh\xf6#\x0c\xfbIt+p6\xbeO' + 92 da 27 d2 0f 5d c2 44 b2 a2 07 4e b1 ad 80 18 | "\x92\xda'\xd2\x0f]\xc2D\xb2\xa2\x07N\xb1\xad\x80\x18" + 92 5e 32 fd 78 ef 23 4f 65 a1 79 97 06 71 6f 60 | '\x92^2\xfdx\xef#Oe\xa1y\x97\x06qo`' + 8f f8 a1 08 41 4f b0 9d 24 17 21 35 cd 1b 63 1f | '\x8f\xf8\xa1\x08AO\xb0\x9d$\x17!5\xcd\x1bc\x1f' + c9 dd c4 b1 7c 1b ab c9 45 b8 c1 74 2c ce ca 7c | '\xc9\xdd\xc4\xb1|\x1b\xab\xc9E\xb8\xc1t,\xce\xca|' + 30 01 1d 92 b0 aa fa 35 ee c8 ba ea 78 11 fd 0e | '0\x01\x1d\x92\xb0\xaa\xfa5\xee\xc8\xba\xeax\x11\xfd\x0e' + 62 b9 86 9c 8e f5 27 70 8e 24 63 c4 7f b8 0b d7 | "b\xb9\x86\x9c\x8e\xf5'p\x8e$c\xc4\x7f\xb8\x0b\xd7" + c8 37 09 ef 49 26 62 1b b9 08 2f c8 eb 58 92 09 | '\xc87\t\xefI&b\x1b\xb9\x08/\xc8\xebX\x92\t' + 4c 23 35 18 b3 1d e2 24 17 89 49 c8 da 85 7b 16 | 'L#5\x18\xb3\x1d\xe2$\x17\x89I\xc8\xda\x85{\x16' + 7e a4 cc 37 0a 27 6a de 7c 98 2c 8b 64 aa 85 53 | "~\xa4\xcc7\n'j\xde|\x98,\x8bd\xaa\x85S" + 99 9d 97 6d 47 92 ae d6 fa 79 4a 18 4c 72 38 52 | '\x99\x9d\x97mG\x92\xae\xd6\xfayJ\x18Lr8R' + 1a c2 cd c2 24 e9 c9 c3 27 11 9b 49 72 0d 12 59 | "\x1a\xc2\xcd\xc2$\xe9\xc9\xc3'\x11\x9bIr\r\x12Y" + d2 07 2a e3 57 e2 91 55 78 40 be 17 86 32 1f 32 | '\xd2\x07*\xe3W\xe2\x91Ux@\xbe\x17\x862\x1f2' + 00 e8 9d 96 04 6b 57 e7 80 8f 55 17 99 8d 83 a9 | '\x00\xe8\x9d\x96\x04kW\xe7\x80\x8fU\x17\x99\x8d\x83\xa9' + 76 36 e9 43 8c cb 49 56 d8 76 5c 85 4f 24 79 56 | 'v6\xe9C\x8c\xcbIV\xd8v\\\x85O$yV' + ec 0d 4c 44 f7 ad 5d 00 0c cc e7 43 ec 22 bb 38 | '\xec\rLD\xf7\xad]\x00\x0c\xcc\xe7C\xec"\xbb8' + 68 5e fc b1 d9 d8 3d 05 96 b2 97 ac 44 d4 51 5c | 'h^\xfc\xb1\xd9\xd8=\x05\x96\xb2\x97\xacD\xd4Q\\' + 23 49 46 21 0c 1f 62 91 38 19 89 b4 73 56 05 d5 | '#IF!\x0c\x1fb\x918\x19\x89\xb4sV\x05\xd5' + ba 79 3b 5f 8a f7 77 d4 ca 67 1e fe 22 15 ee d2 | '\xbay;_\x8a\xf7w\xd4\xcag\x1e\xfe"\x15\xee\xd2' + 91 a3 d8 5b fc e1 cb 51 fd ab fb c9 cc ec ee 21 | '\x91\xa3\xd8[\xfc\xe1\xcbQ\xfd\xab\xfb\xc9\xcc\xec\xee!' + 7d 70 6e f3 18 ce c1 c1 6d 8c 81 44 32 cf 51 ba | '}pn\xf3\x18\xce\xc1\xc1m\x8c\x81D2\xcfQ\xba' + ...> + + ### PNGChunk ### + + + + +``` + +It is possible to test the *pycrate_asn1compile.py* tool with some test ASN.1 +specification from *./test/res/*, or any other valid ASN.1 specification of your +choice. + +```console +$ ./tools/pycrate_asn1compile.py --help +usage: pycrate_asn1compile.py [-h] [-i INPUT [INPUT ...]] [-o OUTPUT] + [-fautotags] [-fextimpl] [-fverifwarn] + +compile ASN.1 input file(s) for the pycrate ASN.1 runtime + +optional arguments: + -h, --help show this help message and exit + -i INPUT [INPUT ...] ASN.1 input file(s) or directory + -o OUTPUT compiled output Python source file + -fautotags force AUTOMATIC TAGS for all ASN.1 modules + -fextimpl force EXTENSIBILITY IMPLIED for all ASN.1 modules + -fverifwarn force warning instead of raising during the + verification stage +``` + +After compiling a module, it is possible to load it in Python and use it for +encoding / decoding any objects defined in it. + +```python +Python 3.4.3 (default, Nov 17 2016, 01:08:31) +[GCC 4.8.4] on linux +Type "help", "copyright", "credits" or "license" for more information. +>>> HardcoreSyntax # this is the only ASN.1 module provided in Hardcore.asn + +>>> Final = HardcoreSyntax.Final # this is the Final object defined at line 115 +>>> Final + +>>> Final.get_proto() # warning: this does not show optional or extended component +{ +w1: { + r10: { + low: 'INTEGER', + high: 'INTEGER', + bool: 'BOOLEAN', + null: 'NULL' + }, + r90: { + low: 'INTEGER', + high: 'INTEGER', + bool: 'BOOLEAN', + null: 'NULL' + } + }, +w2: { + r10: { + low: 'INTEGER', + high: 'INTEGER', + bool: 'BOOLEAN', + null: 'NULL' + }, + r90: { + low: 'INTEGER', + high: 'INTEGER', + bool: 'BOOLEAN', + null: 'NULL' + } + }, +bool: 'BOOLEAN' +} +>>> V = { \ +... 'w1':{'r10':{'low':5, 'high':50, 'bool':False}, 'r90':{'low':50, 'high':95, 'bool':False, 'null':0}}, \ +... 'w2':{'r10':{'low':1, 'high':10, 'bool':False}, 'r90':{'low':90, 'high':100, 'bool':True}}, \ +... 'bool': True}) +>>> Final.set_val(V) +>>> print(Final.to_asn1()) # .to_asn1() returns a printable ASN.1 representation of the value +{ + w1 { + r10 { + low 5, + high 50, + bool FALSE + }, + r90 { + low 50, + high 95, + bool FALSE, + null NULL + } + }, + w2 { + r10 { + low 1, + high 10, + bool FALSE + }, + r90 { + low 90, + high 100, + bool TRUE + } + }, + bool TRUE +} +>>> Final.to_aper() # aligned PER +b'*\x85\x92\x80@\x01\x00\x08\x02\xd5`' +>>> Final.to_uper() # unaligned PER +b'*\x85\x92\x80@@\x02\x00\xb5X' +>>> Final.to_ber() +b'05\xa0\x18\xa0\t\x80\x01\x05\x81\x012\x82\x01\x00\xa1\x0b\x80\x012\x81\x01_\x82\x01\x00\x83\x00\xa1\x16\xa0\t\x80\x01\x01\x81\x01\n\x82\x01\x00\xa1\t\x80\x01Z\x81\x01d\x82\x01\xff\x82\x01\xff' +>>> Final.to_cer() +b'0\x80\xa0\x80\xa0\x80\x80\x01\x05\x81\x012\x82\x01\x00\x00\x00\xa1\x80\x80\x012\x81\x01_\x82\x01\x00\x83\x00\x00\x00\x00\x00\xa1\x80\xa0\x80\x80\x01\x01\x81\x01\n\x82\x01\x00\x00\x00\xa1\x80\x80\x01Z\x81\x01d\x82\x01\xff\x00\x00\x00\x00\x82\x01\xff\x00\x00' +>>> Final.to_der() +b'05\xa0\x18\xa0\t\x80\x01\x05\x81\x012\x82\x01\x00\xa1\x0b\x80\x012\x81\x01_\x82\x01\x00\x83\x00\xa1\x16\xa0\t\x80\x01\x01\x81\x01\n\x82\x01\x00\xa1\t\x80\x01Z\x81\x01d\x82\x01\xff\x82\x01\xff' +>>> Final.from_ber( Final.to_ber() ) +>>> Final() == V # or Final._val == V +True +``` + +For more information about the API exposed for each ASN.1 object, you can check +the docstrings of all ASN.1 objects, and also read the source file *./pycrate_asn1rt/asnobj.py*. + diff --git a/license.txt b/license.txt new file mode 100644 index 0000000..d8cf7d4 --- /dev/null +++ b/license.txt @@ -0,0 +1,280 @@ + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Lesser General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS