Repository files navigation

A Python micro framework for building Diameter protocol applications.

• The Reason Behind
• Installation
• Simple Diameter class example
• Simple Bromelia class example
• License
• Documentation
• Thanks
• Links

bromelia has breathed for the first time to give a Pythonic way for manipulating Diameter protocol structures. Since there is a bunch of ways to handle the well-known HTTP protocol in an elegant fashion in Python, it lacks the same with Diameter.

It is designed to allow at least (but not limited to) five use cases:

1. Automate tests on Diameter-based mobile network platforms, such as 4G EPC and IMS networks,
2. Unlock front-end applications to interact with Diameter-based mobile network applications,
3. Inspect real Diameter traffic to extract relevant information,
4. Translate and interwork between Diameter and other telco protocols (2G/3G MAP e 5G HTTP/2 SBI),
5. Just have some fun.

It makes pretty easy and straightforward to start building the basic Diameter structures such as AVPs and Messages and send them down to/receive from the wire.

bromelia is powered with all AVPs and Messages defined in RFC 6733 (and more!).

For debugging and research purpose, it is also possible to create Diameter objects with raw bytes (eg. captured from network interfaces with both tcpdump and tshark tools).

Last but not least, thebromelia is extensivily tested usingunittest and require only one third-party package (pyyaml) which is used for parse the YAML config file in theBromelia class. The test suite are a good source of knownledge and documentation, where you may find examples on how to use each object and functionshere.

Install and update usingpip:

python3 -m pip install -U Bromelia

Dependencies can be installed using pip:

python3 -m pip install -r requirements.txt

Run unittests:

python3 -m unittest tests/*.pypython3 -m unittest tests/avps/etsi_3gpp*/*.pypython3 -m unittest tests/avps/ietf*/*.pypython3 -m unittest tests/lib/etsi_3gpp*/*.py

Then after setting up the config file as per explained in theTutorials section, you can run the Diameter application by issuing the Python interpreter. Keep in mind there are two ways to spin up a Diameter application: either with Diameter class or Bromelia class.

Find more information on how to run a simple Diameter class example inexamples/diameter-app1/README.md.

#: Script found in examples/diameter-app1/diameter_mme.pyfrombromeliaimportDiameterfrombromeliaimportDiameterRequestfrombromelia.avpsimport*frombromelia.lib.etsi_3gpp_s6aimport*frombromelia.lib.etsi_3gpp_swmimport*LOCAL_HOSTNAME="mme.epc.mynetwork.com"LOCAL_REALM="epc.mynetwork.com"REMOTE_HOSTNAME="hss.epc.mynetwork.com"REMOTE_REALM="epc.mynetwork.com"#: Basic Diameter object configconfig= {"MODE":"CLIENT","APPLICATIONS": [{"vendor_id":VENDOR_ID_3GPP,"app_id":DIAMETER_APPLICATION_S6a_S6d            }],"TRANSPORT_TYPE":"TCP","LOCAL_NODE_HOSTNAME":LOCAL_HOSTNAME,"LOCAL_NODE_REALM":LOCAL_REALM,"LOCAL_NODE_IP_ADDRESS":"127.0.0.1","LOCAL_NODE_PORT":3868,"PEER_NODE_HOSTNAME":REMOTE_HOSTNAME,"PEER_NODE_REALM":REMOTE_REALM,"PEER_NODE_IP_ADDRESS":"127.0.0.1","PEER_NODE_PORT":3870,"WATCHDOG_TIMEOUT":30}app=Diameter(config=config)#: Basic DiameterAVPs for ULR messageavps= [SessionIdAVP(LOCAL_HOSTNAME),AuthSessionStateAVP(NO_STATE_MAINTAINED),OriginHostAVP(LOCAL_HOSTNAME),OriginRealmAVP(LOCAL_REALM),DestinationRealmAVP(REMOTE_REALM),UserNameAVP("123456789123456"),RatTypeAVP(RAT_TYPE_EUTRAN),UlrFlagsAVP(3)]#: Create ULR messageulr=DiameterRequest(command_code=316,application_id=16777251)ulr.extend(avps)#: Setup Diameter connection, send ULR & receive ULAwithapp.context():whileapp.is_open():ula=app.send_message(ulr)break

$ python3 examples/diameter-app1/diameter_mme.py* Running Diameter app (3GPP S6a) on 127.0.0.1:3868 as TCP CLIENT mode (CEX)

For more information, seeHow to build your Diameter application: The 1st way (Not that good) inDocumentation section.

Find more information on how to run a simple Bromelia class example inexamples/diameter-app2/README.md.

#: Script found in examples/diameter-app2/bromelia_mme.pyfrombromeliaimportBromeliafrombromelia.constantsimport*frombromelia.lib.etsi_3gpp_s6aimport*frombromelia.lib.etsi_3gpp_s6aimportCLA# CancelLocationAnswerfrombromelia.lib.etsi_3gpp_s6aimportCLR# CancelLocationRequest#: Application initializationconfig_file=os.path.join(basedir,"bromelia_mme_config.yaml")app=Bromelia(config_file=config_file)app.load_messages_into_application_id([CLA,CLR],DIAMETER_APPLICATION_S6a_S6d)CLA=app.s6a_s6d.CLA#: Creating CLA alias@app.route(application_id=DIAMETER_APPLICATION_S6a_S6d,command_code=CANCEL_LOCATION_MESSAGE)defclr(request):returnCLA(result_code=DIAMETER_SUCCESS)if__name__=="__main__":app.run()#: It will be blocked until connection has been established

$ python3 examples/diameter-app2/bromelia_mme.py* Running Diameter app (3GPP S6a) on 127.0.0.1:3868 as TCP CLIENT mode (CEX)

For more information, seeHow to build your Diameter application: The 2nd way (The Best ever!) inDocumentation section.

bromelia is licensed under the terms of the MIT License. See the LICENSE file for the exact license text.

The documentation forbromelia is composed of tutorials on basic usage and links to the source for various predefined type classes.

• Building Blocks Part 1: Data Types
• Building Blocks Part 2: Diameter AVPs
• Building Blocks Part 3: Diameter Messages
• How to build your Diameter application: The 1st way (Not that good)
• How to build your Diameter application: The 2nd way (The Best ever!)

• Base Structures,bromelia.base
• Bromelia,bromelia.bromelia
• Constants,bromelia.constants
• Data Types,bromelia.types
• Diameter AVPs,bromelia.avps
• Diameter Messages,bromelia.messages
• Peer State Machine,bromelia.statemachine

Big thanks to my family and friends who have inspired me and supported this project.

Thebromelia library implements several pieces of different IETF RFC and 3GPP technical specs. If you want to look at a specific documentation after noticing it on the code comments (such as Diameter AVPs and Diameter Messages), follow the instructions below.

Use the pattern.

https://tools.ietf.org/html/rfc<NUMBER>

For instance, the RFC 6733 may be found as per link below.

https://tools.ietf.org/html/rfc6733

Use the link below to find a specific 3GPP TR/TS and its version. Fulfil the form and click onsearch.

https://webapp.etsi.org/key/queryform.asp