# Copyright (C) 2018-2023 Swift Navigation Inc.
# Contact: https://support.swiftnav.com
#
# This source is subject to the license found in the file 'LICENSE' which must
# be distributed together with this source. All other rights reserved.
#
# THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
# EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED
# WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.

package: swiftnav.sbp.signing
description: Messages relating to signatures
stable: False
public: True

include:
  - types.yaml

definitions:

  - UtcTime:
      short_desc: UTC Time
      fields:
        - year:
            type: u16
            units: year
            desc: Year
        - month:
            type: u8
            units: months
            desc: Month (range 1 .. 12)
        - day:
            type: u8
            units: day
            desc: days in the month (range 1-31)
        - hours:
            type: u8
            units: hours
            desc: hours of day (range 0-23)
        - minutes:
            type: u8
            units: minutes
            desc: minutes of hour (range 0-59)
        - seconds:
            type: u8
            units: seconds
            desc: seconds of minute (range 0-60) rounded down
        - ns:
            type: u32
            units: nanoseconds
            desc: nanoseconds of second
                  (range 0-999999999)

  - ECDSASignature:
      short_desc: ECDSA signature
      fields:
        - len:
            type: u8
            desc: >
              Number of bytes to use of the signature field.  The DER encoded
              signature has a maximum size of 72 bytes but can vary between 70
              and 72 bytes in length.
        - data:
            type: array
            fill: u8
            size: 72
            desc: >
              DER encoded ECDSA signature for the messages using SHA-256 as the digest
              algorithm.

  - MSG_ECDSA_CERTIFICATE:
      id: 0x0C04
      short_desc: An ECDSA certificate split over multiple messages
      desc: >
        A DER encoded x.509 ECDSA-256 certificate (using curve secp256r1).
      fields:
        - n_msg:
            type: u8
            desc: >
              Total number messages that make up the certificate. The first
              nibble (mask 0xF0 or left shifted by 4 bits) is the size of the
              sequence (n), second nibble (mask 0x0F) is the zero-indexed
              counter (ith packet of n).
        - certificate_id:
            type: array
            fill: u8
            size: 4
            desc: The last 4 bytes of the certificate's SHA-1 fingerprint
        - flags:
            type: u8
            fields:
              - 0-2:
                  desc: Certificate type
                  values:
                    - 0: Corrections certificate
                    - 1: Root certificate
                    - 2: Intermediate certificate
        - certificate_bytes:
            type: array
            fill: u8
            desc: DER encoded x.509 ECDSA certificate bytes

  - MSG_CERTIFICATE_CHAIN:
      id: 0x0C09
      short_desc: The certificate chain
      fields:
        - root_certificate:
            type: array
            fill: u8
            size: 20
            desc: SHA-1 fingerprint of the root certificate
        - intermediate_certificate:
            type: array
            fill: u8
            size: 20
            desc: SHA-1 fingerprint of the intermediate certificate
        - corrections_certificate:
            type: array
            fill: u8
            size: 20
            desc: SHA-1 fingerprint of the corrections certificate
        - expiration:
            type: UtcTime
            desc: >
              The time after which the signature given is no longer valid.
              Implementors should consult a time source (such as GNSS) to
              check if the current time is later than the expiration time,
              if the condition is true, signatures in the stream should not
              be considered valid.
        - signature:
            type: ECDSASignature
            desc: >
              Signature (created by the root certificate) over the
              concatenation of the SBP payload bytes preceding this field. That
              is, the concatenation of `root_certificate`,
              `intermediate_certificate`, `corrections_certificate` and
              `expiration`.  This certificate chain (allow list) can also be
              validated by fetching it from `http(s)://certs.swiftnav.com/chain`.

  - MSG_CERTIFICATE_CHAIN_DEP:
      id: 0x0C05
      short_desc: Deprecated
      desc: Deprecated.
      public: false
      replaced_by:
        - MSG_CERTIFICATE_CHAIN
      fields:
       - root_certificate:
           type: array
           fill: u8
           size: 20
           desc: SHA-1 fingerprint of the root certificate
       - intermediate_certificate:
           type: array
           fill: u8
           size: 20
           desc: SHA-1 fingerprint of the intermediate certificate
       - corrections_certificate:
           type: array
           fill: u8
           size: 20
           desc: SHA-1 fingerprint of the corrections certificate
       - expiration:
           type: UtcTime
           desc: >
             The certificate chain comprised of three fingerprints: root
             certificate, intermediate certificate and corrections certificate.
       - signature:
           type: array
           fill: u8
           size: 64
           desc: >
             An ECDSA signature (created by the root certificate) over the
             concatenation of the SBP payload bytes preceding this field. That
             is, the concatenation of `root_certificate`,
             `intermediate_certificate`, `corrections_certificate` and
             `expiration`.  This certificate chain (allow list) can also be
             validated by fetching it from `http(s)://certs.swiftnav.com/chain`.

  - MSG_AES_CMAC_SIGNATURE:
      id: 0x0C10
      short_desc: AES-CMAC 128 digital signature
      desc: Digital signature using AES-CMAC 128 algorithm used for data integrity.
      fields:
        - stream_counter:
            type: u8
            desc: >
              Signature message counter. Zero indexed and incremented with each
              signature message.  The counter will not increment if this message
              was in response to an on demand request.  The counter will roll
              over after 256 messages. Upon connection, the value of the counter
              may not initially be zero.
        - on_demand_counter:
            type: u8
            desc: >
              On demand message counter. Zero indexed and incremented with each
              signature message sent in response to an on demand message. The
              counter will roll over after 256 messages.  Upon connection, the
              value of the counter may not initially be zero.
        - certificate_id:
            type: array
            fill: u8
            size: 4
            desc: The last 4 bytes of the certificate's SHA-1 fingerprint
        - signature:
            type: array
            fill: u8
            size: 16
            desc: Signature (CMAC tag value)
        - flags:
            type: u8
            desc: Describes the format of the 'signed_messages' field.
            fields:
              - 0-1:
                  desc: CRC type
                  values:
                    - 0: 24-bit CRCs from RTCM framing
                    - 1: 16-bit CRCs from SBP framing
        - signed_messages:
            type: array
            fill: u8
            desc: >
              CRCs of the messages covered by this signature.  For Skylark,
              which delivers SBP messages wrapped in Swift's proprietary RTCM
              message, these are the 24-bit CRCs from the RTCM message framing.
              For SBP only streams, this will be 16-bit CRCs from the SBP
              framing.  See the `flags` field to determine the type of CRCs
              covered.

  - MSG_ECDSA_SIGNATURE:
      id: 0x0C08
      short_desc: An ECDSA signature
      desc: >
        An ECDSA-256 signature using SHA-256 as the message digest algorithm.
      fields:
        - flags:
            type: u8
            desc: Describes the format of the 'signed_messages' field.
            fields:
              - 0-1:
                  desc: CRC type
                  values:
                    - 0: 24-bit CRCs from RTCM framing
                    - 1: 16-bit CRCs from SBP framing
        - stream_counter:
            type: u8
            desc: >
              Signature message counter. Zero indexed and incremented with each
              signature message.  The counter will not increment if this message
              was in response to an on demand request.  The counter will roll
              over after 256 messages. Upon connection, the value of the counter
              may not initially be zero.
        - on_demand_counter:
            type: u8
            desc: >
              On demand message counter. Zero indexed and incremented with each
              signature message sent in response to an on demand message. The
              counter will roll over after 256 messages.  Upon connection, the
              value of the counter may not initially be zero.
        - certificate_id:
            type: array
            fill: u8
            size: 4
            desc: The last 4 bytes of the certificate's SHA-1 fingerprint
        - signature:
            type: ECDSASignature
            desc: >
              Signature over the frames of this message group.
        - signed_messages:
            type: array
            fill: u8
            desc: >
              CRCs of the messages covered by this signature.  For Skylark,
              which delivers SBP messages wrapped in Swift's proprietary RTCM
              message, these are the 24-bit CRCs from the RTCM message framing.
              For SBP only streams, this will be 16-bit CRCs from the SBP
              framing.  See the `flags` field to determine the type of CRCs
              covered.

  - MSG_ECDSA_SIGNATURE_DEP_B:
      id: 0x0C07
      short_desc: Deprecated
      desc: Deprecated.
      public: false
      replaced_by:
        - MSG_ECDSA_SIGNATURE
      fields:
        - flags:
            type: u8
            desc: Describes the format of the 'signed_messages' field.
            fields:
              - 0-1:
                  desc: CRC type
                  values:
                    - 0: 24-bit CRCs from RTCM framing
                    - 1: 16-bit CRCs from SBP framing
        - stream_counter:
            type: u8
            desc: >
              Signature message counter. Zero indexed and incremented with each
              signature message.  The counter will not increment if this message
              was in response to an on demand request.  The counter will roll
              over after 256 messages. Upon connection, the value of the counter
              may not initially be zero.
        - on_demand_counter:
            type: u8
            desc: >
              On demand message counter. Zero indexed and incremented with each
              signature message sent in response to an on demand message. The
              counter will roll over after 256 messages.  Upon connection, the
              value of the counter may not initially be zero.
        - certificate_id:
            type: array
            fill: u8
            size: 4
            desc: The last 4 bytes of the certificate's SHA-1 fingerprint
        - n_signature_bytes:
            type: u8
            desc: >
              Number of bytes to use of the signature field.  The DER encoded
              signature has a maximum size of 72 bytes but can vary between 70
              and 72 bytes in length.
        - signature:
            type: array
            fill: u8
            size: 72
            desc: >
              DER encoded ECDSA signature for the messages using SHA-256 as the digest
              algorithm.
        - signed_messages:
            type: array
            fill: u8
            desc: >
              CRCs of the messages covered by this signature.  For Skylark,
              which delivers SBP messages wrapped in Swift's proprietary RTCM
              message, these are the 24-bit CRCs from the RTCM message framing.
              For SBP only streams, this will be 16-bit CRCs from the SBP
              framing.  See the `flags` field to determine the type of CRCs
              covered.

  - MSG_ECDSA_SIGNATURE_DEP_A:
      id: 0x0C06
      short_desc: Deprecated
      desc: Deprecated.
      public: false
      replaced_by:
        - MSG_ECDSA_SIGNATURE
      fields:
        - flags:
            type: u8
            desc: Describes the format of the 'signed_messages' field.
            fields:
              - 0-1:
                  desc: CRC type
                  values:
                    - 0: 24-bit CRCs from RTCM framing
                    - 1: 16-bit CRCs from SBP framing
        - stream_counter:
            type: u8
            desc: >
              Signature message counter. Zero indexed and incremented with each
              signature message.  The counter will not increment if this message
              was in response to an on demand request.  The counter will roll
              over after 256 messages. Upon connection, the value of the counter
              may not initially be zero.
        - on_demand_counter:
            type: u8
            desc: >
              On demand message counter. Zero indexed and incremented with each
              signature message sent in response to an on demand message. The
              counter will roll over after 256 messages.  Upon connection, the
              value of the counter may not initially be zero.
        - certificate_id:
            type: array
            fill: u8
            size: 4
            desc: The last 4 bytes of the certificate's SHA-1 fingerprint
        - signature:
            type: array
            fill: u8
            size: 64
            desc: >
              ECDSA signature for the messages using SHA-256 as the digest
              algorithm.
        - signed_messages:
            type: array
            fill: u8
            desc: >
              CRCs of the messages covered by this signature.  For Skylark,
              which delivers SBP messages wrapped in Swift's proprietary RTCM
              message, these are the 24-bit CRCs from the RTCM message framing.
              For SBP only streams, this will be 16-bit CRCs from the SBP
              framing.  See the `flags` field to determine the type of CRCs
              covered.

  - MSG_ED25519_CERTIFICATE_DEP:
      id: 0x0C02
      short_desc: Deprecated
      desc: Deprecated.
      public: false
      replaced_by:
        - MSG_ECDSA_CERTIFICATE
      fields:
        - n_msg:
            type: u8
            desc: >
              Total number messages that make up the certificate. First nibble
              is the size of the sequence (n), second nibble is the zero-indexed
              counter (ith packet of n)
        - fingerprint:
            type: array
            fill: u8
            size: 20
            desc: SHA-1 fingerprint of the associated certificate.
        - certificate_bytes:
            type: array
            fill: u8
            desc: ED25519 certificate bytes.

  - MSG_ED25519_SIGNATURE_DEP_A:
      id: 0x0C01
      short_desc: Deprecated
      desc: Deprecated.
      public: false
      replaced_by:
        - MSG_ECDSA_SIGNATURE
      fields:
        - signature:
            type: array
            fill: u8
            size: 64
            desc: ED25519 signature for messages.
        - fingerprint:
            type: array
            fill: u8
            size: 20
            desc: SHA-1 fingerprint of the associated certificate.
        - signed_messages:
            type: array
            fill: u32
            desc: CRCs of signed messages.

  - MSG_ED25519_SIGNATURE_DEP_B:
      id: 0x0C03
      short_desc: Deprecated
      desc: Deprecated.
      public: false
      replaced_by:
        - MSG_ECDSA_SIGNATURE
      fields:
        - stream_counter:
            type: u8
            desc: >
              Signature message counter. Zero indexed and incremented with each
              signature message.  The counter will not increment if this message
              was in response to an on demand request.  The counter will roll
              over after 256 messages. Upon connection, the value of the counter
              may not initially be zero.
        - on_demand_counter:
            type: u8
            desc: >
              On demand message counter. Zero indexed and incremented with each
              signature message sent in response to an on demand message. The
              counter will roll over after 256 messages.  Upon connection, the
              value of the counter may not initially be zero.
        - signature:
            type: array
            fill: u8
            size: 64
            desc: ED25519 signature for messages.
        - fingerprint:
            type: array
            fill: u8
            size: 20
            desc: SHA-1 fingerprint of the associated certificate.
        - signed_messages:
            type: array
            fill: u32
            desc: CRCs of signed messages.