Ninfacyzga-01 Manual

1.2.1 Hardware

1. Raspberry Pi Zero W
   

   See the OEM webpage for this product.

2. PiZ UpTime 2.0
   

   See the OEM webpage for this product.

1.2.2 Software

1. Narrative
   

   bkgpslog populates a 60-second buffer with NMEA data from gpsd via gpspipe. This buffer is used by gpsbabel to produce GPX and KML versions of the buffer. All 3 buffers are then comprssed with gzip, encrypted with age, and then written to disk.

1.2.3 Output

1. File Formats
   
   1. NMEA
      

      See the Wikipedia page for this.

   2. GPX
      

      See the Wikipedia page for this. WGS84 is the datum used.

   3. KML
      

      See the Wikipedia page for this. WGS84 is the datum used.

2. Encryption Method
   

   Files produced by the bkgpslog script are encrypted against a set of public keys using age, a simple command line encryption tool selected over gpg because of age's deliberate lack of configurability.

   The public keys are bech32 strings supplied as options to bkgpslog when called. The secret key should NOT be stored in Ninfacyzga-01.

   If a key pair was generated using age-keygen, then it is an X25519 key pair. See the age Version 1 specification.

   An ssh-rsa or ssh-ed25519 SSH public key string may be used instead of the bech32 public key string produced by age-keygen for convenience.

   Help information for age is available by running $ age --help.

   1. Encryption Commands
      

      Files may be encrypted to several recipients using a command similar to:

      timeout "60s" gpspipe -r | gpsbabel -i nmea -f - -o gpx -F | age \
      -r age1kza7pfshy7xwygf9349zgmk7x53mquvedgw9r98qwyyqhssh830qqjzlsw \
      -r age1ce3pvzrqfcn2pc6zqzglc8ac8yjk3fzukpy08cesqjjwns53xywqmaq7xw \
      -r age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5 \
      > location.gpx.age
      

      In this example, the strings beginning with age1... are bech32-formatted public key strings.

   2. Decryption Commands
      

      Files may be decrypted using a command similar to:

      cat location.gpx.age | age -d -i key.txt > location.gpx
      

      The version of age used to perform the encryption

1.3.1 Initial Startup

1. Physical Setup
   

   BerryGPS-IMU must be electrically connected to the correct pins on the GPIO header of a Raspberry Pi Zero W.

   Optional: stack together with PiZ Uptime 2.0 module. No GPIO pins conflict so a simple stacking and soldering with long header pins is possible.

2. Software Setup
   
   1. Install Executables
      

      Install Raspbian 10 Buster onto an SD card image. See the Raspberry Pi Foundation installation instructions. Configure WiFi to permit log file transfer. Configure SSH to permit remote administration via the command line interface.

      Make sure to install the unattended-upgrades package to make sure the latest security patches for packages are installed. See this page for a description of how unattended-upgrades works.

      Install gpsd, gpspipe, git, and this repository for location logging capability.

      Install syncthing for log file transfer capability.

      Place age binary (the one compiled for ARM CPU architecture for Linux) in $HOME/.local/bin.

   2. Disable Swap File
      

      Since standard Raspbian 10 install involves copying unencrypted file system image to SD card which is mounted by the Raspberry Pi, system memory may be written to disk in the form of a Swap file as described here. In order to reduce the chance that location log data is ever written to disk, swap file functionality must be disabled.

      To view the status of the swap file in Raspbian 10, run free -m:

      pi@ninfacyzga-01:~$ free -m
                    total        used        free      shared  buff/cache   available
      Mem:            432          86          36          21         309         268
      Swap:            99           0          99
      

      The swap file may be disabled by:

      pi@ninfacyzga-01:~$ sudo dphys-swapfile swapoff
      pi@ninfacyzga-01:~$ sudo dphys-swapfile uninstall
      pi@ninfacyzga-01:~$ sudo update-rc.d dphys-swapfile remove
      pi@ninfacyzga-01:~$ free -m
                    total        used        free      shared  buff/cache   available
      Mem:            432          96          33          22         302         258
      Swap:             0           0           0
      

   3. Automatic Start Configuration
      

      Edit the user cron job list with $ crontab -e to add the following lines:

      0 * * * * /bin/bash ~/bkgpslog --output ~/dir
      
      @reboot /bin/bash ~/bkgpslog --output ~/dir
      

      The first line will run bkgpslog at the start of every hour and save output files to the dir directory in your home folder.

      The second line will run bkgpslog when the system starts up.

      /bin/bash tells cron to run bkgpslog with Bash.

      If encryption and compression are required, then the appropriate options must be added. The lines that must be added via $ crontab -e may resemble:

      0 * * * * /bin/bash ~/bkgpslog -c -e -r age1z2...qkv6p -o ~/dir
      
      @reboot /bin/bash ~/bkgpslog -c -e -r age1z2...qkv6p -o ~/dir
      

      The age1z2...qkv6p is an age public key string. Please see the Key Generation section for an explanation.

      The options are:

      -c : tells bkgpslog to compress output
      -e : tells bkgpslog log to encrypt output
      -r : tells bkgpslog to interpret the next argument as a pubkey string
      -o : tells bkgpslog to write output files to the directory represented
             by the next argument
      
      

   4. Log Transfer Configuration
      

      Log files may be shared to other machines via syncthing. See this manual for how to set up a shared folder and add Ninfacyzga-01 as a device. Syncthing's directory synchronization capability allows a remote machine to delete files from Ninfacyzga-01 by deleting from the shared folder that they both share.

      When log files are removed from Ninfacyzga-01 is not within the scope of this document.

   5. Key Generation
      

      An age encryption key may be generated like so:

      $ umask          # Gets current umask
      0022             # Note: This is the default umask for Raspbian 10
      $ umask 066      # Sets umask so key.txt will have no permissions except for owner (you)
      $ umask          # Confirm umask set to 066
      0066
      $ age-keygen > key.txt
      Public key: age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5
      $ ls -al key.txt
      -rw------- 1 baltakatei baltakatei 184 Jun 29 18:28 key.txt
      $ umask 0022     # Return umask to default value
      $ umask          
      0022
      

      The resulting public/private keypair data looks like:

      $ cat key.txt
      # created: 2020-06-29T18:01:56Z
      # public key: age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5
      AGE-SECRET-KEY-1NEUU5U2XGZGL9UYWNPU5DL99TGJJHFSN4F2E2WCCSDJJ6L5ZMLESNTVTU0
      

      The file key.txt is not password-protected by default and should be secured like an SSH public key should. The $ umask 066 command run before the $ age-keygen > key.txt command ensures key.txt will not be readable, writeable, or executable to anyone except the owner (you).

1.3.2 Normal Startup

1.3.3 Normal Operation

1. Log Transfer
   

   Log files may be transferred by use of syncthing shared folders.

2. Automatic Updates
   

   The automatic-upgrades package, if installed, should automatically install security patches to packages installed via apt.

1.3.4 Normal Shutdown

$ sudo shutdown -r 0

1.3.5 Unscheduled Shutdown

1.3.6 End of Life Disposal