Firewall Settings

The information provided below is for typical/majority environments. It is possible that highly secure or complex or atypical environments will have needs for exceptions that are not required in most use cases and therefore may not be listed in this document. It is left to the individual customer to consider the information we provide in context of their infrastructure and consult with Sassafras technical staff as needed with any concerns or questions.

Port 19283 has been registered with the IANA (Internet Assigned Numbers Authority) for use by the KeyServer process so that enhanced security can be enforced with explicit firewall routing rules that avoid conflict with other services.

Network routing equipment and wireless routing devices typically include firewall features that can be configured to forward or block network packets. Modern operating systems also include "personal firewall" features that can be configured to block or forward packets from the individual computer. Many third party "security" products may also include firewall features (e.g. Norton Personal Firewall, ZoneAlarm, etc).

Firewall rules must be configured on the KeyServer host to allow communication from KeyAccess clients and from KeyConfigure, the administrative console. Response packets from KeyServer to KeyAccess clients will generally be allowed by default client settings, but connection timeouts for personal firewalls, wireless routers, and NAT routers can be changed to achieve increased efficiency.

Outbound Considerations

The ks-prs process on the KeyServer host needs to communicate with https://prs.sassafras.com (the PRS server) (and optionally also http), either directly or through a proxy in order to receive product definition updates. This is also needed on any stand alone KeyReporter server to allow Software icons to be downloaded.

Any KeyReporter service, be it on the KeyServer or stand alone, also need to contact *.openstreetmap.org to download map tiles for geographic Maps if you use that feature. Without access, maps will just be gray fields. Specifically, this would include a.tile.openstreetmap.org, b.tile.openstreetmap.org, and c.tile.openstreetmap.org. Note that these are DNS cnames against dualstack.osff2.map.fastly.net, so in rare cases you may need to allow the latter as well (OpenDNS filtering proved an issue for one site).

The KeyReporter/KeyServer host will need to be able to reach https://www.sassafras.com and linodeobjects.com if you use the Client Self Update feature. This is because the server has to reach our website to see if a new version is available and then redirect to our hosting partner to download it to the local storage.

The KeyServer host will reach out to ecb.europa.eu to obtain current currency conversion rates, specifically http://www.ecb.europa.eu/stats/eurofxref/eurofxref-hist.xml. You can allow this, or block if you will not need conversion rates for Purchase records/ will set the values manually if needed.

In addition to the below ports, KeyConfigure uses standard https or http queries directed to KeyReporter on the KeyServer host (for listing saved reports), and also to prs.sassafras.com (when querying the PRS server for new product definitions or searches), and to www.sassafras.com (to check for new versions or look for Admin Scripts). This means any computer using the admin application will need to reach these addresses or it will not be able to perform the related function(s).

Ports

The KeyServer process listens for incoming UDP and TCP packets on port 19283. Response packets are sent from port 19283 back to the requesting address and port (which can be random). Port 19283 is registered through ICANN to Sassafras Software. This default port for KeyServer can be customized, but this is not recommended.

  • UDP port 19283
    • traditional receipt of packets from clients (KeyAccess) when using just the server FQDN for the host address
    • support of admin (KeyConfigure) connections (optional but encouraged)
    • receipt of packets from Shadows (if any are installed)
  • TCP port 19283
    • communication of admin (KeyConfigure) connections
    • support of report queries (from KeyConfigure, KeyReporter, any external SQL reporting tools)


A Web Service process (installed with KeyServer, optionally installed on a separate host via standalone KeyReporter) listens for incoming http, https, and KeyConfigure requests. The outgoing connection to KeyServer targets the standard KeyServer tcp port (see above) using a dynamic source port.

  • TCP port 80 (this default port for http can be customized)
    • receipt of packets from any web browser and from KeyConfigure
    • receipt of packets if using an http (not recommended) address for the Hostname in KeyAccess settings (7.7 and later)
  • TCP port 443 (this default port for https can be customized)
    • receipt of secure packets from any web browser and from KeyConfigure
    • receipt of secure packets if using an https address for the Hostname in KeyAccess settings (7.7 and later)


A KeyShadow process (e.g. the KeyServer component running with a shadow.lic license certificate) uses UDP port 19315 (instead of 19283). Allowing TCP traffic on 19315 is unnecessary. As noted above, the Shadow talks to the KeyServer on UDP 19283 from a random port in the same way clients communicate to the server.

  • UDP port 19315
    • open on the KeyShadow host address for receipt of packets from clients
    • open on the KeyShadow host address for receipt of packets from KeyConfigure (when the Shadows window is used to check shadow status)


The KeyAccess process initiates communication to the KeyServer process on a dynamically allocated UDP port (with destination port 19283). When the KeyServer is unreachable and the client has previously obtained a "shadow hint list" of shadow addresses, a dynamic port is used to communicate to a KeyShadow (with destination port 19315).

