picDakota VOEvent Tools V3.0.3 (September 2012)

Dakota is a cross-platform set of VOEvent tools which fully implement the VOEvent Transport protocol for subscriber, publisher, and broker-to-broker operations. Tools include a broker/receiver, a message sender, and a message checker/validator. The broker/receiver can be operated as an end-point receiver without any message distribution or as a full broker. It has support for sending received messages to a script or program, allowing you to start a pipeline with incoming VOEvent messages. Thus, the Dakota tools provide everything needed for receiving, publishing, and distributiing VOEvent messages.

The broker provides separate subscriber and publisher authentication via IP address white listing, as well as optional digital signature based authentication for publishers (only). In addition, it keeps a local copy of all VOEvent messages it receives and distributes, using this archive to prevent looping of messages received more than once. Finally, the broker can be configured to validate incoming VOEvent messages against the VOEvent 1.1 or 2.0 schema and reject messages that fail to validate. A special "lenient" validation mode is available (see Message Validation below) in which commonly occurring violations of the VOEvent 1.1 schema (only) are pre-patched and corrected before submitting to the parser/validator.

In addition, the broker/receiver can be configured to start an external program or shell script on receipt of a message from a publisher or a remote broker. This allows you to immediately process received messages using the program or script of your choice. Thus, you have the flexibility of using Dakota as a receiver, then later enabling it to act as a broker while still serving as a receiver for your needs.

The message sender sendvo is a command line tool which will deliver a VOEvent message from a file or a standard-in stream to a specified broker. The broker's response is sent to standard out. See Command Line Publishing Tool below. The message checker checkvo is a command line tool that performs a deep validation on a VOEvent message from a file or standard-in stream, and reports on its correctness. See Message Validation Tool below.

The Dakota tools are written in portable C# and thus can run on a variety of Windows and Linux platforms, as well as Mac OS X (Leopard or later), without rebuilding. Linux and Mac OS X require the Mono Framework 2.4 or later (2.10 is current) to be installed in order to run the tools. Some Linux flavors come with older versions of Mono (some very old); these cannot be used! On Windows (XP and later), the tools require the .NET Framework 3.5 SP1, which comes with Vista and Win7. Both 32-bit and 64-bit CPU operation is supported on Windows (Mono itself is 32-bit only). Optionally, the broker can use GnuPG for digital signature publisher authentication and the sender can digitally sign messages. The digital signature method is described in Digital Signatures in VOEvent Messages. GnuPG is free and is available for Windows, Linux, and Mac OS X. See Digital Signature Authentication below.

Finally, a command line publishing tool sendvo is included. This tool can be used to publish VOEvent XML messages to a broker. It restuns the ACK/NAK message from the broker on its standard out.

Prerequisites

The following must be installed on your system before using Dakota:

Optionally, for signature authentication, you need GnuPG. Most Linux distributions come with GnuPG. For more info see Digital Signature Authentication below.

Installation - Linux

