# Message Authenticator v0.92_022525. Visit https://kf7mix.com/ for information
# Special thanks to KD0QYN, KN4AM, and everyone else who contributed
#
# MIT License, Copyright 2025 Joseph D Lyman KF7MIX --- Permission is hereby granted,  free of charge, to any person obtaining a copy of this software and associated documentation files
# (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
# of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:  The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.  The Software IS PROVIDED "AS IS",  WITHOUT WARRANTY OF ANY KIND,  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
# WARRANTIES  OF  MERCHANTABILITY,  FITNESS OR A PARTICULAR PURPOSE AND  NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR  COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,  DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

# Readme

Message Authenticator is a very simple piece of software that enables amateur radio operators to
validate the integrity and authenticity of a message transmitted over the air. This readme provides
a brief overview of the method, along with instructions on how to use the software.

## Overview

At times, you may wish to have reasonable assurance that the message you're receiving is being
received correctly, and that it was in fact sent by the reported sender. You can do this by
exchanging a key off the air, and using this software to validate messages manually.

## Installation

1. Download and unpack the software in the location where you'd like to use it.
2. Edit the msgauth.cfg file with a text editor.
    * The first line is the theme style, light or dark
    * The second line is your callsign
    * The third line is your default key (see below)
    * You may optionally add additional keys, one per line

## Creating a Key

A key is a random string of characters in the recommended set A-Z and 0-9, with a recommended
minimum length of 25 characters. Longer keys may be more secure to an extent. Additional UTF-8
characters may be used if desired and supported by your system.

Your keys should be unique, random, and should not be based on well know sequences, numbers in
order, dates, phone numbers, or anything else that could be easily guessed. Prepending known
sequences as a label is certainly secure and acceptable.

Never send your key over the air; in order for it to be secure, it should be communicated in a
secure or at least semi-secure way. In-person, secure app, telephone, or secure email
(gpg, pgp, protonmail, etc) are all suitable methods.

## Using the Application

The application is split into three parts: a common entry area at the top, and two tabs at the
bottom. One tab is for signing a message, and one is for validating a signed message.

    To sign a message: Enter all of the information (either using the entry boxes or the alternate
    single line entry), select a key, decide if you want to include the optional datecode, and click
    "Sign". The resulting CRC signature (and optional datecode) is added to your message before
    transmission.

    To validate a message: Select the key associated with the source station. Enter the message
    plus target and source, exactly as received. Enter the CRC in the box provided. Click "Validate"
    to see if the CRC passes. If a datecode is detected, it will be automatically decoded.

    NOTE: The program will standardize input to remove duplicate spaces, control characters, and
    trim whitespace.

### Single Line Entry

The alternate single line entry requires a specific format. That format is:

    <from callsign>:<space><to callsign or group><space><message text>

For example:

    KF7MIX: @MYGRP STATUS 1112 GREEN

If you'd like to see how this is formed based on your entry boxes, simply fill in the entry boxes
and then click the sliding switch; the single line will be filled in and you will see the correct
format to use.

## Things to Consider

* You may use a key shorter than 25 characters (any length works), but it will be easier to crack.
* You may use a key longer than 25 characters to increase security, to an extent.
* No system will substitute for good operating procedures.
* Using sets of keys, rotated per your group procedures, may help increase security.
* Keys should be updated regularly.
* Consider using different keys for exercises and real situations.
* The datecode is a good addition if you are sending repetitive data (such as net checkins) or data
  that you feel may be re-transmitted by a 3rd party (parrot).
* Operators may optionally use any UTF-8 characters in their keys, if their systems are configured
  to handle UTF-8 and if they are able to save their .cfg file correctly in a UTF-8 format.