Copyright: : MARX(R) CryptoTech LP File : readme.txt Date: : Mar 28, 2023 Description : Smarx(R)OS package for macOS Operating System : macOS 10.9 and higher Content: 1. Smarx(R)OS for macOS package - Overview 2. Package content 3. Accessing the CRYPTO-BOX under macOS 3.1 Access to the CRYPTO-BOX on the local USB port 3.2 Access to the CRYPTO-BOX in network mode 4. Libraries and sample code for Implementation with API 4.1 Overview 4.2 API directory content 4.3 Sample build instructions 5. Contact Details 6. Version History ******************************************************************************* 1. Smarx(R)OS for macOS package - Overview ******************************************************************************* This document contains description of Smarx(R)OS for macOS package. With this package you can: - add software protection and license management with the CRYPTO-BOX(R) to your applications by using our Smarx(R)OS API - program CRYPTO-BOX(R) hardware with licensing data (SmrxProg) - use both local and network licensing modes (Smarx(R)OS Network Server) ******************************************************************************* 2. Package content ******************************************************************************* This package includes the following files and folders: - readme.txt - this file - setupSharedMemoryDaemon.sh - script for increasing shared memory, see 3.1 - /api - folder with Smarx(R)OS APIs for macOS, including samples for CBIOS/DO/RFP API and SmarxAPI/AC API. Both samples and library folder (SDK) are included, see /API/api.txt file for further details. - /network_server - folder with Smarx(R)OS Network Server for macOS - /smrxprog - folder with SmrxProg for macOS utility to program the CRYPTO-BOX(R) hardware with licensing data ******************************************************************************* 3. Accessing the CRYPTO-BOX under macOS ******************************************************************************* 3.1 Access to the CRYPTO-BOX on the local USB port -------------------------------------------------- To access the CRYPTO-BOX on the local USB port of Mac computers, no special USB driver nor additional runtime components are required. You only need to link your application with the corresponding Smarx OS library. Refer to "4.3 Sample build instructions" for build requirements. IMPORTANT: Smarx(R)OS API logic requires about 2 Mb of shared memory for internal usage. If your software or any of its dependencies require shared memory, CBIOS may not be initialized properly: CBIOS_Startup() will return error 0x35 (CBIOS_ERROR_NOT_INITIALIZED). The setupSharedMemoryDaemon.sh script in the main folder of this package will resolve this conflict by increasing system limits for shared memory. It will make proper changes to the system Property List File in /Library/LaunchDaemons/ directory. The following settings will be added: kern.sysv.shmmax=16777216 kern.sysv.shmmin=1 kern.sysv.shmmni=32 kern.sysv.shmseg=32 kern.sysv.shmall=4096 The script must be run with root rights. To run it: - Open a Terminal window - Type the following: sudo bash (then drap & drop the setupSharedMemoryDaemon.sh script and press enter) It will setup the shared memory limits for the current session (no restart is required), and will create a Property List File for the Launch Daemon for next reboot. NOTE: The script will also show the existing shared memory settings. We recommend to write them down: In case you experience any problems, you can revert these settings manually by editing the script file. You can modify shared memory configuration parameters in the script if you want to set you own values. Please note that the relationship between shmall and shmmax. shmall is the number of pages (eg. 4k in size) and shmmax=shmall*4096." 3.2 Access to the CRYPTO-BOX in network mode -------------------------------------------- The Smarx OS libraries for macOS support support the network mode which means that the CRYPTO-BOX is attached to any computer in the network where our "CBIOS Network Server" is running. In network mode the client application will access the CRYPTO-BOX via TCP/IP. Client and server may also the same computer. The CBIOS Network server is available for Windows, Linux and macOS platforms and can be downloaded from https://www.marx.com/en/support/downloads#networktools See our White Paper "Network Licensing for more details on network mode: https://www.marx.com/en/support/documents#whitepapers NOTE: Refer to the readme file in the corresponding server package for your target platform for details on server administration and configuration. ******************************************************************************* 4. Libraries and sample code for Implementation with API ******************************************************************************* 4.1 Overview ------------ The content in the /api subfolder of this package is targeted to developers who want to implement software protection and licensing with the CRYPTO-BOX(R) under macOS directly into the source code of their applications. IMPORTANT: For an introduction into API implementation and a detailed overview on the available APIs, we recommend to read our "Implementation with API" White Paper: https://www.marx.com/en/support/documents#whitepapers The following architectures are supported: - ARM64 (Apple M series processors) - Intel 64 bit - PPC 32 bit (see "obsolete" folder) The /api folder includes SDK and set of samples for: - C/C++, Objective C, Cocoa, Swift 5.0 (via Xcode) - Delphi (via RAD Studio 10.2 and up) - Java Virtual Machine - Qt4 - REALbasic and the following Smarx(R)OS programming interfaces: a) Smarx(R)API - high level, object oriented APIs (see /Samples/SmarxAPI/readme.txt for further details): - SmarxAPI - AC API - SmarxCpp b) Standard API subsets: - CBIOS: querying the CRYPTO-BOX local and in networks, access to memory and encryption functions) - DO: using (encrypted) DataObjects, such as Expiration Date, Counters or customized memory objects - RFP: updating the CRYPTO-BOX at the end-user side NOTE: Due to macOS's specific semaphore implementation we don't recommend to access the CRYPTO-BOX from multiple threads of one process! 4.2 API directory content ------------------------- The /api subfolder includes the following files and folders: - /sdk/SmarxAPI/ - SmarxAPI static library - libSmarxCPP.a - SmarxAPI library (Intel64/ARM64) - /sdk/static/ - CBIOS static libraries - libcbios.a - CBIOS library (Intel64/ARM64) - liwincompat.a - Windows compatibility library - librfp.a - RFP library (Intel64/ARM64) - /sdk/include - CBIOS, RFP and Windows compatibility header - /sdk/framework/ - unified binary module for Intel64/ARM64 processors. CBIOS framework needs to be installed into /Library/Frameworks/ directory. - /sdk/java/ - JNI (java native interface library for CBIOS) for Intel64/ARM64 processors - /sdk/Delphi/ - CBIOS/DO type definitions required for Delphi support under macOS - /samples/ - Smarx(R)OS API samples (CBIOS, DO, RFP, SmarxAPI) for different development environments - /obsolete/ - libraries for Mac OS Tiger (10.4). 32-bit universal binaries (i386/PPC 32-bit) - RFP library for Mac OS 10.5-10.9 4.3 Sample build instructions ----------------------------- To build SmarxAPI samples: - refer to readme.txt in /Samples/SmarxAPI/ subfolder for build instructions To build gcc samples use Xcode. To build Qt sample: - navigate to "Qt4" directory - run "qmake -spec macx-g++" to generate g++ makefile - run "make" to compile sample binary To build Delphi samples you need a Windows system with RAD Studio 10.2 or higher. Please check readme.txt in [Package root]/api/samples/[CBIOS/DO]/Delphi folder for further instructions. To run samples: - navigate to sample release directory - run ./%sample_name% (do not forget "./" before sample name) IMPORTANT: Before building the sample, place corresponding library from [Package root]/api/sdk folder to the /lib subfolder of the sample! - For Xcode CBIOS and DO samples, copy header files from [Package root]/api/sdk/include folder into /include subfolder in the sample root dir and libCBIOS.a from [Package root]/api/sdk/ folder to the /lib subfolder. - For Java JDK sample, place [Package root]/api/sdk/java/libjnicbios.jnilib into the /Release subfolder before running the sample. REMARK: To test samples in network mode, the Smarx(R)OS CBIOS Network Server needs to be run on the computer where the CRYPTO-BOX(R) is attached - can be either the same computer or any computer in the (local) network. See chapter 3.2 above for further details on network mode. ******************************************************************************* 5. Contact Details ******************************************************************************* Please contact us if you have questions or experience difficulties during implementation or usage of the CRYPTO-BOX(R), or if you need support for a specific (development) environment. U.S.A. ------------------------------ MARX CryptoTech LP 489 South Hill Street USA-30518 Buford, GA Phone: (+1) 770 904 0369 Fax: (+1) 678 730 1804 contact@marx.com www.marx.com Germany ------------------------------ MARX Software Security GmbH Vohburger Strasse 68 D-85104 Wackerstein Phone: (+49) 8403 / 9295-0 contact-de@marx.com Sales: (+49) 8403 / 9295-19 or sales-de@marx.com www.marx.com ******************************************************************************* 6. Version History ******************************************************************************* 1.00 08DEC2006 OK Initial version 1.10 22APR2008 SK Network UDP broadcasting added for server search 1.11 09APR2010 DB Revised for support Mac OS 10.5 & 10.6 1.60 27OCT2010 SK Added support of CBU2 and CBIOS1.6 internal logic 1.60 24NOV2010 DB Package revised to use different build targets 1.65 03JUL2011 SK Added JNI library with Intel 64-bit support 1.65 10OCT2011 DB All libraries are updated to new versions 1.70 18JUN2012 DB All libraries are updated to new versions 2.00 21SEP2012 SK All libraries are updated to CBIOS 2012, including support of expiration date & time and binding to local computer data objects. 2.10 20NOV2012 SK All libraries are updated to new versions 2.20 04NOV2014 DB All libraries are updated to CBIOS 2014, including CDO support, attach/detach notifications, CBIOS servers scanning logic improvements 2.30 24MAY2016 DB OSX ElCapitan support 2.35 21NOV2016 DB macOS Sierra support, CBIOS 2016 support, including extended networking, revised CDO 2.40 15AUG2017 DB macOS High Sierra support, CBIOS 2017 support extended networking improvements 2.41 20JUL2019 - jnicbios bug fixes in CBIOS_CBU2_GetKeyAES and CBIOS_CBU2_CryptAES - jnicbios bug fix in CBIOS_CBU2_GetKeyInfoAES 2.42 15NOV2019 Fix: CRYPTO-BOX sometimes not detected under macOS Catalina 2.43 12DEC2019 RFP library: macOS 10.9+ support 2.44 24FEB2020 Updated libSmarxCPP.a, fixes in SmarxAPI samples, revised SmarxAPI readme file 2.45 14APR2021 Apple M1 support and bugfixes in network mode for libcbios.a, libSmarxCPP. and CBIOS.framework CBIOS Network Server: - Apple M1 support - IPv6 support - SetAPW/UPW command support added - DDoS protection added 2.46 15JUN2021 CBIOS: deadlock issue fix 2.47 04JUL2021 CBIOS: change lock timeout from 200s to 20s Apple M1 support for libRFP.a Rebuilt libjnicbios, SmarxCPP, CBIOSFramework with the latest CBIOS lib version SmarxAPI: fix gui notifications for SmarxAC 2.48 26JUL2021 CBIOS: fix issue that CBIOS_LockLicense locks CBU instead of license in local mode CBIOS: fix duplicate symbols issue when compiling DO sample Built libCBIOS.a and libSmarxCPP.a with latest CBIOS 2.49 18APR2022 Delphi(RAD Studio 10.2+) support added 2.50 20OCT2022 CBIOS: Fixed issue when UPWLogin crashes with access violation error in Delphi ARM64 applications 2.51 18NOV2022 Updated Swift sample to Swift 5 versions Small fixes Xcode DO sample. Updated libcbios.a (duplicated symbols issue in DO sample) 2.52 27FEB2023 Updated libcbios.a (fix read/write pipe issue, added support for CDO memory objects larger than 512 bytes) RFP sample: CDO support and Apple Silicon support added *********** Copyright(c) 2002, 2023 MARX(R) CryptoTech LP ******************** *****************************************************************************/