It's assumed that you already unarchived the distribution somewhere, since you're reading this! You should have six binary files, three executable shell scripts, and two sub-directories data and doc. This should be done as root!

  1. Create a directory for Dakota wherever your system keeps local binaries, e.g. /usr/local/bin/dakota.
  2. Copy the files Dakota.exe, sendvo.exe, checkvo.exe, VOEvent.SimpleTcp.dll, VOEvent.Utility.Validator.dll, VOEvent.XmlSignatures.dll, checkvo, sendvo, and broker to this directory. The .exe files do not need execute permissions, remove execute provileges if set on these files. Set execute permissions on the three shell scripts checkvo, sendvo, and broker if needed.
  3. Add the directory created in (1) to your path. You can do this system wide via an /etc/profile.d script as shown below.
  4. Decide where you want to keep the broker's data (config files, logs, and archived messages), for example /usr/local/etc/dakota. Then add a new environment variable DAKOTA_DATA and set its value to the chosen directory. You can do this system wide (via an /etc/profile.d script) or use a shell script to launch Dakota and export that environment variable in that script. See the sample /etc/profile.d script below.
  5. Copy the entire contents of the data directory to the DAKOTA_DATA directory (typically /usr/local/etc/dakota). Don't copy the data directory itself, just the three directories contained within data.
  6. Set the Logs and Archive directories to world writeable if you plan to run the broker as other than root. The config files in Config shouldn't be writeable by other than a sudo or root user.
  7. Copy the entire contents of the doc directory wherever you want (e.g. /usr/local/etc/dakota/doc)
  8. Optional: If you want signature authentication, you need GnuPG. It's included with most Linux distributions. Run gpg from a shell once; this will create the keyfiles. See Digital Signature Authentication below.
  9. Edit your config files (in the DAKOTA_DATA directory's Config subdirectory, typically /usr/local/etc/dakota/Config) as described in Configuration below. You probably should do this as root so no one else can change them). If you plan to use GnuPG for digital signature authentication, be sure to configure the path to gpg.

Example /etc/profile.d script

You can set up your environment easily by creating a shell script in /etc/profile.d similar to that shown below. Suggested name for the script is dakota.sh:

PATH="/usr/local/bin/dakota:$PATH"
export PATH
DAKOTA_DATA="/usr/local/etc/dakota"
export DAKOTA_DATA

Installation - Mac OS X

Since you're reading this, you've already installed Dakota using the Dakota package. There are a couple of additional items that could not be automated:

  1. Optional: If you want signature authentication, install GnuPG. Run gpg from a shell once; this will create the keyfiles. See Digital Signature Authentication below.
  2. Edit your broker config files (in /Users/Shared/DakotaBroker/Config) as described in Configuration below. If you installed GnuPG for digital signature authentication, be sure to configure the path to gpg.

Uninstalling Dakota from Mac OS X

To uninstall Dakota:

  1. If you have Dakota running as a launchd daemon (see Running Dakota) kill the daemon.
  2. Remove Dakota.app from /Applications
  3. Remove the folder /Users/Shared/DakotaBroker
  4. Remove the folder /usr/local/libexec/dakota
  5. Remove /Library/LaunchDaemons/com.dc3.dakota.plist
  6. Remove /usr/local/bin/dakota, /usr/local/bin/sendvo, and /usr/local/bin/checkvo (shell scripts for running in Terminal).

Installation - Windows

It's assumed that you already unzipped the distribution somewhere, since you're reading this! You should have six binary files and two sub-directories data and doc.

  1. Create a folder C:\Program Files\Dakota and copy the six binaries Dakota.exe, sendvo.exe, checkvo.exe, VOEvent.SimpleTcp.dll, VOEvent.Utility.Validator.dll, and VOEvent.XmlSignatures.dllto this folder. You may wish to create a shortcut to Dakota.exe so it's easy to start, and add C:\Program Files\Dakota to your system PATH so that sendvo and checkvo can easily be started from a command line.
  2. Create a folder C:\Documents and Settings\All Users\Application Data\VOEvent Broker (on XP) or Program Data\VOEvent Broker (on Vista and Windows 7). You will need to have "Show Protected Operating System Files" enabled in order to see these areas on your disk.
  3. Copy the three folders under data (Archive, Config, and Logs) to the folder you created in step 2. These folders must be just below VOEvent Broker, do not copy the data folder itself.
  4. Optionally, copy the entire contents of the doc directory wherever you want. C:\Program Files\Dakota\doc is a reasonable choice.
  5. Optional: If you want signature authentication, install GnuPG. Run gpg from a shell once; this will create the keyfiles. See Digital Signature Authentication below.
  6. Edit your config files (in C:\Documents and Settings\All Users\Application Data\VOEvent Broker\Config as described in Configuration below. If you installed GnuPG for digital signature authentication, be sure to configure the path to gpg.
  7. Optional: To install Dakota as a System Service, open a shell to C:\Program Files\Dakota and type InstallUtil -i Dakota.exe. This utility is included in the Windows distribution of Dakota. Put it and its DLL in a directory that's known to the system PATH. Once installed as a service, configure, start, and stop the Dakota service with the services manager as usual. By default it is installed to start automatically at system startup.

Configuring the Dakota Broker/Receiver

The broker/receiver's config files are in the Config subdirectory of the data directory. The location varies between operating systems (see installation above). There are four config files, and they are described below. Each config file contains comments briefly describing its purpose and format. The '#' character starts a comment. Blank lines and comment lines are ignored. After a configuration change, the broker/receiver must be restarted.

Running as a VOEvent Receiver Only (client, subscriber)

To use the broker/receiver as a subscriber receiver only, in BrokerConfig.txt (see below) make the following settings:

Then start it up either in a shell or daemon. If running in a shell, the incoming VOEvent messages will be written to stdout. If running as a daemon, set up an external message handling program (see below). You can do this when running in a shell also.

Subscriber and Publisher Authentication (access control)

Dakota's broker provides for both IP address whitelist and digital signature methods of authentication (for access control) for both subscribers and publishers (separately). The SubscriberAuth and PublisherAuth settings in BrokerConfig.txt (see below) separately enable autheitication for subscribers and publishers, respectively. If authentication is enabled for a class of broker users, IP whitelisting is enabled/disabled by the presence/absence of the corresponding white list file. Digital signature authentication is enabled/disabled by the GnuPGPath config item. Setting it to "" will disable signature authentication. With these controls, you can choose the type(s) of authentication that your Dakota broker will do.

BrokerConfig.txt

This file configures the broker's basic parameters. Each live setting consists of a name, followed by one or more spaces and/or tabs, followed by a value. Values may be followed by spaces and/or tabs and a comment (beginning with '#'). The names and values are described below:

Name Description of Value
BrokerIVORN The IVORN that is used by the broker to identify itself in Transport messages. Typically of the form ivo://yyy.xxx/xxx.yyy.broker If you are running Dakota as a receiver-only, it should be something that identifies your organization but it should not look like the IVORN of a broker.
BrokerContact The email address of a contact person for the broker. This is included in the meta section of the broker's Transport messages.
LogLevel Controls the level of detail in the broker's logs. Legal values are 0 (Normal), 1 (Verbose), and 2 (Debug).
PublishPort The IP port on which the broker accepts incoming (ephemeral) connections from VOEvent publishers. The commonly used value is 8098. If you are running Dakota as a receiver-only, set this to 0 to disable incoming publish connections.
SubscribePort The IP port on which the broker accepts incoming (persistent) connections from VOEvent subscribers. The commonly used value is 8099. If you are running Dakota as a receiver-only, set this to 0 to disable incoming subscriber connections.
PublisherAuth A value of true means that the broker will require authentication of publishers by either IP address white listing (see PublisherWhiteList.txt below) or by digital signature (optional, only if GnuPG is installed and the publisher's public key is on its keyring). Any other value for PublisherAuth will disable publisher authentication. If PublisherWhiteList.txt is not present, only digital signature authentication will be used (if possible, see Digital Signature Authentication below). Not used if running as a receiver-only.
SubscriberAuth A value of true means that the broker will require authentication of subscribers by IP address white listing (see SubscriberWhiteList.txt below) or by digital signature (optional, only if GnuPG is installed and the subscriber's public key is on its keyring). Any other value for SubscriberAuth will disable subscriber authentication. If SubscriberWhiteList.txt is not present, only digital signature authentication will be used (if possible, see Digital Signature Authentication below). Not used if running as a receiver-only.
ValidationLevel Controls the level of VOEvent message schema validation. Legal values are 0 (None), 1 (Lenient), and 2 (Strict). See Message Validation below.
TestMessageInterval Sets the interval in minutes between broker-generated test messages. The default is 60 minutes. If set to 0, no test messages will be sent from the broker/receiver. This is useful for running in receiver-only mode.
LogKeepDays Sets the number of days for which log files are kept. Logs older than this are deleted at the beginning of each day.
ArchiveKeepDays Sets the number of days for which archived VOEvent messages are kept. Messages older than this are deleted at the beginning of each day. NOTE: The archive is used to prevent duplicate messages (received from other brokers) from being distributed. So you should set this to at least a few days (30 days is a good minimum value).
GnuPGPath Only needed if you want signature authentication and you are either are running as a Windows system service or GnuPG is not on your PATH. If present, this must be the complete path/name to the gpg executable. Set this to "" if you do not want to do digital signature authentication but GnoPg is installed on your system. If you don't it may be started via your PATH.
GnuPGKeyringPath Explicit path to GnuPG keyring folder. Not normally needed except when broker is running as a daemon on a multi-user system where a user creates and maintains keys under their account, yet the daemon runs under a different account (root, system). This tells the daemon/broker where to find the administrative user's keyring files.
SignKeyID ID of keypair used to sign broker test messages. Note: This keypair must have an embedded name that matches the broker IVORN!
SignKeyPassphrase Passphrase of keyring where broker's signing key is installed. Needed for broker to sign its test messages.
MsgHandlerPath Full path to the external received message handler program or script.
MsgHandlerArgs Argument(s) to be passed to the external message receiver program on its command line.

RemoteBrokers.txt

This file tells the broker about broker-to-broker connections, or if running as a receiver-only, it should list the broker from which you want to receive your VOEvent feed.. Specifically, it lists remote brokers to which your broker/receiver will connect as a subscriber. To complete a broker-to-broker connection the remote broker must also subscribe to your broker. Each live line of this file must list the IP address or domain name of the remote broker, immediately followed by a colon (':'), immediately followed by the subscriber port of the remote broker. For example:

estar6.astro.ex.ac.uk:8099    # eSTAR broker at Exeter
70.167.219.231:8099           # DC-3 Dreams, broker in Mesa, AZ (aka voevent.dc3.com)

PublisherWhiteList.txt

If present, this file contains a list of IP addresses from which clients are allowed to connect for publishing VOEvent messages. It is ignored if the PublisherAuth variable in BrokerConfig.txt is set to a value other than true. Each live line of this file must list a single IP address (which can contain wildcards, see Wildcards below). For example:

127.0.0.1
70.167.219.231

This is not used if running as a receiver-only.

SubscriberWhiteList.txt

If present, this file contains a list of IP addresses from which clients and remote brokers are allowed to connect to subscribe to VOEvent messages. It is ignored if the SubscriberAuth variable in BrokerConfig.txt is set to a value other than true. Each live line of this file must list a single IP address (which can contain wildcards, see Wildcards below). For example:

127.0.0.1
70.167.219.231

This is not used if running as a receiver-only

Wildcards

In the publisher and subscriber white list config files, you can list an IP address with one or more wildcards, signified by the '*' character. This allows your broker to support clients who are on dynamic IP addresses (typical of residential internet connections). The '*' cannot be embedded within an octet, it must replace the entire octet. For example:

70.167.219.*  # Any Ip within the range 70-167-219.1-70.167.219.254

Running the Broker

The broker is a command line program, but it can be set up to run at startup as a daemon on all three OS types, and it can run as a Finder Application on Mac OS X. On Linux and Mac OS X it runs under Mono, the cross-platform runtime for .NET languages. The broker takes no command line argument, nor does it read from standard-in. On startup, it writes a banner and a few lines of startup info to the console and that's all. Everything else is logged, see Logging below.

Running the broker on Linux

To run the broker on Linux from a shell:

$ broker

You can set up the broker to run as a daemon, but since this varies among Linux flavors, you'll have to set that up according to your particular flavor. The full command line to start the broker (assuming the default installation location) is:

$ mono /usr/local/bin/dakota/Dakota.exe

It does not require any command line options, but the daemon's environment must include the DAKOTA_DATA variable!

Running the broker on Mac OS X

The broker can run on Mac OS X as a Mac application, as a Linux-like command line program, or as a system daemon. In all cases, the broker's data files (logs, config files, and message archive) are kept in /Users/Shared/DakotaBroker. If run as an application (the Dakota icon, a butterfly), double-clicking its icon will start it but it will be completely invisible. To stop it, you'll need to use Terminal to kill it by its process ID. If you decide to run it as a Linux-like command line app, you can run it via Terminal like this:

$ dakota

If you want to run it as a system daemon, you can stop and start it with the launchctl tool, for example:

sudo launchctl load -w /Library/LaunchDaemons/com.dc3.dakota.plist

sudo launchctl unload -w /Library/LaunchDaemons/com.dc3.dakota.plist

To enable the broker at boot up, edit the file /Library/LaunchDaemons/com.dc3.dakota.plist and set the Disabled and RunAtLoad keys to false.

Running the the broker on Windows

On Windows, in a command shell, no "runner" is needed, for example (while in the Dakota program directory):

> Dakota		

You can install the broker as a Windows System Service. See Installation - Windows above for instructions on setting it up as a System Service.

External Message Handler Program

The broker can optionally run an external program to handle received messages. To enable this, you must configure the full path to the script or program as well as any command line argument(s) the program might need. The latter is mosly useful on Windows where there is no support for "magic" (e.g. shebang info) in a script. In this case the program would be the script "runner" (e.g., cscript.exe, perl.exe) and the argument is the full path to the script to be run. On Linux and Mac OS X, the program can be a shell/perl/Python/etc. script if it has execute permissions and contains the necessary magic (e.g. #!/bin/sh) at the beginning so the OS can execute it directly. Of course an executable program can also be used on all operating systems. See Configuration above.

On receipt of a message, it is placed on a queue for the external handler. A separate thread dequeues each received message and feeds it to the external program or script via its standard input. It then waits (for up to 30 seconds) for the external program to exit. At this point it loops back and dequeues the next received message if one exists. This logic assures that no more than one copy of the external handler is spawned at a time. It also serializes the handling of incoming messages. Thus, you should try to keep the time needed to run your external program down to a minimum. Certainly, 30 seconds (the time limit) is way too long.

Message Validation

The broker includes a VOEvent message validator that can optionally be used to schema-validate messages against the Sky Event Reporting Metadata (VOEvent) 1.1 schema or Sky Event Reporting Metadata (VOEvent) 2.0 schema and reject messages from publishers and remote brokers which do not conform to the relevant schema (as determined from the version in the VOEvent XML).

Note that the Dakota Tools validator does not implement the entire Space-Time Coordinate Metadata (STC) schema that is embedded into VOEvent 1.1. Instead, the author created a schema that implements the currently used subset of STC, and which can be compiled into an object model by automated parser generators such as Liquid and JAXB. In addition, the author's schema resolves missing object references in the VOEvent 1.1 What section, allowing that section to be parsed and validated. For more information on this see the author's IVOA Note Reflections on VOEvent 1.1 and the Real World.

Lenient vs Strict Validation

As described in the author's IVOA Note Reflections on VOEvent 1.1 and the Real World, VOEvent 1.1 messages from several sources may contain constructions that violate the Sky Event Reporting Metadata (VOEvent) 1.1 schema. The Dakota Tools message validator can be configured to pre-patch incoming VOEvent messages before sending them to the parser/validator, allowing these common but illegal messages to pass validation. The distributed messages (after validation) are not altered by the broker.

VOEvent Message Archive

The broker saves copies of all VOEvent messages it receives from publishers and remote brokers. The messages are stored in a directory tree below the broker's Archive folder. The directory structure mirrors the paths in the message IVORNs. Messages are kept in the archive for the configured ArchiveKeepDays in BrokerConfig.txt. Messages older than that are deleted daily. It is vital that you do not delete "recent" messages from this archive, as Dakota uses the archive to prevent looping of messages between brokers. What is meant by "old" and "recent" is unclear, the author has seen messages over five days old reappear! Seemingly, 30 days is a good minimum amount of time to keep messages in the archive.

Logging

Dakota logs its activity to files in its Logs folder. Logs are rotated daily (at local midnight), and logs older than the configured LogKeepDays in BrokerConfig.txt are deleted.

The level of detail in its logs is controlled by the LogLevel variable in BrokerConfig.txt. A value of 2 (Debug) will result in potentially huge logs, with all message traffic and low-level Transport and TCP operations appearing in the log.

In addition, on Windows, Dakota outputs its log messages to the system trace receiver. You can watch this log output in real time, even when Dakota is running as a system service and/or on a remote system, via the free DebugView utility. DebugView 4.765 is included with Dakota.

Digital Signature Authentication

The Dakota broker can authenticate publishers via digital signature as an alternative to IP address white listing. This method was chosen in preference to a username/password scheme (of which there are many, with varying levels of security). Digital signature authentication is high-strength, encrypted, and as a bonus it provides verification of the integrity of the message itself. It uses the freely available GnuPG tool which is supported on a wide variety of platforms.

Publishers wishing to authenticate via Dakota's digital signature authentication must digitally sign their outgoing messages with a keypair whose embedded name matches their Author IVORN. In addition, the publisher's public key must be on the keyring of GnuPG that the broker uses. For more details see Digital Signatures in VOEvent Messages.

Setup of GnuPG for Use by the Broker

This installation guide is brief, it's beyond the scope of this document to explain how to use the command line, add things to your path, etc. Follow the directions for installing GnuPG on your operating system. If you need help contact the author at rdenny@dc3.com. The GNU Privacy Handbook document that comes with GnuPG is invaluable, as is the web page GnuPG Command Reference.

Most Linux distributions come with GnuPG or GnuPG2 pre-installed. Either will do. If you already have GnuPG 2 on your system, Dakota can use it, but since Dakota looks for an executable named gpg (or gpg.exe on Windows) you may have to create a symlink named gpg which points to gpg2 (on Windows create a shortcut to gpg2.exe and name it gpg.exe).

If you don't have GnuPG installed on your system, install GnuPG 1.4.9. This is a much smaller and simpler package compared to GnuPG 2, yet it has everything needed for verifying signatures on VOEvent messages.

Before doing anything else, make sure that GnuPG is accessible from your shell (console/cmd window on Windows). Open a shell and try to run it:

$ gpg --version
 gpg (GnuPG) 1.4.9
 Copyright (C) 2007 Free Software Foundation, Inc.
 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
 This is free software: you are free to change and redistribute it.
 There is NO WARRANTY, to the extent permitted by law.
 Home: depends on your operating system
 Supported algorithms:
 Pubkey: RSA, RSA-E, RSA-S, ELG-E, DSA
 Cipher: 3DES, CAST5, BLOWFISH, AES, AES192, AES256, TWOFISH
 Hash: MD5, SHA1, RIPEMD160, SHA256, SHA384, SHA512, SHA224
 Compression: Uncompressed, ZIP, ZLIB, BZIP2
$

If this succeeds, then the broker will be able to find the GnuPG executable. If not, re-check your installation instructions, making sure that the GnuPG executable is accessible via a directory on your system's path environment variable. Next, make sure that GnuPG has done its one time initialization of its keyring, etc.

$ gpg --list-keys
 gpg: keyring ~/gnupg/pubring.gpg created
 gpg: ~/gnupg/trustdb.gpg: trustdb created
$

Before a publisher can be authenticated, you must have their public key in your GnuPG keyring. It is the presence of this key that allows them to publish with encrypted authentication (and without being bound to an IP address). Normally you will get their public key as an ASCII-armored (.asc) file via email, etc. See Importing Author Public Keys below. The name on the key must match the publisher's author IVORN.

It is not necessary to generate a signing keypair for Dakota, since Dakota never signs messages itself. All it needs is the public key of each publisher that you want to allow to use your Dakota broker for publishing via digital signature authentication.

Exporting Public Keys (for Publishers)

A publisher wishing to use your Dakota broker must give you a copy of their public key. Their software should provide instructions on how to generate their signing keypair and export the public key. See the instructions in Command Line Publishing Tool below. . The name of the key must match the publisher's Author IVORN. Here is the command line that a publisher would use to export their public key:

$ gpg --output MyVOeventPubKey.asc --armor --export ivo://xxx.yyy/abcd
		

The --armor option creates an "ASCII-armored" file that can be easily mailed in a plain-text email. Here's what the contents of an ASCII-armored file looks like:

-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: GnuPG v1.4.9 (MingW32)

mQGiBEnAXrIRBACF41Bq+dc2jsCGDjE8mR7YGqDiOXNnGWu1I3kXo62USYdHUnr9
3tXgktKeiZtTnC6Le8URDomflrAxgKXVsCRBerEC3PrV7NZxwQk8MFi069zDwFeR
0w2I+hEHNpv/rvWmv18awswF4o2vF8TN6goLkr272YL+GA5PL39SjDwQLwCgiJnk
xxIQ7sE5sk6UcgelH//gJKcD/3G0h+wMs8g5nbchiKJOokB3R8gQMzVCLOdqguzV
P/+KXMf/PbG4b/sK6p+NbbDmqlzZinohX45185A9INhiffCPKVrBBKCmKqAQHcZx
/SyzqQtNl8kcZkZEX/8jSOulpTPf1q09eDmrvLHBgGmIpkj9iciHWe3Ht02LpRQo
1ZMpA/9UmjtvpBW6YNlOnOuGUDAKEQBGiJM+YiH50SYMgaUs8xDylu9BAGKMOXgg
Gey4NsUBgu9aibGQkD/GgX7GWtuajy30ArRxr2oOeih5eaYWwvCWs3/BqNvrPHGa
ZiIziJAu3mcC1d9uyadvFgC10LlSMLv1Pxq4QsiwkhLnZzLC1rQSaXZvOi8vY29t
LmRjMy9hYmNkiGAEExECACAFAknAXrICGwMGCwkIBwMCBBUCCAMEFgIDAQIeAQIX
gAAKCRAf8jYAqUZ9JO4bAJ9PQO9Pm2woRloHVMdqBJ0DxvzMvwCfRdnH5L1kjhNO
dHLYvxliCVGkHBm5Ag0EScBeshAIAMhC9L0hBb3edbWT3gJmy37D49BI0RCnESiC
b0d5Se43gi/voK2dYNlW+HKDf3wkL3pzSRpbxApW3zKb8g4Qd2rofJscxCNEJyjy
nBuPVzdsupjsc6iLev4dTrNnxGJqBUebXNvPV0j1LCospc7TO83Ci6XxdG4/KFM8
pI7VU2Gs+MllhmKaof2AyvD+1GN02cvGWpwzvThEmQ8yFi5Xcul2JG538ogwyVeK
FBTAE7sPONzsDroRRv5xBMpqYuJTIVAcuD9pwr8sGH4JqQ/mATfzXGTNI8/thSUq
oMJvs5V7oTx19d9XrpRAbC691tMVkmUD461M8Y0W5l2GAL4B5QsAAwUIAK1N3HZD
5IV75twlqKW8MWqhjpXL3WtNkZQ4IgiebLx64jQDalCQDWPIaP3Wv8boDur3BVQe
eF/8eCQRhS0AwYQ1PVMTT7vKZ91NO4c4hg/zlZOgNpK4uu2h0XZnQoGCLct52hcK
85BQbHkWS5ty3m0mXs7a6yfvdTgrTfqe+jxId8HsLXU3mi8hfSjIT8f5r88MDRqg
vuN3ExWOW7HhaCtSqvYdQ8MfgCyT8mcPwU5CDnV3auuizNnPDVYZm7aTx+eW2XfW
ABj9LIl+3mH6VeBSFIgo27Gqe+9FTmBk+7KI8JjC7WaTyLmp7L6GfRuo5aCgjvUP
vE8rjRpo5p9rdFKISQQYEQIACQUCScBesgIbDAAKCRAf8jYAqUZ9JIOpAJ4kjfpX
mmanfI0QTiprHB7ve54AuACbBfGEbJcLu+ADRcrSoOCKduswdcc=
=+lRB
-----END PGP PUBLIC KEY BLOCK-----

The publisher provides this key to you (email, etc.).

Importing Author Public Keys

In order for Dakota to authenticate a publisher via digital signature, you must put the publisher's public key into the keyring of the GnuPG on your system (that's running Dakota). Assuming the publisher exported their public key as described in the preceding section, you simply save it to a file and import it into your keyring like this:

$ gpg --import SomePublishersPubKey.asc

Once it is imported, take a look at it with the gpg --list-keys command and make sure it is what you expected from that publisher. The name on the key must match the publisher's author IVORN.

Routine Use

Be sure that the PublisherAuth variable in BrokerConfig.txt is set to true so that Dakota will require publisher authentication. There's nothing else to do. Dakota will accept a message from a publisher if it is signed by that publisher, if the key is named correctly (matches the message's Author IVORN), and if the message has not been altered after being signed.

Dakota Command Line Publishing Tool

Dakota includes a command line tool sendvo for publishing VOEvent messages. sendvo sends (publishes) a VOEvent message (XML) to the VOEvent backbone via a broker's publish port. The broker's response (a Transport XML message) is written to standard out. Shell run syntax is similar to that for the broker:

Linux: mono sendvo

Mac OS X: sendvo

Windows: sendvo

Usage: sendvo [OPTION]... [FILE] (file quoted if contains spaces)

Options ('/' form only on Windows):

-b, /b, --broker=domain|IP Broker IP address or domain name, default is voevent.dc3.com
-h, /h, --help Show this help info
-p, /p, --port=nnnn Broker publish port, default is 8098
-s, /s, --sign=keyID:pass Sign the VOEvent message with the given (required) GPG key ID and password (see below)
-v, /v, --version Show just the program name and version
-x, /x, --validate Schema-validate the VOEvent message per VOEvent 1.1

Option values may be delimited by space, '=' (shown above), or ':'.

If [FILE] (a VOEvent message file) is not given, the VOEvent message is read from standard input. Errors are written to standard error and the program exits with non-zero status.

Timestamp Substitution

The publishing tool can perform a date/time substitution in the message it is sending. If it finds _DAT_ anywhere in the message, it will substitute the current date/time in ISO 8601 format, UTC, as required by the VOEvent specification. This is most useful for putting a date/time into the <TimeStamp> element of the mesage when publishing it.

Generating a Signing Keypair

Here's how to generate your VOEvent keypair. It is vital that the User-ID be exactly equal to your Author IVORN. Take the default DSA/Elgamal type and the default 2048 bit size and don't bother with expiry. Enter your Author IVORN at the Real name: prompt as shown. Leave the Email and Comment fields blank! For example, if your IVO Identity is com.dc3/abcd, your Author IVORN will be ivo://com.dc3/abcd. Here is an example dialog with GnuPG for generating this key:
> gpg --gen-key
gpg (GnuPG) 1.4.8; Copyright (C) 2007 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Please select what kind of key you want:
   (1) DSA and Elgamal (default)
   (2) DSA (sign only)
   (5) RSA (sign only)
Your selection? 1
DSA keypair will have 1024 bits.
ELG-E keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048)
Requested keysize is 2048 bits
Please specify how long the key should be valid.
      0  = key does not expire
      n  = key expires in n days
      nw = key expires in n weeks
      nm = key expires in n months
      ny = key expires in n years
Key is valid for? (0) 0
Key does not expire at all
Is this correct? (y/N) y

You need a user ID to identify your key; the software constructs the user ID
from the Real Name, Comment and Email Address in this form:
    "Heinrich Heine (Der Dichter) "

Real name: ivo://com.dc3/abcd
Email address:
Comment:
You selected this USER-ID:
    "ivo://com.dc3/abcd"

Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
You need a Passphrase to protect your secret key.
[the passphrase is requested twice here and erased from the shell display]
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
++++++++++...++++++++++++++++++++++++++++++++++++++++++++++++++.++++++++++++++++++++++++++++++++++++
++++..+++++..++++++++++++++++++++.++++++++++>+++++.<+++++................+++++
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
++++++++++++++++++++++++++++++++++++++++.++++++++++.+++++..++++++++++++++++++++++++++++++++++++++++.
++++++++++++++++++++.+++++.+++++..++++++++++....++++++++++>.+++++.+++++>+++++>+++++..............<++
+++...>+++++<.+++++......+++++^^^^
gpg: key FE9654C5 marked as ultimately trusted
public and secret key created and signed.

gpg: checking the trustdb
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
gpg: depth: 0  valid:   4  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 4u
pub   1024D/FE9654C5 2009-03-17
      Key fingerprint = 9855 AEB7 06E8 E5ED B840  47F6 28AD 96B0 FE96 54C5
uid                  ivo://com.dc3/abcd
sub   2048g/8D2598CD 2009-03-17

>
At this point you can export it to ASCII armored format to give to the broker operator(s) as described above in Exporting Public Keys.

Dakota Command Line Message Validation Tool

Dakota includes a command line tool checkvo for validating VOEvent messages. checkvo reads a VOEvent message from a file or standard in and performs a deep schema-validation on the XML. If errors are found they are written to standard error, and the tool exits with non-zero status. If the validation is successful, a success message is written to standard output and the tool exist with succeeded (0) status. Shell run syntax is similar to that for the broker:

Linux: mono checkvo

Mac OS X: checkvo

Windows: checkvo

Usage: checkvo [OPTION]... [FILE] (file quoted if contains spaces)

Options ('/' form only on Windows):

-h, /h, --help Show this help info
-l, /l, --lenient Lenient validation: accept commonly occurring violations
-v, /v, --version Show just the program name and version

If [FILE] (a VOEvent message file) is not given, the VOEvent message is read from standard input. Errors are written to standard error and the program exits with non-zero status.

Administrivia

As shown below, Dakota is licensed as open source. Sources are available on request from the author at rdenny@dc3.com.