OSNMAlib

OSNMAlib is an open-source Python library that can be used for research purposes or be integrated into existing receivers and applications to incorporate navigation message authentication to the positioning process. It can read the Galileo I/NAV pages from an input, store the navigation and authentication data, perform the verification operations, and report the status.

The software has been successfully tested using the official ICD test vectors and data from corner cases recorded by us. To our knowledge, it has also been used to verify other third-party OSNMA implementations and in research.

Note that the security of the OSNMA protocol can only be guaranteed if the receiver providing the navigation data is aware of its synchronization with respect to the Galileo System Time. By default, OSNMAlib assumes a synchronization time (TS) of 30s: the maximum to process all tags. However, it can be configured for a different TS depending on what your receiver can guarantee. For live executions, OSNMAlib can use an NTP server or the local clock from the computer as synchronization sources. For more information about time synchronization see the OSNMA Receiver Guidelines, and Configuration Options to configure OSNMAlib.

OSNMAlib implements several optimizations in the cryptographic material extraction and in the process of linking navigation data to tags [link]. None of these optimizations imply trial-and-error on the verification process, so if you see authentication failures in a non-spoofing scenario, feel free to report them.

A live visualization of the output of OSNMAlib can be found at OSNMAlib.eu. This web view uses a receiver located in KU Leuven, Belgium, and live aggregated data from galmon, to display the general state of OSNMA. It also provides the raw navigation bits received and the OSNMAlib status in JSON format.

If you are using data from the OSNMA Test Phase (before 2023-08-03 11:00 UTC), use the OSNMA_Test_Phase_ICD branch. OSNMA updated its Public Key from ID 1 to ID 2 on 2025-12-10 10:00 UTC. Be mindful when using old data. I am providing both keys in the run folders.

Supports Python 3.10, 3.11 and 3.12. For older Python versions, check the branches. Tested on Linux and Windows.

OSNMAlib Features

Features supported:

• Verification of the public key retrieved from the DSM-PKR message.
• Verification of the TESLA root key retrieved from the DSM-KROOT message.
• Verification of a TESLA key against a root key or a previously authenticated key.
• Verification of the MACK message structure:
  • ADKD sequence.
  • MACSEQ value.
  • FLX tags.
• Verification of the ADKD 0, ADKD 4 and ADKD 12 tags.
• Authentication of the navigation data.
• Support for custom Time Synchronization values.
• Support for Cold Start, Warm Start and Hot Start.
• Support for the following events: EOC, CREV, NPK, PKREV, NMT, and OAM.
• JSON output for monitoring and postprocessing with json-schema [html|json].
• Report the Time To First Authenticated Fix (TTFAF) and Time To First Fix (TTFF) in terms of navigation data.
• Time synchronization options for live execution (local clock or NTP).

Extra optimizations for a faster TTFAF:

• Reconstruct broken HKROOT messages.
• Reconstruct TESLA key from partial MACK messages.
• Extract valid tags from broken MACK messages.
• Reed-Solomon recovery of I/NAV data using word types 17 to 20.
• Dual frequency reception of I/NAV data from the E5b-I signal.
• Link and recover lost data using the IOD and the COP.
  • Obtain TTFAF as low as 44 seconds in hot start.
  • IEEE TAES article: accepted version, published version.

Current input formats supported:

• Septentrio Binary Format (SBF) log files.
• Septentrio receiver live connection through IP port.
• u-blox UBX log files.
• u-blox live connection through COM port.
• Live aggregated data from the galmon project.
• Android GNSSLogger App files in postprocess (contact me if you are interested in live data).
• GNSS-SDR project format through UDP socket.
  • Note that GNSS-SDR recently implemented OSNMA inside their GNSS receiver.
• Allows for custom data by implementing your iterator.

Future development:

• IDD ICD implementation for authentication of cryptographic materials.

Documentation

OSNMAlib

• This README file.
• Wiki
• OSNMAlib Journal Paper IEEE JISPN - [local] - [online]
• OSNMAlib Conference Paper NAVITEC 2022 (outdated) - [local] - [online]
• See later in the README for a complete list of publications using OSNMAlib.

General OSNMA documentation

• GSC website with the reference documents
• Look at the ICD, the Receiver Guidelines, and the IDD

Quick Run - Try it!

Requirements

The required Python libraries can all be installed with pip using the requirements.txt file.

$ pip install -r requirements.txt

Current configuration

The folder custom_run/ contains the current Merkle Tree and Public Key, both downloaded from the official GSC website. It also contains the current_config.sbf file with the current configuration recorded by me. You can run it directly with the console with:

$ cd custom_run/
$ python run.py

Beware the console output will be huge. A log folder will be created with the same logs for easy parsing.

The run.py file contains a dictionary with the configuration parameters that are more useful for a normal user. The parameters are set to their default value, feel free to modify them at will.

You can also run your own SBF files by passing the file name as parameter. Mind to also update the Merkle Tree and Public Key files in the configuration dictionary of run.py appropriately.

$ cd custom_run/
$ python run.py [filename]

Real-time execution with data from Galmon

If you want to see the library process data in real-time but don't have a receiver, I've integrated OSNMAlib with the galmon project. You can find it under the folder live_galmon_run/ and run it with:

$ cd live_galmon_run/
$ python run.py

You will see information printed every 30s approximately. There may be some problems with the data received from galmon due to the P2P nature of this service.

The IP and Port are defaulted to 86.82.68.237:10000. You can specify your own in the Galmon input class constructor.

Real-time execution with a Septentrio receiver

If you have access to a Septentrio receiver SBF log output, I have implemented a real-time input module for that. To tell the receiver to output the required navigation data send the following commands to it. Mind that Stream2 or port 20000 may be in use.

setSBFOutput, Stream2, IPS1, GALRawINAV, sec1
setIPServerSettings, IPS1, 20000

Then just execute the software. By default, it connects to 192.168.3.1:20000.

$ cd live_septentrio_run/
$ python run.py

Other input formats

The wiki page Input Data contains useful information about all the input formats supported by OSNMAlib as well as documentation on how to develop a new one.

Test Execution

The software is provided with several test scenarios under the folder tests/scenarios/. The scenarios cover different configurations and events of the OSNMA protocol. The test files come from the Official Test Vectors and also from the live recording of some corner cases.

The pytest framework is the easiest way to execute the OSNMA Open Implementation receiver tests. To do so, the following shell commands are provided. Note that the users interpreter work directory is assumed to be the top folder of the provided software and python pip shall be already installed.

$ pip install -r requirements.txt
$ cd tests
$ pytest icd_test_vectors.py 
# or
$ pytest test_corner_cases.py 

The tests can also be executed using the traditional Python interpreter. In that case, just run the files.

OSNMAlib Configuration Options

OSNMAlib has several configuration parameters that can be defined previous to execution. The parameters are defined in a dictionary and passed to the receiver when creating the receiver object. The receiver will load default values for the configuration parameters not specified.

The most important parameters are:

• exec_path [mandatory]: Path to the folder where OSNMAlib wi