Copyright: : MARX(R) CryptoTech LP File: : network_server.txt Date: : Mar 28, 2023 Description: : Smarx(R)OS Network Server for macOS CONTENTS ======== 1. Overview 2. Installation 3. Configuration Settings (CBIOSSrv.cfg) 4. Server Administration Instructions 5. FAQ (Frequently Asked Questions) 6. Version History ******************************************************************************* 1. Overview ******************************************************************************* 1.1 Distributive content ------------------------ This document contains description of Smarx(R)OS Network Server for macOS. The Smarx(R)OS Network Server (or CBIOS Network Server) allows Smarx OS based applications to access a CRYPTO-BOX(R) attached to the USB port of any computer on the network. It takes care of managing the remote connections and forwards license queries to the attached CRYPTO-BOX units. Network licensing is ideal for cost-effective software licensing in (corporate) networks. The software vendor determines how often the application is allowed to run in a network - with just one CRYPTO-BOX per network. Furthermore, it allows software licensing not only for computers/laptops, but also for environments without the possibility to connect a CRYPTO-BOX(R) directly: - Mobile devices (Tablets, Smartphones) - IoT devices - Virtual machines without access to a physical USB port For more details on Network licensing with the CRYPTO-BOX, please refer to chapter 1 in our "Network Licensing" White Paper: https://www.marx.com/en/support/documents#whitepapers The Network Server for macOS includes the following files: - network_server.txt - this file - CBIOS Network Server.app - Network Server App which contains the following files: * CBIOSSrv.cfg - Server configuration file * netcbios_server - Server binary * CBIOSSrv.log - log file * run.sh/run_server.sh - Shell executable files for server startup 1.2 Supported Operating Systems and Hardware -------------------------------------------- - macOS (OS X) 10.13 or higher - Intel64 or M1 (ARM64) based Mac Remark: If you need the Network Server for other platforms (Windows, Linux), please visit: https://www.marx.com/en/support/downloads#networktools 1.3 Supported CRYPTO-BOX Hardware --------------------------------- - CRYPTO-BOX SC Rev.1 and Rev.2, Firmware 2.2 and higher - CRYPTO-BOX XS or Versa* Rev.1 and Rev.2, Firmware 1.6 and higher, Smarx(R)OS formatted * The CRYPTO-BOX Versa does not support network license management with LCS (floating license), the number of network licenses will be always unlimited in that case. See 5. for more details. ******************************************************************************* 2. Installation ******************************************************************************* 2.1 Downloading the latest version ---------------------------------- The latest Network Server distributive can be downloaded from: https://www.marx.com/en/support/downloads#networktools 2.2 Installation and Start -------------------------- Unzip the package, and copy the "CBIOS Network Server.app" to your preferred location on your Mac (eg. Application folder). Launch CBIOS Network Server.app. It will do the following: - Create a link in the dock; - Create a link to netcbios_server in /usr/local/bin in order to launch the server through the console; - Show this readme file; - Start the server (a console window will be opened). IMPORTANT: When launching CBIOS Network Server.app for the first time on macOS versions 11 and up you will get a security message from Gatekeeper that "CBIOS Network Server" cannot be opened. Go to "System Settings" -> "Privacy & Security" and allow to start the CBIOS Network Server. To prevent this message, you can sign the network server with your Apple Developer certificate before providing it to your end-users. On first launch the server package will also ask for administrative rights to configure the settings described above. Next time, just click on the dock icon to start the server. Or open a Terminal window and type "netcbios_server". Press CTRL+C to shutdown the server. ******************************************************************************* 3. Configuration Settings (CBIOSSrv.cfg) ******************************************************************************* Configuration settings are set in CBIOSSrv.cfg file which is located at: CBIOS Network Server.app/Contents/MacOS REMARK: When starting the "CBIOS Network Server.app" from Dock or from Applications folder, the server will automatically take configuration settings from the folder above. Furthermore, a log file (CBIOSSrv.LOG) will be written to the same location. If you want to start the server from the console with "netcbios_server" you have to specify the location of the CBIOSSrv.cfg (and the CBIOSSrv.LOG if required) with the following options: -c: [cfg file] // specifies config file location -l: [log file] // specifies log file, all output will be written to file instead of console You can edit default settings in CBIOSSrv.cfg (some options described below may not be available for Linux and macOS version of the server): 3.1 Server IP & Port -------------------- Default values: IP=* Port=8765 If having more than one active network configured for the Server computer (Ethernet, Wi-Fi, active VPN, virtual adapters of VMWare, etc.) it may be required to assign a dedicated IP address (& optionally port) to listen/response to UDP broadcasting of CBIOS network clients. It can be done with IP (and port) parameter of the CBIOSSrv.cfg configuration file. Examples: IP=10.10.10.32 (IPv4) or fe80::1ff:fe23:4567:890a (IPv6) Port=1234 Important Hints: a) If IP=* is set (default), CBIOS Server will listen on all network interfaces available on this computer (IPv4 and IPv6). If you specify an IP address here (IPv4 or IPv6), CBIOS Server will be available only via this particular address. b) If IP=::1 is set, then the server will be available on the local computer only. This is useful when server and client application are running on the same computer and server should not be exposed to other computers in the network. 3.2 Server UDP Port (broadcasting) ---------------------------------- UDPPort=8766 // default value 3.3 Server Passwords -------------------- Administrative Password (for the AdminApp tool, see 3.2): Password=admin // default value Optional Client Password: OptionalClientPassword= // ignored - default value The Administrative Password is used for server administration (AdminApp for Windows or customer specific program). The Server supports hardware based encryption calls not requiring UPW/APW Login in local mode (CryptFixed, InternalRSA, all CBU SC specific calls) before UPW/APW Logon. The Optional Client Password is supposed to prevent potential DDoS attacks if the Server is exposed online(accessible via global network). In this case specifying value for Optional Client Password in the CBIIOSSRv.cfg configuration file will require clients to start with the CBIOS_ClientLogin (OptionalClientPassword) call for their requests on hardware based encryption to be processed by the Server prior to UPW/APW login. If no value is set to OptionalClientPassword (by default), then clients' requests for hardware based encryption coming prior to UPW/APW login will be always processed by the Server. 3.4 Connection Settings ----------------------- ConnectionTimeoutSec=30 // connection timeout, default value in seconds KeepAliveScanRateMSec=3000 // inactivity scan rate, default value in milliseconds KeepAliveTimeoutSec=180 // inactivity timeout, default value in seconds ClientKeepAliveDelayMSec=3000 // default value in milliseconds 3.5 Debug Settings ------------------------------ "DebugLevel" parameter in CBIOSSrv.cfg file controls the level of the debug information that will be added to log file (console output or CBIOSSrv.log). It is specified as DebugLevel= where Level 0 - quiet, nothing is written to log file Level 1 - critical errors Level 2 - warnings Level 3 - general information (default) Level 4 - debug information 3.6 Max Log Size Settings ------------------------- MaxLogSizeKB=200 (default value). It controls the maximum log file size, but leaves the full session server. The old log is renamed to <...>.bak. 3.7 SetUPW/SetAPW Options ------------------------- Allows to execute CBIOS_SetUPW/CBIOS_SetAPW via network SetUPW=1 - allow CBIOS_SetUPW requests SetUPW=0 - do not allow CBIOS_SetUPW requests (default value) 3.8 Protection against Denial-of Service (DDoS) attacks ------------------------------------------------------ Allows to limit the number of requests per client (IP address) to the server during a defined time interval to prevent server overload, for instance by an attack or a malfunctioning application. FilterPacketsLimit=200 // Number of requests that are allowed to receive during FilterPacketsInterval, 0 - disable protection (default value) FilterPacketsInterval=5000 // Restriction interval (ms) In case the limit has reached, further requests will lead to CBIOS:ERR_CONN_REFUSED ******************************************************************************* 4. Server Administration Instructions ******************************************************************************* 4.1 General Issues ------------------ There are two possibilities to administrate the Smarx(R)OS Network Server: a) Locally on the same Mac where the server is installed. The Smarx OS Network Server icon appears in dock menu after the server was started for the first time. Click on the icon to start the server - a console window will be opened. Or open a Terminal window and type "netcbios_server". Press CTRL+C to shutdown the server. b) The server can be managed remotely from Windows computers with the Administrative Utility (Windows application) via TCP/IP protocol. The Administrative Utility (AdminApp64.exe resp. AdminApp.exe) is part of the CBIOS Server installation package for Windows which can be downloaded from marx.com (see 2.1) The server administration with the Administrative Utility is described below: 4.2 Connect to Server --------------------- Administrative Utility (Win64/32 only) provides remote administration of the Smarx(R)OS Network Server via TCP-IP protocol. Server Name (IP address, 127.0.0.1 by default), Port (8765 by default) and Password ("admin" by default) need to be submitted on connect dialog window. 4.3 Server Information ---------------------- After successful connect to Server, information about Server settings, attached boxes and connected clients/applications is displayed. 4.4 Change Server Settings -------------------------- To change Server settings press "Change settings" button and set Server Connection timeout (in seconds), Inactivity timeout (in seconds) and Inactivity scan rate (in seconds). Connection timeout - the timeout for inactive socket-level connection. If client opens connection to server but does not send any data, this connection will be closed when timeout is reached. After that server will be ready to process subsequent requests. Inactivity timeout - the session-level inactivity timeout. If client does not send keep-alive packet for previously opened session until this timeout is reached, this session will be closed and all appropriate resources (network licenses, e.g.) will be released. Inactivity scan rate - the rate at which session table is scanned for inactive sessions (those sessions for which keep-alive packet is not received in time). 4.5 Change Password ------------------- To change Administrative password settings press 'Change password' button, input current (old) password, set and confirm new password value. ******************************************************************************* 5. FAQ (Frequently Asked Questions) ******************************************************************************* Q: How can I limit the number of instances of my client application in the network which can connect to the server? A: This requires a CRYPTO-BOX SC or XS (CRYPTO-BOX Versa model does not support limiting the number of network licenses), and the License Control System (LCS) which is available as an option. For more details see: https://www.marx.com/en/lcs And the "Network Licensing" White Paper: https://www.marx.com/en/support/documents#whitepapers Q: Where can I obtain the latest version of the CBIOS Network Server? A: The latest release is available at marx.com download area: https://www.marx.com/en/support/downloads#networktools Q: Does the Server support IPv6 protocol? A: Yes, both IPv4 and IPv6 are supported. If IP=* is set in .cfg file (default value), CBIOS Server will listen on all network interfaces available on this computer (IPv4 and IPv6). If you specify an IP address here (IPv4 or IPv6), CBIOS Server will be available only via this particular address. Q: When I search for available server in my network, I get no results although the server is up and running on the other computer in my network. A: UDP Search will only work if UDP connection is not blocked by the firewall, and both CBIOS Server and client are in the same sub-network. See also next question. Q: I cannot properly connect to the CBIOS Server / I get CBIOS:ERR_CONN_REFUSED! A: I most cases the reason is one of the following: a) Configuration/firewall issue. Please check your network and firewall settings or try to disable your firewall temporary to test connection. On Windows computers you can also use MARX Analyzer to test your network configuration: https://www.marx.com/en/support/downloads#driversanddiagnostic b) The settings for Packet Filtering are too low, see 3.8 for details. ******************************************************************************* 6. Version History ******************************************************************************* 1.00 16NOV2006 Initial version 1.10.6.1209 09DEC2006 Bug fixes, rebuild with the latest libCBIOS.a 1.20.8.0420 20APR2008 UDP listening added 1.60 24NOV2010 Added support of CBU2 and CBIOS1.6 internal logic 1.70 20NOV2012 Rebuilt with new libraries (network binding supported) 1.80 04NOV2014 Rebuilt with latest libraries 1.90 24MAY2016 Rebuilt with latest libraries 1.95 21NOV2016 Rebuilt with latest libraries, CDO support 1.96 14AUG2017 SmarxAPI support; macOS High Sierra Support 1.97 20JUL2019 Fix delay in CBIOS network requests 1.98 22JUL2019 Fix: Network server sometimes hangs when accepting a new connection 1.99 15NOV2019 Fix: CRYPTO-BOX sometimes not detected on server startup under macOS Catalina 1.100 14APR2021 M1 suppport IPv6 support SetAPW/UPW command support added DDoS protection added 1.101 21JUN2021 Rebuilt with the latest CBIOS 1.102 21JUN2021 Server was rebuild as universal package for Intel64 and Apple CPUs 1.103 28MAR2023 Fixed "filter packet thread" issue. Removed misleading IPV6 error messages. Fixed architecture detection in start script for Macs with Apple CPU to avoid Rosetta installation message if Rosetta is not installed. ********** Copyright(c) 2003, 2023 MARX(R) CryptoTech LP ******************** *****************************************************************************/