KeyConfigure initiates admin communication to the KeyServer process on dynamically allocated TCP and UDP ports (with destination UDP 19283 and TCP 19283 at the KeyServer host address). A dynamic UDP port is also used to interrogate shadows (if any) for status information (with destination port UDP 19315). KeyConfigure sends to https port 443 (optionally, http port 80) to search for product definitions from prs.sassafras.com. KeyConfigure sends to www.sassafras.com using http port 80 to check for newer versions of the various Sassafras Software components. Communication from KeyConfigure to the KeyReporter host (for listing saved reports) sends to a configured address and port – port 80 is the default, but KeyReporter can be set up to listen on a custom port instead.

If http access to sassafras.com from the computer running KeyConfigure is blocked, KeyConfigure's version check feature should be turned off (from the Preferences -> Updates Menu) in order to avoid an excessive delay when launching. Note: if traffic from the KeyServer host is blocked from reaching prs.sassafras.com, the automatic product recognition service cannot work. But if KeyConfigure can connect to KeyServer from a different computer that is not blocked, its manual "Find Product Definitions" menu can still be used to add new definitions to KeyServer's Products table.

ksODBC is an ODBC driver component that can be installed on any Windows or Macintosh computer in order to support third party SQL reporting tools (e.g. Crystal Reports, MS Access, FileMaker, etc.). When an external reporting tool is used, ksODBC initiates communication to the KeyServer process on a dynamically allocated TCP port (with destination port 19283).

ks-prs is a helper utility sub launched on the KeyServer host whenever the Product Recognition Service (PRS) is enabled. It will initiate an https connection (or optionally, http) to the Sassafras Software PRS server at prs.sassafras.com. It is highly recommended this be allowed so several automated features can work when it comes to product discovery and tracking. However, this can be disabled in KeyConfigure -> Config -> General Settings -> PRS.

The KeyReporter process initiates a connection to the KeyServer process on dynamically allocated port with destination port TCP 19283 on the KeyServer host. KeyReporter listens for web browser connections on the standard http port 80 and standard https port 443 to provide the Web UI. If KeyReporter is hosted on a computer that is already running a web server, this default must be changed as explained in the KeyReporter Setup documentation. Connections from KeyConfigure for access to archived reports are accepted on this same port.

If the KeyServer process is specially configured to use external authentication services, to export its databases, or to backup onto a remote volume, additional dynamic ports will be opened to support these underlying network services. You may have to configure some firewall rules according to the documentation for each of these services.

The "Send KeyServer Status/Warning Messages" option (as configured from the Alerts & Status dialog in the Config menu) initiates packets from KeyServer (and KeyShadows, if any) to a specified mail server address using TCP destination port 25 from a dynamic source port.

Firewall Configuration Rules

  1. All firewalls between KeyServer and its clients (and between KeyServer and KeyShadow hosts, if any) must be configured to allow traffic on UDP port 19283 into the KeyServer host address. KeyServer will send and receive packets on port 19283, while clients will send and receive packets on a dynamically assigned port.
  2. All firewalls between KeyShadow and its clients must be configured to allow traffic on UDP port 19315 into the KeyShadow host address(es). KeyShadow will send and receive packets on port 19283, while clients will send and receive packets on a dynamically assigned port.
  3. All firewalls between the admin computer running KeyConfigure and KeyServer must be configured to allow traffic on both UDP and TCP port 19283 into the KeyServer host address. KeyServer will send and receive packets on port 19283, while KeyConfigure will send and receive packets on a dynamically assigned port.
  4. All firewalls between KeyServer and prs.sassafras.com must be configured to allow https port 443 (or optionally, http port 80) connections initiated from the KeyServer computer in order to support the Product Recognition Service.
  5. Whenever KeyConfigure's product definition search feature is needed, standard https communication using port 443 (optionally, http port 80) must be allowed to prs.sassafras.com. The version check and online documentation features use http port 80 to query www.sassafras.com.
  6. Additional rules for optional features: external authentication, data export, backup, and status e-mail may require firewall configuration rules to allow specific outgoing tcp target addresses and ports.

Windows Firewall

Windows Firewall service on supported versions is enabled by default. In addition to ignoring most unsolicited incoming packets, the default firewall configuration will also ignore "late" UDP response packets from any address unless the response is received within 90 seconds of a send to that same address. The following Exception rules should be added for Sassafras Software components:

MacOS Firewall

The firewall in the MacOS is off by default and is an application based firewall rather than a port based firewall. It lacks the detailed UI configuration of a Windows Firewall to add a port exception. Generally speaking, if you enable the firewall (System Preferences -> Security & Privacy -> Firewall), the default options allow incoming connections to signed software. However, if you used our k2clientconfig utility to customize your Mac Deployment package, it will not have been signed at installation and late UDP responses may be blocked. To avoid this, you can add /Library/KeyAccess/KeyAccess.app to allow incoming connections.

Options

This section is for non standard considerations that may be needed for certain 3rd party integrations.