What is pycrate
===============
While this is a french joke about bad wine (you say "picrate" when it's close to vinegar !).
The present software library has nothing to do with wine (except it is developed in France),
it is simply a Python library for manipulating various digital formats in an easy way,
with a funny name. Most of the format supported are related in one way or another
to cellular network's signalling.
It is the glorious successor of [libmich](https://github.com/mitshell/libmich),
which was started back in 2009, served well and retired in 2017.
It provides basically a runtime for encoding and decoding data structures, including
CSN.1 and ASN.1. Additionally, it features a 3G and LTE mobile core network.
This updated repository inside the collaborative organization [pycrate-org](https://github.com/pycrate-org/),
is the new home to keep maintaining and updating the project, starting February 2024.
Any and all collaborative efforts will be much appreciated: from uncovering bugs and discussing issues,
to integrate fixes and extensions through PR...
License
=======
The whole library is licensed under LGPL v2.1 and is compatible with more recent
version of the LGPL: all licensed files have an header making it self-explanatory.
For more details, please report to the
[license.txt](https://github.com/pycrate-org/pycrate/blob/master/license.txt) file.
Wiki
====
Pycrate has a growing [wiki](https://github.com/pycrate-org/pycrate/wiki/).
Use it as much as possible before opening an issue.
Feel free also to propose some additional content.
Installation
============
Operating systems and Python version
------------------------------------
The library is designed to work with Python 3 (3.5 and greater), from the official Python
implementation [CPython](https://www.python.org/), and is systematically tested both on
Linux, MacOS and Windows. It should also support alternative Python engines such as
[pypy](http://pypy.org/), [nuitka](http://nuitka.net/) or [Cython](https://cython.org/) ;
this is however not regularly tested. It should also support any other operating systems which
has a decent Python 3 support.
Python2 support is entirely abandonned end of 2022, and hence release 0.5.5 is the last one with
full support of Python 2.7.
Dependencies
------------
Currently none. Only the Python builtins and few internal modules of Python
(e.g. os, system, re, struct, datetime) are required for most of the features.
The json internal module is required for supporting the JSON API.
If you want to run pycrate in Python2 (which is bad !), you will however need to
install the [enum34](https://pypi.org/project/enum34/) package.
The _pycrate\_ether/SCTP_ module can optionally use the external
[crc32c](https://pypi.org/project/crc32c/) module from ICRAR.
The _pycrate\_mobile/TS24301\_EMM_ and _pycrate\_mobile/TS24501\_FGMM_ modules use
[CryptoMobile](https://github.com/mitshell/CryptoMobile) as optional dependency to
encrypt and decrypt LTE and 5G NAS messages.
The _pycrate\_corenet_ part requires also [pysctp](https://pypi.org/project/pysctp/)
and [CryptoMobile](https://github.com/pycrate-org/CryptoMobile) to run.
The _pycrate\_diameter/parse\_iana\_diameter\_xml.py_ file uses
[lxml](https://pypi.org/project/lxml/) to translate xml files from IANA to Python
dictionnaries ; this is however not required for standard runtime.
The _pycrate\_osmo/SEDebugMux.py_ module relies on the [crcmod](https://pypi.org/project/crcmod/)
to compute custom CRC in the frame format.
Automatic installation
----------------------
An installation script is available.
As soon as you have cloned or downloaded the repository, you can use it to install
the library within your Python package directory:
```
python setup.py install
```
Run it as superuser for a system-wide install, or as-is for a user home-directory
level install. You can also run _develop_ instead of _install_ if you want a
developer-friendly installation.
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 -m unittest test.test_pycrate
```
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 latest version of the compiler):
```
python -m pycrate_asn1c.asnproc
```
More generally, installation is not required, and simply having all _pycrate\_*_
subdirectories into the PYTHONPATH enables to use the entire library.
Installation with pip
---------------------
Alternatively, you can install the library with the `pip` command:
```
pip install pycrate
```
The install package is available on [pypi](https://pypi.org/project/pycrate/).
It contains the library from the last tagged release on github (which may be months old).
Contributing
============
Contact and support
-------------------
This library is free software, and you are free to use it (or not to use it).
In case you encounter a problem with it, first read this README completely and then
check the [Wiki](https://github.com/pycrate-org/pycrate/wiki/) ; moreover many classes,
methods and functions are documented with docstrings, and finally you can have a look
at the source code (it won't bite you).
If after all those steps, you still have a question or you think you found a bug,
please open an issue (see below). Specific support requires time and may not be always
possible. In case you require such support, please consider also contributing in one
way or another (see below, too).
In case you are using this library in any of your project and you find it useful,
do not hesitate to send me an email. It is always a pleasure to know where code provided
on the Internet can end up... (I am personally aware of some dark places where a pycrate's
fork lies).
Filling an issue
---------------
When filling an issue, please provide precise and contextual information about
your case and the error you potentially encounter:
- indicate the version (or commit-level) of pycrate you are using, together with the version of Python.
- provide a code snippet that leads to the error you are facing, so that it can be reproduced.
- provide the eventual stacktrace you are getting from Python
- provide additional and contextual information as needed (e.g. a specific ASN.1 specification being used...)
This is the bare minimum if you want to get help.
And when you consider your issue has been addressed, please close it: "A good issue is a closed one !"
as would have said my great grandmother.
Extending the library
---------------------
If you are willing to extend the library, do not hesitate to contact me by
email or preferably through the github service (ideally, open a pull request).
For important changes, please elaborate about your need and provide some justification.
Any patch or submission is always very welcome!
Other contributions
-------------------
In case you do not want to deep dive in the code, you can still contribute in many ways:
* highlighting specific issues in the inner-working of the library,
and opening an issue with concrete debugging information
* writing new test cases for more coverage (have a look at the *test/* directory)
* sending captures / real-world data that can be used for writing new test cases
* writing new parts of the wiki (have a look at the
[pycrate wiki](https://github.com/pycrate-org/pycrate/wiki/))
Getting contributions is extremely important to encourage the continuous development
of the library, and to confirm the choice made to open-source it.
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.
* *MPLS* with structures for MPLS label and header
* *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
* *SCTP* with structures for SCTP headers and various chunks
* *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 a 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).
* *asnproc* 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
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 compiled with the compiler in *pycrate_asn1c*. It supports
the PER encoding rules (aligned and not, canonical also), and the BER, CER, DER
and JER encoding rules.
pycrate_csn1
------------
This subdirectory contains a CSN.1 to Python translater in the file *trans.py*,
and a CSN.1 runtime in the file *csnobj.py*, in order to encode and decode CSN.1
structures translated to Python objects.
pycrate_csn1dir
---------------
This subdirectory contains CSN.1 structures extracted from 3GPP specifications
(in the .csn files), and translated into Python objects. The following specifications
have been used: TS 44.018, TS 44.060 and TS 24.008.
pycrate_mobile
--------------
This subdirectory implements most of the 3GPP NAS protocol formats:
* *GSMTAP*: gsmtap header format
* *MCC_MNC*: dictionnaries for MCC and MNC look-up
* *NAS*: provides two functions to parse any uplink and downlink mobile NAS messages
* *NASLTE*: provides two functions to parse LTE uplink and downlink NAS messages
* *NAS5G*: provides one function to parse 5G uplink and downlink mobile NAS messages
* *PPP*: structures for NCP and LCP protocols used for PPP connection estabishment,
as defined in RFC 1661, 1332 and 1334
* *SCCP*: structures for SCCP user-data and management messages as defined in ITU-T Q.713
* *ISUP*: structures for ISUP messages as defined in ITU-T Q.763
* *SIGTRAN*: generic structures for SIGTRAN (i.e. M2UA, M2PA, MTP3 and M3UA) messages
* *M3UA*: structures dedicated to the M3UA format from RFC 4666
* *TS102225*: structures for SIM card's Secured Packets from ETSI TS 102.225
* *TS23038*: structures and routines for SMS encoding from TS 23.038
* *TS23040_SMS*: structures for the SMS transport protocol from TS 23.040
* *TS23041_CBS*: structures for the Cell Broadcast Service protocol from TS 23.041
* *TS24007*: basic structures from the TS 24.007 specification, reused in most of the NAS protocols
* *TS24008_CC* : structures for call control messages from TS 24.008
* *TS24008_GMM*: structures for GPRS mobility management messages from TS 24.008
* *TS24008_IE*: structures for many information elements from TS 24.008
* *TS24008_MM*: structures for mobility management messages from TS 24.008
* *TS24008_SM*: structures for GPRS session management messages from TS 24.008
* *TS24011_PPSMS*: structures for the SMS point-to-point protocol from TS 24.011
* *TS24080_SS*: structures for the Supplementary Services protocol from TS 24.080,
wrapping some MAP ASN.1 objects
* *TS24301_EMM*: structures for the EPS mobility management messages from TS 24.301
* *TS24301_ESM*: structures for the EPS session management messages from TS 24.301
* *TS24301_IE*: structures for many information elements from TS 24.301
* *TS24501_FGMM*: structures for the 5G mobility management messages from TS 24.501
* *TS24501_FGSM*: structures for the 5G session management messages from TS 24.501
* *TS24501_IE*: structures for many information elements from TS 24.501
* *TS24501_UEPOL*, *TS24526_UEPOL* and *TS24588_UEPOL*: structures for the 5G UE policy protocol
from TS 24.501, 526 and 588
* *TS29002_MAPAppCtx*: functions that relies on the Pycrate_TCAP_MAPv2v3 ASN.1 module,
dealing mostly with MAP application-contexts
* *TS29002_MAPIE*: structure for the MAP AddressString object from TS 29.002
* *TS29244_PFCP*: structure for PFCP messages from TS 29.244
* *TS0960_GTPv0*: structures for 2G GTP version 0 from TS 09.60
* *TS29060_GTP*: structures for 2G/3G GTP-C version 1 from TS 29.060
* *TS29274_GTPC*: structures for 4G GTP-C version 2 from TS 29.274
* *TS29281_GTPU*: structures for 2G/3G/4G/5G GTP-U from TS 29.281
* *TS31111_SAT*: basic structures and dict for the SIM application toolkit from TS 31.111
* *TS31115*: structures for SIM card's Secured Packets over SMS from TS 31.115
* *TS38415_PDUSess*: structure used in 5G user-place traffic (i.e. GTP-U) from TS 38.415
* *TS44018_GTTP*: structure for the single GSM GTTP message from TS 44.018
* *TS44018_IE*: structures for many information elements from TS 44.018
* *TS44018_RR*: structures for the GSM and GPRS radio ressources messages from TS 44.018
* *TS48058_Abis*: few IE structures for the GSM Abis protocol from TS 48.058
pycrate_diameter
----------------
This subdirectory contains the following modules:
* *parse_iana_diameter_xml*: to translate XML Diameter structures from IANA to Python
* *iana_diameter_dicts.py*: that is automatically created by the former, containing Diameter Python dicts
* *Diameter*: a generic Diameter module which implements DiameterGeneric and AVPGeneric structures
* *DiameterIETF*: a Diameter module which relies on AVP types provided in all IETF RFC
* *Diameter3GPP*: a Diameter module which relies on AVP types provided in all 3GPP TS
pycrate_osmo
------------
This subdirectory contains the following modules:
* *L1CTL*: structures to control the osmocom-bb GSM embedded stack from the host
* *SEDebugMux*: structure used by Sony-Ericsson SoC and basebands to wrap logs
* *RRCTL*: structures to interact with the RRC layer of the UE emulator from this
[fork](https://gitea.osmocom.org/vyanitskiy/srsRAN/src/branch/extnas/release_20_10) of srs-lte
pycrate_corenet
---------------
This subdirectory implements a signaling server that supports IuCS and IuPS over Iuh interfaces
(including HNBAP and RUA/RANAP) for interfacing with 3G femtocells, and S1 interfaces
(including S1AP) for interfacing with LTE eNodeBs.
It handles many procedures to drive femtocells, eNodeBs and mobile terminals connecting
through them. In terms of services, it mostly support short messages and data connectivity.
It does not handle call services, neither active mobility procedures (handovers).
It can be easily (common, running a mobile core network is not *that* easy)
configured and used thanks to the [corenet](https://github.com/mitshell/corenet/) project,
also open-source.
pycrate_gmr1
------------
This subdirectory contains the main module for the GMR-1 Radio Resources protocol: *TS101376_04_08*,
and the submodule for specific Information Elements: *TS101376_04_08_IE*.
This is a partial implementation of the ETSI specification TS 101 376-04-08 for the
GEO-Mobile Radio Interface Specifications (Release 3).
pycrate_gmr1_csn1
-----------------
This subdirectory contains all the CSN.1 definitions for the GMR-1 Radio Resources protocol,
extracted from the 3 ETSI specifications for GEO-Mobile Radio release 3:
TS 101 376-04-08, TS 101 376-04-12 and 101 376-04-13.
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...).
A [wiki](https://github.com/pycrate-org/pycrate/wiki/) is provided
and extended from time to time, to bring examples and methods on how to use the
different modules (any contribution on this would be very welcome, too).
Finally, the code provided in the *test/* subdirectory is also representative on
how to use the different modules.
Basically, a pycrate's object exposes the following methods:
* `set_val()` / `get_val()` / `get_val_d()`, which sets value into and gets value from the object
* `from_bytes()` / `to_bytes()`, which converts a buffer into values according to the internal structure of the object, and back
* `from_json()` / `to_json()`, for working with JSON-encoded values
* `hex()` / `bin()`, for getting hexadecimal and binary representation of the serialized obect's value
* `repr()` / `show()`, for providing nice python's internal representation, and printable representation of the object's value
ASN.1 usage
===========
When a Python module from *pycrate_asn1dir/* is loaded, it creates Python classes
corresponding to ASN.1 modules (all dash characters are converted to underscore).
Each ASN.1 object has a corresponding Python instance, exposing the following methods:
* `from_asn1()` / `to_asn1()`, which converts ASN.1 textual value to Python value and back
* `from_aper()` / `to_aper()`, which converts aligned PER encoded value to Python value and back
* `from_uper()` / `to_uper()`, which converts unaligned PER
* `from_ber()` / `to_ber()`, which converts BER
* `from_cer()` / `to_cer()`, which converts CER
* `from_der()` / `to_der()`, which converts DER
* `from_jer()` / `to_jer()`, which converts JER
* `from_oer()` / `to_oer()`, which converts OER
* `from_coer()` / `to_coer()`, which converts canonical OER
* `set_val()` / `get_val()` to set and get Python's values into the ASN.1 object
* `get_proto()` to return to internal structure of the ASN.1 object
All the methods useful for working with ASN.1 objects at runtime can be found in
the file *pycrate_asn1rt/asnobj.py*.
Tools
=====
Four 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.
* *pycrate_berdecode.py* parses any BER/CER/DER encoded binary value of ASN.1
objects and prints the corresponding structure.
* *pycrate_map_op_info.py* prints prototypes and various information related to
TCAP-MAP (Mobile Application Part) and CAMEL operations and application-contexts.
* *pycrate_gtp_type_info.py* prints prototypes and various information related to
GTP messages and transactions as in version 0, 1 or 2
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 ###
<sig [PNG signature] : '\x89PNG\r\n\x1a\n'>
### PNGBody ###
### PNGChunk ###
<len : 13>
<type : 'IHDR'>
### IHDR ###
<width : 238>
<height : 415>
<depth [bit depth] : 8>
<color [color type] : 0 (Greyscale)>
<comp [compression method] : 0 (inflate/deflate with sliding window)>
<filter [filter method] : 0 (no interlace)>
<interlace [interlace method] : 0 (no interlace)>
<crc : 0x7d8cb12e>
### PNGChunk ###
<len : 9>
<type : 'pHYs'>
<data :
00 00 0c 4e 00 00 0c 4e 01 | '\x00\x00\x0cN\x00\x00\x0cN\x01'>
<crc : 0x7f778c23>
### PNGChunk ###
<len : 792>
<type : 'iCCP'>
<data :
50 68 6f 74 6f 73 68 6f 70 20 49 43 43 20 70 72 | 'Photoshop ICC pr'
6f 66 69 6c 65 00 00 78 da 63 60 60 9e e0 e8 e2 | 'ofile\x00\x00x\xdac``\x9e\xe0\xe8\xe2'
[...]
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'>
<crc : 0xfa96f15d>
### PNGChunk ###
<len : 32>
<type : 'cHRM'>
<data :
00 00 6e 27 00 00 73 af 00 00 df f2 00 00 83 30 | "\x00\x00n'\x00\x00s\xaf\x00\x00\xdf\xf2\x00\x00\x830"
00 00 77 43 00 00 c8 0a 00 00 34 95 00 00 2e dc | '\x00\x00wC\x00\x00\xc8\n\x00\x004\x95\x00\x00.\xdc'>
<crc : 0x20bf171a>
### PNGChunk ###
<len : 21130>
<type : 'IDAT'>
<data :
78 da ed bd 79 50 8d fd 1f ff ff bc ce 39 73 4e | 'x\xda\xed\xbdyP\x8d\xfd\x1f\xff\xff\xbc\xce9sN'
db b4 37 95 32 b4 19 94 06 2d 7e 11 26 b2 fc 10 | '\xdb\xb47\x952\xb4\x19\x94\x06-~\x11&\xb2\xfc\x10'
[...]
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'
...>
<crc : 0xa9fbdd38>
### PNGChunk ###
<len : 0>
<type : 'IEND'>
<data : >
<crc : 0xae426082>
```
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] [-s SPEC] [-i INPUT [INPUT ...]] [-o OUTPUT] [-g GENERATOR_PATH] [-j] [-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
-s SPEC provide a specification shortname, instead of ASN.1 input file(s)
-i INPUT [INPUT ...] ASN.1 input file(s) or directory
-o OUTPUT compiled output Python (and json) source file(s)
-g GENERATOR_PATH, --generator GENERATOR_PATH
provide an alternative python generator file path
-j output a json file with information on ASN.1 objects dependency
-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
$ ./tools/pycrate_asn1compile.py -i ./test/res/Hardcore.asn -o Hardcore
[proc] [./test/res/Hardcore.asn] module HardcoreSyntax (oid: []): 116 ASN.1 assignments found
--- compilation cycle ---
--- compilation cycle ---
--- compilation cycle ---
--- verifications ---
[proc] ASN.1 modules processed: ['HardcoreSyntax']
[proc] ASN.1 objects compiled: 75 types, 3 sets, 37 values
[proc] done
```
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.8.5 (default, Jul 28 2020, 12:59:40)
[GCC 9.3.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> from Hardcore import HardcoreSyntax
>>> HardcoreSyntax # this is the only ASN.1 module provided in Hardcore.asn
<class 'Hardcore.HardcoreSyntax'>
>>> Final = HardcoreSyntax.Final # this is the Final object defined at line 115
>>> Final
<Final (SEQUENCE)>
>>> Final.get_proto() # warning: this can return very laaaaaaarge definitions
('SEQUENCE', {
w1: ('SEQUENCE', {
r10: ('SEQUENCE', {
low: 'INTEGER',
high: 'INTEGER',
bool: 'BOOLEAN',
null (OPT): 'NULL'
}),
r90: ('SEQUENCE', {
low: 'INTEGER',
high: 'INTEGER',
bool: 'BOOLEAN',
null (OPT): 'NULL'
})
}),
w2: ('SEQUENCE', {
r10: ('SEQUENCE', {
low: 'INTEGER',
high: 'INTEGER',
bool: 'BOOLEAN',
null (OPT): 'NULL'
}),
r90: ('SEQUENCE', {
low: 'INTEGER',
high: 'INTEGER',
bool: 'BOOLEAN',
null (OPT): '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*.
Do not forget to have a look at the [Wiki](https://github.com/pycrate-org/pycrate/wiki/), too!
Raw data
{
"_id": null,
"home_page": "https://github.com/pycrate-org/pycrate/",
"name": "pycrate",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "protocol format ASN.1 CSN.1 compiler encoder decoder mobile core network Diameter NAS S1AP NGAP TCAP MAP GTP PFCP SCCP ISUP",
"author": "Benoit Michau",
"author_email": "michau.benoit@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/f4/01/09aac6ea758ca7b7b1b4832c0c39003752ef7b6c1478e6db2f34171db3fe/pycrate-0.7.2.tar.gz",
"platform": null,
"description": "What is pycrate\n===============\n\nWhile this is a french joke about bad wine (you say \"picrate\" when it's close to vinegar !).\nThe present software library has nothing to do with wine (except it is developed in France), \nit is simply a Python library for manipulating various digital formats in an easy way,\nwith a funny name. Most of the format supported are related in one way or another\nto cellular network's signalling.\nIt is the glorious successor of [libmich](https://github.com/mitshell/libmich), \nwhich was started back in 2009, served well and retired in 2017.\n\nIt provides basically a runtime for encoding and decoding data structures, including\nCSN.1 and ASN.1. Additionally, it features a 3G and LTE mobile core network.\n\nThis updated repository inside the collaborative organization [pycrate-org](https://github.com/pycrate-org/),\nis the new home to keep maintaining and updating the project, starting February 2024.\nAny and all collaborative efforts will be much appreciated: from uncovering bugs and discussing issues, \nto integrate fixes and extensions through PR...\n\n\nLicense\n=======\n\nThe whole library is licensed under LGPL v2.1 and is compatible with more recent \nversion of the LGPL: all licensed files have an header making it self-explanatory.\nFor more details, please report to the \n[license.txt](https://github.com/pycrate-org/pycrate/blob/master/license.txt) file.\n\n\nWiki\n====\n\nPycrate has a growing [wiki](https://github.com/pycrate-org/pycrate/wiki/).\nUse it as much as possible before opening an issue.\nFeel free also to propose some additional content.\n\n\nInstallation\n============\n\nOperating systems and Python version\n------------------------------------\n\nThe library is designed to work with Python 3 (3.5 and greater), from the official Python \nimplementation [CPython](https://www.python.org/), and is systematically tested both on\nLinux, MacOS and Windows. It should also support alternative Python engines such as \n[pypy](http://pypy.org/), [nuitka](http://nuitka.net/) or [Cython](https://cython.org/) ; \nthis is however not regularly tested. It should also support any other operating systems which\nhas a decent Python 3 support.\n\nPython2 support is entirely abandonned end of 2022, and hence release 0.5.5 is the last one with\nfull support of Python 2.7.\n\n\nDependencies\n------------\n\nCurrently none. Only the Python builtins and few internal modules of Python \n(e.g. os, system, re, struct, datetime) are required for most of the features. \nThe json internal module is required for supporting the JSON API.\nIf you want to run pycrate in Python2 (which is bad !), you will however need to\ninstall the [enum34](https://pypi.org/project/enum34/) package.\n\nThe _pycrate\\_ether/SCTP_ module can optionally use the external \n[crc32c](https://pypi.org/project/crc32c/) module from ICRAR.\n\nThe _pycrate\\_mobile/TS24301\\_EMM_ and _pycrate\\_mobile/TS24501\\_FGMM_ modules use \n[CryptoMobile](https://github.com/mitshell/CryptoMobile) as optional dependency to \nencrypt and decrypt LTE and 5G NAS messages.\n\nThe _pycrate\\_corenet_ part requires also [pysctp](https://pypi.org/project/pysctp/) \nand [CryptoMobile](https://github.com/pycrate-org/CryptoMobile) to run.\n\nThe _pycrate\\_diameter/parse\\_iana\\_diameter\\_xml.py_ file uses \n[lxml](https://pypi.org/project/lxml/) to translate xml files from IANA to Python \ndictionnaries ; this is however not required for standard runtime.\n\nThe _pycrate\\_osmo/SEDebugMux.py_ module relies on the [crcmod](https://pypi.org/project/crcmod/)\nto compute custom CRC in the frame format.\n\n\nAutomatic installation\n----------------------\n\nAn installation script is available.\nAs soon as you have cloned or downloaded the repository, you can use it to install\nthe library within your Python package directory:\n\n```\npython setup.py install\n```\n\nRun it as superuser for a system-wide install, or as-is for a user home-directory \nlevel install. You can also run _develop_ instead of _install_ if you want a \ndeveloper-friendly installation.\n\nIt is also possible to test the library before installing it\n(this will create two local directories *./test_asn/* and *./pycrate.egg-info/* that\nyou can just delete afterwards):\n\n```\npython -m unittest test.test_pycrate\n```\n\nOr to build the library without installing it in the system:\n\n```\npython setup.py build\n```\n\nIt is also possible to recompile all ASN.1 modules, this will take few minutes\n(but if I did not do any mistake, all ASN.1 modules provided in *./pycrate_asn1dir/*\nshould have been compiled with the latest version of the compiler):\n\n```\npython -m pycrate_asn1c.asnproc\n```\n\nMore generally, installation is not required, and simply having all _pycrate\\_*_ \nsubdirectories into the PYTHONPATH enables to use the entire library.\n\n\nInstallation with pip\n---------------------\n\nAlternatively, you can install the library with the `pip` command:\n```\npip install pycrate\n```\n\nThe install package is available on [pypi](https://pypi.org/project/pycrate/).\nIt contains the library from the last tagged release on github (which may be months old).\n\n\nContributing\n============\n\nContact and support\n-------------------\n\nThis library is free software, and you are free to use it (or not to use it). \nIn case you encounter a problem with it, first read this README completely and then\ncheck the [Wiki](https://github.com/pycrate-org/pycrate/wiki/) ; moreover many classes, \nmethods and functions are documented with docstrings, and finally you can have a look \nat the source code (it won't bite you).\n\nIf after all those steps, you still have a question or you think you found a bug,\nplease open an issue (see below). Specific support requires time and may not be always \npossible. In case you require such support, please consider also contributing in one \nway or another (see below, too).\n\nIn case you are using this library in any of your project and you find it useful,\ndo not hesitate to send me an email. It is always a pleasure to know where code provided \non the Internet can end up... (I am personally aware of some dark places where a pycrate's\nfork lies).\n\n\nFilling an issue\n---------------\n\nWhen filling an issue, please provide precise and contextual information about \nyour case and the error you potentially encounter:\n- indicate the version (or commit-level) of pycrate you are using, together with the version of Python.\n- provide a code snippet that leads to the error you are facing, so that it can be reproduced.\n- provide the eventual stacktrace you are getting from Python\n- provide additional and contextual information as needed (e.g. a specific ASN.1 specification being used...)\n\nThis is the bare minimum if you want to get help.\nAnd when you consider your issue has been addressed, please close it: \"A good issue is a closed one !\"\nas would have said my great grandmother.\n\n\nExtending the library\n---------------------\n\nIf you are willing to extend the library, do not hesitate to contact me by\nemail or preferably through the github service (ideally, open a pull request).\nFor important changes, please elaborate about your need and provide some justification.\nAny patch or submission is always very welcome!\n\n\nOther contributions\n-------------------\n\nIn case you do not want to deep dive in the code, you can still contribute in many ways:\n* highlighting specific issues in the inner-working of the library,\nand opening an issue with concrete debugging information \n* writing new test cases for more coverage (have a look at the *test/* directory)\n* sending captures / real-world data that can be used for writing new test cases\n* writing new parts of the wiki (have a look at the \n[pycrate wiki](https://github.com/pycrate-org/pycrate/wiki/))\n\nGetting contributions is extremely important to encourage the continuous development\nof the library, and to confirm the choice made to open-source it.\n\n\nComponents\n==========\n\nPycrate is actually more a software suite than a single library. It is composed\nof several subdirectories, each providing specific services.\n\n\npycrate_core\n------------\n\nThe core of the library.\n* *utils* provides basics functions to manipulate integers, bytes and bits\n* *charpy* provides the Charpy class to handle easily the consumption of a bit-stream\n* *elt* and *base* are providing several classes to help when building complex\n data structures\n* *repr* provides simple functions to help with the representation of instances\n from the *elt* and *base* modules\n\nSome of the most useful features are provided by the *pack_val()* functions from \nthe *utils* module and the *Charpy* class from the *charpy* module.\nThey help to deal easily with packing and unpacking bytes and integers \n(signed / unsigned, little / big endian) in an aligned and unaligned way.\nAll lengths of fields are provided in bits, hence facilitating the handling of \nunaligned structures.\n\n\npycrate_ether\n-------------\n\nThe modules provided here implement Ethernet and IP-oriented protocols and formats.\n* *MPLS* with structures for MPLS label and header\n* *Ethernet* with structures for Ethernet and VLAN headers\n* *ARP* simply providing the structure for ARP\n* *IP* with structures for IPv4, IPv6, ICMP, UDP and TCP\n* *SCTP* with structures for SCTP headers and various chunks\n* *PCAP* with structures for the PCAP global header and the record header\n\n\npycrate_media\n-------------\n\nThe modules here implement various multimedia formats.\n* *JPEG* with detailed structures used in the JPEG format\n* *GIF* with detailed structures used in the GIF format\n* *TIFF* with detailed structures used in the TIFF format\n* *BMP* with structures used in the BMP format\n* *PNG* with the basic structure used in the PNG format\n* *MPEG4* with the basic structure used in the MPEG4 file format\n* *MP3* with detailed structures used in the MP3 format, including ID3v1 and ID3v2 tags\n\nMost of the classes here implement a complete recipe to parse all of those format in a \nsingle shot, by using their *from_char()* method.\n\n\npycrate_asn1c\n-------------\n\nAll the modules here serve the sole purpose of compiling ASN.1 specifications.\nThe most important ones are:\n* *asnobj* which is the almighty class when parsing any ASN.1 definition\n* *generator* which provides two distinct generators to produce source files from\n the ASN.1 objects processed in Python: *PycrateGenerator* which produces source \n file to be used with the pycrate ASN.1 runtime (in *pycrate_asn1rt*), \n and *JSONDepGraphGenerator* which produces json file listing object dependencies \n (which then can be browsed dynamically thanks to D3).\n* *asnproc* which is the top-level module for the compiler, it contains for example \n the *compile_text()* function which compiles a serie of ASN.1 modules into\n Python objects\n \nThis compiler support most of the ASN.1 language features, including parameterization and\nclass objects and sets (especially useful when working with table constraints).\nIt has however few restrictions, the biggest being the need for the left part of the ASN.1\nassignment *::=* being on a single line. Also, old-school ASN.1 macros are not supported ;\nhence, the compiler cannot parse SNMP MIBs. \n\n\npycrate_asn1dir\n---------------\n\nThis subdirectory contains several ASN.1 specifications that are supported and \nprecompiled for pycrate. Very few specifications have been changed in order to\nwork with pycrate :\n* Q.775, in which the terrible *AllPackagesAS* is commented out\n* Q.773 and Q.775, in which the *TCInvokeIdSet* constraint is modified to be\n used as a set of values\nThat's all !\n\n\npycrate_asn1rt\n--------------\n\nThis subdirectory contains the ASN.1 runtime, that is loaded and used by the ASN.1 \nspecifications compiled with the compiler in *pycrate_asn1c*. It supports \nthe PER encoding rules (aligned and not, canonical also), and the BER, CER, DER \nand JER encoding rules.\n\n\npycrate_csn1\n------------\n\nThis subdirectory contains a CSN.1 to Python translater in the file *trans.py*,\nand a CSN.1 runtime in the file *csnobj.py*, in order to encode and decode CSN.1 \nstructures translated to Python objects.\n\n\npycrate_csn1dir\n---------------\n\nThis subdirectory contains CSN.1 structures extracted from 3GPP specifications\n(in the .csn files), and translated into Python objects. The following specifications\nhave been used: TS 44.018, TS 44.060 and TS 24.008.\n\n\npycrate_mobile\n--------------\n\nThis subdirectory implements most of the 3GPP NAS protocol formats:\n* *GSMTAP*: gsmtap header format\n* *MCC_MNC*: dictionnaries for MCC and MNC look-up\n* *NAS*: provides two functions to parse any uplink and downlink mobile NAS messages\n* *NASLTE*: provides two functions to parse LTE uplink and downlink NAS messages\n* *NAS5G*: provides one function to parse 5G uplink and downlink mobile NAS messages\n* *PPP*: structures for NCP and LCP protocols used for PPP connection estabishment, \n as defined in RFC 1661, 1332 and 1334\n* *SCCP*: structures for SCCP user-data and management messages as defined in ITU-T Q.713\n* *ISUP*: structures for ISUP messages as defined in ITU-T Q.763\n* *SIGTRAN*: generic structures for SIGTRAN (i.e. M2UA, M2PA, MTP3 and M3UA) messages\n* *M3UA*: structures dedicated to the M3UA format from RFC 4666\n* *TS102225*: structures for SIM card's Secured Packets from ETSI TS 102.225\n* *TS23038*: structures and routines for SMS encoding from TS 23.038\n* *TS23040_SMS*: structures for the SMS transport protocol from TS 23.040\n* *TS23041_CBS*: structures for the Cell Broadcast Service protocol from TS 23.041\n* *TS24007*: basic structures from the TS 24.007 specification, reused in most of the NAS protocols\n* *TS24008_CC* : structures for call control messages from TS 24.008\n* *TS24008_GMM*: structures for GPRS mobility management messages from TS 24.008\n* *TS24008_IE*: structures for many information elements from TS 24.008\n* *TS24008_MM*: structures for mobility management messages from TS 24.008\n* *TS24008_SM*: structures for GPRS session management messages from TS 24.008\n* *TS24011_PPSMS*: structures for the SMS point-to-point protocol from TS 24.011\n* *TS24080_SS*: structures for the Supplementary Services protocol from TS 24.080, \n wrapping some MAP ASN.1 objects\n* *TS24301_EMM*: structures for the EPS mobility management messages from TS 24.301\n* *TS24301_ESM*: structures for the EPS session management messages from TS 24.301\n* *TS24301_IE*: structures for many information elements from TS 24.301\n* *TS24501_FGMM*: structures for the 5G mobility management messages from TS 24.501\n* *TS24501_FGSM*: structures for the 5G session management messages from TS 24.501\n* *TS24501_IE*: structures for many information elements from TS 24.501\n* *TS24501_UEPOL*, *TS24526_UEPOL* and *TS24588_UEPOL*: structures for the 5G UE policy protocol \n from TS 24.501, 526 and 588\n* *TS29002_MAPAppCtx*: functions that relies on the Pycrate_TCAP_MAPv2v3 ASN.1 module, \n dealing mostly with MAP application-contexts\n* *TS29002_MAPIE*: structure for the MAP AddressString object from TS 29.002\n* *TS29244_PFCP*: structure for PFCP messages from TS 29.244\n* *TS0960_GTPv0*: structures for 2G GTP version 0 from TS 09.60\n* *TS29060_GTP*: structures for 2G/3G GTP-C version 1 from TS 29.060\n* *TS29274_GTPC*: structures for 4G GTP-C version 2 from TS 29.274\n* *TS29281_GTPU*: structures for 2G/3G/4G/5G GTP-U from TS 29.281\n* *TS31111_SAT*: basic structures and dict for the SIM application toolkit from TS 31.111\n* *TS31115*: structures for SIM card's Secured Packets over SMS from TS 31.115\n* *TS38415_PDUSess*: structure used in 5G user-place traffic (i.e. GTP-U) from TS 38.415\n* *TS44018_GTTP*: structure for the single GSM GTTP message from TS 44.018\n* *TS44018_IE*: structures for many information elements from TS 44.018\n* *TS44018_RR*: structures for the GSM and GPRS radio ressources messages from TS 44.018\n* *TS48058_Abis*: few IE structures for the GSM Abis protocol from TS 48.058\n\n\npycrate_diameter\n----------------\n\nThis subdirectory contains the following modules:\n* *parse_iana_diameter_xml*: to translate XML Diameter structures from IANA to Python\n* *iana_diameter_dicts.py*: that is automatically created by the former, containing Diameter Python dicts\n* *Diameter*: a generic Diameter module which implements DiameterGeneric and AVPGeneric structures\n* *DiameterIETF*: a Diameter module which relies on AVP types provided in all IETF RFC\n* *Diameter3GPP*: a Diameter module which relies on AVP types provided in all 3GPP TS\n\n\npycrate_osmo\n------------\n\nThis subdirectory contains the following modules:\n* *L1CTL*: structures to control the osmocom-bb GSM embedded stack from the host\n* *SEDebugMux*: structure used by Sony-Ericsson SoC and basebands to wrap logs\n* *RRCTL*: structures to interact with the RRC layer of the UE emulator from this \n [fork](https://gitea.osmocom.org/vyanitskiy/srsRAN/src/branch/extnas/release_20_10) of srs-lte\n\n\npycrate_corenet\n---------------\n\nThis subdirectory implements a signaling server that supports IuCS and IuPS over Iuh interfaces\n(including HNBAP and RUA/RANAP) for interfacing with 3G femtocells, and S1 interfaces \n(including S1AP) for interfacing with LTE eNodeBs.\nIt handles many procedures to drive femtocells, eNodeBs and mobile terminals connecting\nthrough them. In terms of services, it mostly support short messages and data connectivity.\nIt does not handle call services, neither active mobility procedures (handovers).\n\nIt can be easily (common, running a mobile core network is not *that* easy) \nconfigured and used thanks to the [corenet](https://github.com/mitshell/corenet/) project, \nalso open-source.\n\n\npycrate_gmr1\n------------\n\nThis subdirectory contains the main module for the GMR-1 Radio Resources protocol: *TS101376_04_08*,\nand the submodule for specific Information Elements: *TS101376_04_08_IE*.\nThis is a partial implementation of the ETSI specification TS 101 376-04-08 for the \nGEO-Mobile Radio Interface Specifications (Release 3).\n\n\npycrate_gmr1_csn1\n-----------------\n\nThis subdirectory contains all the CSN.1 definitions for the GMR-1 Radio Resources protocol,\nextracted from the 3 ETSI specifications for GEO-Mobile Radio release 3:\nTS 101 376-04-08, TS 101 376-04-12 and 101 376-04-13.\n\n\nUsage\n=====\n\nMost of the modules have doc strings. I try also to write readable sources and to\ncomment them as much as possible for understanding them easily (and to allow also\nmyself to understand my own code years after...).\nA [wiki](https://github.com/pycrate-org/pycrate/wiki/) is provided \nand extended from time to time, to bring examples and methods on how to use the \ndifferent modules (any contribution on this would be very welcome, too).\nFinally, the code provided in the *test/* subdirectory is also representative on\nhow to use the different modules.\n\nBasically, a pycrate's object exposes the following methods:\n* `set_val()` / `get_val()` / `get_val_d()`, which sets value into and gets value from the object\n* `from_bytes()` / `to_bytes()`, which converts a buffer into values according to the internal structure of the object, and back\n* `from_json()` / `to_json()`, for working with JSON-encoded values\n* `hex()` / `bin()`, for getting hexadecimal and binary representation of the serialized obect's value\n* `repr()` / `show()`, for providing nice python's internal representation, and printable representation of the object's value\n\n\nASN.1 usage\n===========\n\nWhen a Python module from *pycrate_asn1dir/* is loaded, it creates Python classes\ncorresponding to ASN.1 modules (all dash characters are converted to underscore).\nEach ASN.1 object has a corresponding Python instance, exposing the following methods:\n* `from_asn1()` / `to_asn1()`, which converts ASN.1 textual value to Python value and back\n* `from_aper()` / `to_aper()`, which converts aligned PER encoded value to Python value and back\n* `from_uper()` / `to_uper()`, which converts unaligned PER\n* `from_ber()` / `to_ber()`, which converts BER\n* `from_cer()` / `to_cer()`, which converts CER\n* `from_der()` / `to_der()`, which converts DER\n* `from_jer()` / `to_jer()`, which converts JER\n* `from_oer()` / `to_oer()`, which converts OER\n* `from_coer()` / `to_coer()`, which converts canonical OER\n* `set_val()` / `get_val()` to set and get Python's values into the ASN.1 object\n* `get_proto()` to return to internal structure of the ASN.1 object\n\nAll the methods useful for working with ASN.1 objects at runtime can be found in \nthe file *pycrate_asn1rt/asnobj.py*.\n\n\nTools\n=====\n\nFour different tools are provided (yet):\n* *pycrate_showmedia.py* parses some media files (jpg, bmp, gif, mp3, png, \n tiff, mpeg4) and pretty print the file structure on the standard output.\n* *pycrate_asn1compile.py* compiles ASN.1 source file(s) and produce a Python\n source file that makes use of the ASN.1 runtime. This source file is then\n usable to encode / decode any ASN.1 object from the compiled ASN.1 \n specification.\n* *pycrate_berdecode.py* parses any BER/CER/DER encoded binary value of ASN.1 \n objects and prints the corresponding structure.\n* *pycrate_map_op_info.py* prints prototypes and various information related to\n TCAP-MAP (Mobile Application Part) and CAMEL operations and application-contexts.\n* *pycrate_gtp_type_info.py* prints prototypes and various information related to\n GTP messages and transactions as in version 0, 1 or 2\n\n\nExamples\n========\n\nIt is possible to test the *pycrate_showmedia.py* tool with media test files \nprovided in *./test/res/*, or any other supported media file.\n\n```console\n$ ./tools/pycrate_showmedia.py --help\nusage: pycrate_showmedia.py [-h] [-bl BL] [-wt] input\n\nprint the internal structure of the input media file,supported formats are:\nBMP, GIF, JPEG, MP3, MPEG4, PNG, TIFF\n\npositional arguments:\n input input media file\n\noptional arguments:\n -h, --help show this help message and exit\n -bl BL maximum length for buffer representation\n -wt show also absent / transparent fields\n\n$ ./tools/pycrate_showmedia.py ./test/res/xkcd_wireless_signal.png \n### PNG ###\n <sig [PNG signature] : '\\x89PNG\\r\\n\\x1a\\n'>\n ### PNGBody ###\n ### PNGChunk ###\n <len : 13>\n <type : 'IHDR'>\n ### IHDR ###\n <width : 238>\n <height : 415>\n <depth [bit depth] : 8>\n <color [color type] : 0 (Greyscale)>\n <comp [compression method] : 0 (inflate/deflate with sliding window)>\n <filter [filter method] : 0 (no interlace)>\n <interlace [interlace method] : 0 (no interlace)>\n <crc : 0x7d8cb12e>\n ### PNGChunk ###\n <len : 9>\n <type : 'pHYs'>\n <data :\n 00 00 0c 4e 00 00 0c 4e 01 | '\\x00\\x00\\x0cN\\x00\\x00\\x0cN\\x01'>\n <crc : 0x7f778c23>\n ### PNGChunk ###\n <len : 792>\n <type : 'iCCP'>\n <data :\n 50 68 6f 74 6f 73 68 6f 70 20 49 43 43 20 70 72 | 'Photoshop ICC pr'\n 6f 66 69 6c 65 00 00 78 da 63 60 60 9e e0 e8 e2 | 'ofile\\x00\\x00x\\xdac``\\x9e\\xe0\\xe8\\xe2'\n [...]\n 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'\n f1 ff 7f 00 0d 00 0f 34 | '\\xf1\\xff\\x7f\\x00\\r\\x00\\x0f4'>\n <crc : 0xfa96f15d>\n ### PNGChunk ###\n <len : 32>\n <type : 'cHRM'>\n <data :\n 00 00 6e 27 00 00 73 af 00 00 df f2 00 00 83 30 | \"\\x00\\x00n'\\x00\\x00s\\xaf\\x00\\x00\\xdf\\xf2\\x00\\x00\\x830\"\n 00 00 77 43 00 00 c8 0a 00 00 34 95 00 00 2e dc | '\\x00\\x00wC\\x00\\x00\\xc8\\n\\x00\\x004\\x95\\x00\\x00.\\xdc'>\n <crc : 0x20bf171a>\n ### PNGChunk ###\n <len : 21130>\n <type : 'IDAT'>\n <data :\n 78 da ed bd 79 50 8d fd 1f ff ff bc ce 39 73 4e | 'x\\xda\\xed\\xbdyP\\x8d\\xfd\\x1f\\xff\\xff\\xbc\\xce9sN'\n db b4 37 95 32 b4 19 94 06 2d 7e 11 26 b2 fc 10 | '\\xdb\\xb47\\x952\\xb4\\x19\\x94\\x06-~\\x11&\\xb2\\xfc\\x10'\n [...]\n 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!'\n 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'\n ...>\n <crc : 0xa9fbdd38>\n ### PNGChunk ###\n <len : 0>\n <type : 'IEND'>\n <data : >\n <crc : 0xae426082>\n```\n\nIt is possible to test the *pycrate_asn1compile.py* tool with some test ASN.1 \nspecification from *./test/res/*, or any other valid ASN.1 specification of your\nchoice.\n\n```console\n$ ./tools/pycrate_asn1compile.py --help\nusage: pycrate_asn1compile.py [-h] [-s SPEC] [-i INPUT [INPUT ...]] [-o OUTPUT] [-g GENERATOR_PATH] [-j] [-fautotags] [-fextimpl] [-fverifwarn]\n\ncompile ASN.1 input file(s) for the pycrate ASN.1 runtime\n\noptional arguments:\n -h, --help show this help message and exit\n -s SPEC provide a specification shortname, instead of ASN.1 input file(s)\n -i INPUT [INPUT ...] ASN.1 input file(s) or directory\n -o OUTPUT compiled output Python (and json) source file(s)\n -g GENERATOR_PATH, --generator GENERATOR_PATH\n provide an alternative python generator file path\n -j output a json file with information on ASN.1 objects dependency\n -fautotags force AUTOMATIC TAGS for all ASN.1 modules\n -fextimpl force EXTENSIBILITY IMPLIED for all ASN.1 modules\n -fverifwarn force warning instead of raising during the verification stage\n\n$ ./tools/pycrate_asn1compile.py -i ./test/res/Hardcore.asn -o Hardcore\n[proc] [./test/res/Hardcore.asn] module HardcoreSyntax (oid: []): 116 ASN.1 assignments found\n--- compilation cycle ---\n--- compilation cycle ---\n--- compilation cycle ---\n--- verifications ---\n[proc] ASN.1 modules processed: ['HardcoreSyntax']\n[proc] ASN.1 objects compiled: 75 types, 3 sets, 37 values\n[proc] done\n```\n\nAfter compiling a module, it is possible to load it in Python and use it for\nencoding / decoding any objects defined in it.\n\n```python\nPython 3.8.5 (default, Jul 28 2020, 12:59:40) \n[GCC 9.3.0] on linux\nType \"help\", \"copyright\", \"credits\" or \"license\" for more information.\n>>> from Hardcore import HardcoreSyntax\n>>> HardcoreSyntax # this is the only ASN.1 module provided in Hardcore.asn\n<class 'Hardcore.HardcoreSyntax'>\n>>> Final = HardcoreSyntax.Final # this is the Final object defined at line 115\n>>> Final\n<Final (SEQUENCE)>\n>>> Final.get_proto() # warning: this can return very laaaaaaarge definitions\n('SEQUENCE', {\nw1: ('SEQUENCE', {\n r10: ('SEQUENCE', {\n low: 'INTEGER',\n high: 'INTEGER',\n bool: 'BOOLEAN',\n null (OPT): 'NULL'\n }),\n r90: ('SEQUENCE', {\n low: 'INTEGER',\n high: 'INTEGER',\n bool: 'BOOLEAN',\n null (OPT): 'NULL'\n })\n }),\nw2: ('SEQUENCE', {\n r10: ('SEQUENCE', {\n low: 'INTEGER',\n high: 'INTEGER',\n bool: 'BOOLEAN',\n null (OPT): 'NULL'\n }),\n r90: ('SEQUENCE', {\n low: 'INTEGER',\n high: 'INTEGER',\n bool: 'BOOLEAN',\n null (OPT): 'NULL'\n })\n }),\nbool: 'BOOLEAN'\n})\n>>> V = {\n... 'w1':{'r10':{'low':5, 'high':50, 'bool':False}, 'r90':{'low':50, 'high':95, 'bool':False, 'null':0}},\n... 'w2':{'r10':{'low':1, 'high':10, 'bool':False}, 'r90':{'low':90, 'high':100, 'bool':True}},\n... 'bool': True}\n>>> Final.set_val(V)\n>>> print(Final.to_asn1()) # .to_asn1() returns a printable ASN.1 representation of the value\n{\n w1 {\n r10 {\n low 5,\n high 50,\n bool FALSE\n },\n r90 {\n low 50,\n high 95,\n bool FALSE,\n null NULL\n }\n },\n w2 {\n r10 {\n low 1,\n high 10,\n bool FALSE\n },\n r90 {\n low 90,\n high 100,\n bool TRUE\n }\n },\n bool TRUE\n}\n>>> Final.to_aper() # aligned PER\nb'*\\x85\\x92\\x80@\\x01\\x00\\x08\\x02\\xd5`'\n>>> Final.to_uper() # unaligned PER\nb'*\\x85\\x92\\x80@@\\x02\\x00\\xb5X'\n>>> Final.to_ber()\nb'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'\n>>> Final.to_cer()\nb'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'\n>>> Final.to_der()\nb'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'\n>>> Final.from_ber( Final.to_ber() )\n>>> Final() == V # or Final._val == V\nTrue\n```\n\nFor more information about the API exposed for each ASN.1 object, you can check\nthe docstrings of all ASN.1 objects, and also read the source file *pycrate_asn1rt/asnobj.py*.\nDo not forget to have a look at the [Wiki](https://github.com/pycrate-org/pycrate/wiki/), too!\n\n",
"bugtrack_url": null,
"license": "LGPL v2.1+",
"summary": "A software suite to handle various data and protocol formats",
"version": "0.7.2",
"project_urls": {
"Homepage": "https://github.com/pycrate-org/pycrate/"
},
"split_keywords": [
"protocol",
"format",
"asn.1",
"csn.1",
"compiler",
"encoder",
"decoder",
"mobile",
"core",
"network",
"diameter",
"nas",
"s1ap",
"ngap",
"tcap",
"map",
"gtp",
"pfcp",
"sccp",
"isup"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9e2c62b70226295961aa26e9c405003713036b2f1b4942752620ff35aca224d6",
"md5": "544d9d1f7a4f5e4d34b692ab4f60c587",
"sha256": "7619a0d2729109ef32602cb7dcbc16704d51526ecc3135df17a4693b5eeba954"
},
"downloads": -1,
"filename": "pycrate-0.7.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "544d9d1f7a4f5e4d34b692ab4f60c587",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 12956340,
"upload_time": "2024-03-02T15:23:37",
"upload_time_iso_8601": "2024-03-02T15:23:37.724596Z",
"url": "https://files.pythonhosted.org/packages/9e/2c/62b70226295961aa26e9c405003713036b2f1b4942752620ff35aca224d6/pycrate-0.7.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f40109aac6ea758ca7b7b1b4832c0c39003752ef7b6c1478e6db2f34171db3fe",
"md5": "37e1bda10f41fe947512e9d5f8289518",
"sha256": "8abd3fb9f3e7a2dc62061490f01e99b2a6185e88b1c9bf30db68853b748b8f61"
},
"downloads": -1,
"filename": "pycrate-0.7.2.tar.gz",
"has_sig": false,
"md5_digest": "37e1bda10f41fe947512e9d5f8289518",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 12088142,
"upload_time": "2024-03-02T15:23:41",
"upload_time_iso_8601": "2024-03-02T15:23:41.488993Z",
"url": "https://files.pythonhosted.org/packages/f4/01/09aac6ea758ca7b7b1b4832c0c39003752ef7b6c1478e6db2f34171db3fe/pycrate-0.7.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-02 15:23:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pycrate-org",
"github_project": "pycrate",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pycrate"
}
JSON
