Improve wording

gnss-sdr · Sep 19, 2024 · aee65e1 · aee65e1
1 parent 3101230
commit aee65e1
Show file tree

Hide file tree

Showing 2 changed files with 70 additions and 53 deletions.
diff --git a/_posts/2024-07-11-osnma.md b/_posts/2024-07-11-osnma.md
@@ -11,18 +11,25 @@ sidebar:
   nav: "news"
 toc: true
 toc_sticky: true
-last_modified_at: 2024-07-11T11:54:02+02:00
+last_modified_at: 2024-09-19T11:54:02+02:00
 ---
 
-GNSS signal spoofing has become a frequent and concerning issue, particularly in
-regions experiencing military conflicts. This phenomenon can be easily monitored
-through various online platforms that utilize ADS-B data to detect and display,
-in near-real time, instances of aircraft being [jammed](http://gpsjam.org) or
-[spoofed](https://spoofing.skai-data-services.com) worldwide. In such scenarios,
-GNSS signal authentication emerges as a critical feature to mitigate the effects
-of spoofing. This can be achieved by detecting spoofed signals and either
-adequately warning the user, or by excluding non-authenticated satellite
-products in the computation of the Position, Velocity, and Time (PVT) solutions.
+Please note that OSNMA functionality is currently available only in the `next` branch
+of the [upstream repository](https://github.com/gnss-sdr/gnss-sdr) and will be included
+in the next stable release of GNSS-SDR.
+{: .notice--warning}
+
+GNSS signal spoofing has become a frequent and concerning issue, particularly in regions
+experiencing military conflicts. This phenomenon can be monitored through various online
+platforms that use [ADS-B data](https://en.wikipedia.org/wiki/Automatic_Dependent_Surveillance%E2%80%93Broadcast)
+to detect and display, in near-real time, instances of aircraft being
+[jammed](http://gpsjam.org) or [spoofed](https://spoofing.skai-data-services.com)
+worldwide.  In such scenarios, GNSS signal authentication is crucial for mitigating the
+effects of spoofing. This can be achieved by detecting spoofed signals at various stages
+of the signal processing chain, depending on the service provided by the system operator
+and the user’s receiver. If spoofed signals are detected, the receiver can respond by
+either issuing appropriate warnings to the user or excluding non-authenticated satellite
+signals from the computation of Position, Velocity, and Time (PVT) solutions.
 
 Galileo, the European GNSS, is currently testing its Open Service Navigation
 Message Authentication (OSNMA) service. OSNMA is designed to provide a secure,
@@ -43,7 +50,7 @@ able to authenticate it immediately. Shortly afterward, the sender discloses
 $$ K $$, allowing the receiver to authenticate the packet.
 {: .notice--info}
 
-The OSNMA protocol takes a similar approach: in each I/NAV navigation data
+The OSNMA service takes a similar approach: in each I/NAV navigation data
 subframe of the [Galileo E1 OS
 signal]({{ "/docs/tutorials/gnss-signals/#galileo-e1" | relative_url }}) (that
 is, every 30 seconds), a subset of satellites insert predefined sequences of
@@ -117,7 +124,7 @@ signals) can be activated by setting:
 GNSS-SDR.osnma_mode=strict
 ```
 
-Check out the page about [OSNMA configuration in
+Check out the documentation about the [OSNMA configuration parameters in
 GNSS-SDR]({{ "/docs/sp-blocks/global-parameters/#open-service-navigation-message-authentication-osnma" | relative_url }})
 for more information.
 
@@ -341,47 +348,50 @@ received data can be declared authenticated.
 
 ## Implementation of cryptographic functions in GNSS-SDR
 
-The OSNMA protocol requires the availability of two secure hash standards
-(SHA-256 and SHA3-256), two message authentication code functions (HMAC-SHA-256
-and CMAC-AES) for tag verification, and two Elliptic Curve Digital Signature
-Algorithms (ECDSA P-256 and ECDSA P-521) for the verification of the TESLA root
-key. In the testing phase, only SHA-256, HMAC-SHA-256, and ECDSA P-256 are used,
-but the others could be used in the future.
-
-Implementing cryptographic functions in C++ from scratch is often unnecessary
-and inefficient. Instead, leveraging well-known, reliable, and actively
-maintained open-source libraries ensures robust and secure implementations.
-These libraries undergo continuous testing and updates, benefiting from scrutiny
-by a vast user base. In the GNSS-SDR implementation, the objective was to enable
-the OSNMA service across the broadest possible range of hardware and software
+The OSNMA protocol requires two secure hash standards (SHA-256 and SHA3-256),
+two message authentication code functions (HMAC-SHA-256 and CMAC-AES) for tag
+verification, and two Elliptic Curve Digital Signature Algorithms (ECDSA P-256
+and ECDSA P-521) for verifying the TESLA root key, with only one option from
+each category used at a time. During the testing phase, only SHA-256, HMAC-SHA-256,
+and ECDSA P-256 are employed, but the others may be utilized in the future.
+
+Implementing cryptographic functions from scratch in C++ is often unnecessary and
+inefficient. Instead, leveraging well-known, reliable, and actively maintained
+open-source libraries ensures more robust and secure implementations. These
+libraries undergo continuous testing and updates, benefiting from scrutiny by a
+large, diverse user base. In the GNSS-SDR implementation, the goal was to enable
+the OSNMA service across the widest possible range of hardware and software
 environments, covering diverse setups such as embedded SoC/FPGA-based platforms,
-a Raspberry Pi 5, an x86-64-based personal computer, or even an M3 Apple's
-silicon processor working on a macOS environment. The required open-source
-dependency options, which are transparent to the user and automatically picked
-up by the build configuration system upon availability, are:
-
-- [OpenSSL](https://www.openssl.org/) is a robust, commercial-grade,
-  full-featured toolkit for general-purpose cryptography and secure
-  communication. Versions 1.x were published under a dual-license scheme that
-  was incompatible with the GPLv3.0 license, preventing the library from being a
-  mandatory dependency for GNSS-SDR in most GNU/Linux distributions. OpenSSL
-  1.1.1, released on Sep 11th, 2018, already implemented all the cryptographic
-  functions required by the OSNMA protocol. The licensing issue was resolved in
-  OpenSSL version 3.0.0, which transitioned to the Apache License 2.0, fully
-  compatible with GPLv3.0. Released on Sep 7th, 2021, OpenSSL 3.0.0 and its
-  subsequent updates support the cryptographic functions required by OSNMA and
-  have been incorporated into major GNU/Linux distributions released since 2022.
-  For instance, in Debian/Ubuntu-based distributions it can be installed as
-  `sudo apt install libssl-dev`.
-- [GnuTLS](https://www.gnutls.org/) is used as a fallback if OpenSSL is not
-  found in the host system when building GNSS-SDR. This Transport Layer Security
-  library, published under the GNU Lesser General Public License (LGPL), is
-  available even in older GNU/Linux distributions. However, some operating
-  systems may omit the optional (but necessary) SSL module. For instance, in
-  Debian/Ubuntu-based distributions it can be installed as
-  `sudo apt install libgnutls-openssl-dev`. This library implements all the
-  cryptographic functions required by OSNMA since version 3.6.13, released on
-  Apr 24th, 2020.
+the Raspberry Pi 5, older or less powerful x86-64-based personal computers, and
+even Apple's cutting-edge M3 silicon processors running in a macOS environment.
+The required open-source dependency options, which are transparent to the user
+and automatically picked up by the build configuration system upon availability,
+are:
+
+- [OpenSSL](https://www.openssl.org/) is a robust, commercial-grade, full-featured
+  toolkit for general-purpose cryptography and secure communication. Versions 1.x
+  were published under a dual-license scheme that was incompatible with the GPLv3.0
+  license, preventing the library from being a mandatory dependency for GNSS-SDR in
+  most GNU/Linux distributions. OpenSSL 1.1.1, released on September 11, 2018, had
+  already implemented all the cryptographic functions required by the OSNMA protocol.
+  The licensing issue was resolved in OpenSSL version 3.0.0, which transitioned to
+  the Apache License 2.0, fully compatible with GPLv3.0. Released on September 7,
+  2021, OpenSSL 3.0.0 and its subsequent updates support the cryptographic functions
+  required by OSNMA and have been incorporated into major GNU/Linux distributions
+  released since 2022. For instance, in Debian/Ubuntu-based distributions, it can be
+  installed with `sudo apt install libssl-dev`.
+
+- [GnuTLS](https://www.gnutls.org/) is used as a fallback if OpenSSL is not found on
+  the host system when building GNSS-SDR. You can force linking against GnuTLS even if
+  OpenSSL is installed by using the `-DENABLE_GNUTLS=ON`
+  [configuration option]({{ "/docs/tutorials/configuration-options-building-time/#binary-portability-and-packaging-options" | relative_url }}).
+  This Transport Layer Security library, published under the GNU Lesser General Public
+  License (LGPL), is available even in older GNU/Linux distributions. However, some
+  operating systems may omit the optional (but necessary) SSL module. For instance,
+  in Debian/Ubuntu-based distributions, it can be installed with
+  `sudo apt install libgnutls-openssl-dev`. This library has implemented all the
+  cryptographic functions required by OSNMA since version 3.6.13, released on April
+  24, 2020.
 
 ## Usage of OSNMA data in GNSS-SDR
 

diff --git a/_sp-blocks/01-global-parameters.md b/_sp-blocks/01-global-parameters.md
@@ -104,11 +104,18 @@ Users must register and log in on the [European GNSS Service Centre website](htt
 | `osnma_enable`  | [`true`, `false`]: Enables or disables the OSNMA service. It defaults to `true`. |   Optional   |
 | `osnma_public_key` | Path to the OSNMA Public Key (`.crt` file). it defaults to `./OSNMA_PublicKey_20240115100000_newPKID_1.crt` |   Optional   |
 | `osnma_merkletree` | Path to the Merkle Tree root (`.xml` file). It defaults to `./OSNMA_MerkleTree_20240115100000_newPKID_1.xml` |   Optional |
-| `osnma_mode` | If set to `strict`, only authenticated satellites are used in the PVT computation. If not set, the receiver will only log OSNMA events and warn the user in case of authentication failures. Please note that the `strict` mode requires the host computer's internal date and time to be synchronized with the Galileo System Time, allowing a tolerance of ±30 seconds, so it is only intended for real-time operation. |   Optional |
+| `osnma_mode` | If set to `strict`, only authenticated satellites are used in the PVT computation. If not set, the receiver will only log OSNMA events and warn the user in case of authentication failures. Please note that the `strict` mode requires the host computer's internal date and time to be synchronized with the Galileo System Time, allowing a tolerance of ±30 seconds, so it is only intended for real-time operation. No other systems than Galileo will be used in the PVT solution. |   Optional |
 | -------------- |
 
 Example in the configuration file:
 
+```ini
+GNSS-SDR.osnma_public_key=./OSNMA_PublicKey_20240115100000_newPKID_1.crt
+GNSS-SDR.osnma_merkletree=./OSNMA_MerkleTree_20240115100000_newPKID_1.xml
+```
+
+The same, but with the strict mode:
+
 ```ini
 GNSS-SDR.osnma_public_key=./OSNMA_PublicKey_20240115100000_newPKID_1.crt
 GNSS-SDR.osnma_merkletree=./OSNMA_MerkleTree_20240115100000_newPKID_1.xml