> For the complete documentation index, see [llms.txt](https://sandbox-docs.verifone.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sandbox-docs.verifone.com/adk-5.0-programmers-guide/readme/system_overview/pg_vos3_differences.md). # VOS3 Main Differences and Migration from VOS1/VOS2 ## Main Differences to VOS1/VOS2 The following table provides summary on changes compared to existing VOS2 platform and lists potential impact to applications. | | Area | Changes | Impacts | | -- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Packaging format and tools |

Control files are replaced by manifest (json) files describing the bundle and its packages.
Adapt package types to vos3 package types.

|

Users to repackage applications with the new VOS3 packaging tools.
Notes:
- Bundles targeting read-only partitions (system\_ro & user\_ro) are not allowed to target the same file location on device (i.e. conflict). Installation will fail and report this error.
- Bundles must have unique names on the system. On vos1/vos2 bundles with different users could have same name. This was confusing and error prone. Installation and packaging will fail and report this error.

| | 2 | Signing | VOS3 will no longer support signing via signing cards, but only via online signing service. | Need to use VF online signing methods. | | 3 | Compiler and Toolset | VOS3 will use newer compiler and tools for building applications. This is to enable more recent C/C++ standards |

Users to update to the new Compiler and revise code as needed according to findings caused by stricter or different checks that come with changed tools.
Plan is to use gcc-Version 11.2.1 20220111 (GNU Toolchain for the Arm Architecture 11.2-2022.02 (arm-11.14))
- C++17 Support in GCC: GCC has almost full support for the previous revision of the C++ standard, which was published in 2017. Some library features are missing or incomplete, as described in the library documentation.
- C++20 Support in GCC: GCC has experimental support for the latest revision of the C++ standard, which was published in 2020. C++20 features are available since GCC 8. To enable C++20 support, add the command-line parameter -std=c++20 (use -std=c++2a in GCC 9 and earlier) to your g++ command line. Or, to enable GNU extensions in addition to C++20 features, add -std=gnu++20. Important: Because the ISO C++20 standard is very recent, GCC's support is experimental.
- Default is: Default ist #define \_\_cplusplus 201703L, meaning C++17 standard.

| | 4 | Linux Kernel | VOS3 will user newer revisions of the linux kernel. Also the Linux kernel revisions might be different between various products running VOS3. | Users will need to adjust to some potential (even though not expected) behavior changes of the underlying Linux system when using direct calls to the POSIX APIs of the system. | | 5 | A/B Images | VOS3 will support A/B scheme for supporting both seamless updates and allow fallback to previous image of the system. |

A VOS3 device will contain two versions of the installed software:
- "active" version (currently running)
- "fallback" version (previous version)
Thus, application executables, libraries and read-only resources will reside in the device in two versions (as for the system software itself). Each time an installation takes place, the current "fallback" version is lost, the current "active" version becomes the fallback and the newly installed version becomes "active" version.

To take advantage of this versioning, the read/write data storage for applications will come in two forms:
- "versioned data" : this storage is kept in two versions and will be restored as it was when falling back ("/home/usr1/versioned\_data")
- "flash" : this storage is not versioned and is thus common to all versions ("/home/usr1/flash")

| | 6 | Sysmode vs. VOS3 control panels | VOS3 will have changed Sysmode Interface. Most of previous VOS1/VOS2 sysmode gets replaced with System applications for various purpose (e.g. Log Control Panel, Comms Control Panel, Power Panel, etc.). | No changes to applications expected, but operational differences. | | 7 | No VOS Private APIs | VOS3 will no longer support the VOS1/VOS2 private APIs. Older VOS services APIs have been deprecated and removed from VOS3 products. | Users need to revise their application code to use and comply with ADK APIs. | | 8 | No VSS Support | VOS3 will no longer support Verifone Secure Scripts (VSS). | Users will need to adapt any security customization to make use of new Secure Interfaces for Key management or Key derivation using Verifone Customizable Crypto Interface (VCCI). | | 9 | No direct key loading | VOS3 will not support direct key loading APIs. | Users will need to migrate key all loading to VRK or make use of new Secure Interfaces for Key management using Verifone Customizable Crypto Interface (VCCI). | | 10 | Transparent Card Data and Card Reader Access | VOS3 enforces card holder data protection by default through a system service called SDI that blocks transparent card data access and offers encrypted card data to transactions. This enables P2PE/PCI-SSF compliant support for VOS3 products. |

Users can change behavior if needed by using one of the following methods:
- Configuration of BIN ranges that can be excluded from card holder data protection.
- Installation of extension regional/customer plug-ins that enable transparent card reader access
- Installation of vos3-cards plugin that offers VOS2 APIs and card data access compatible to VOS2

| | 11 | Flash partitions not using "synchronized I/O" | In VOS2, flash partitions were mounted with the "sync" option (aka "synchronized I/O"). This is a bottleneck of performance (cpu and io) for both system and applications. On VOS3, all flash partitions will not be mounted with that option. It is also strongly discouraged to use the sync() call in any part of the VOS3 system or applications as this synchronizes all files of all filesystems: thus very inefficient. |

An application that really needs a "transactional" behavior on a specific file can use one of the following methods:
- open the file with "O\_DSYNC": all writing to this file will be synchronized
- use fsync() on a file to synchronize

| | 12 | No ADK-SEC 1.x compatibility layer | VOS3 will no longer support a compatibility layer for ADK-SEC 1.x APIs. |

Users still using ADK-SEC 1.x APIs need to revise their application code to use and comply with ADK 2.x APIs.
- ADK-SEC 1.x has been deprecated since ADK 4.5 and eventually removed in ADK 4.8.
- ADK-SEC 2.x has provided a compatibility layer with ADK-SEC 1.x interface (libseccmd.h) for the time of migration.
VOS3 will no longer support ADK-SEC 1.x APIs (neither native, nor in a compatibility layer). Users still using ADK-SEC 1.x APIs have to migrate to ADK-SEC 2.x APIs introduced since ADK 4.4. Applications already using ADK-SEC 2.x API will not be affected from this change.

| | 13 | OpenSSL Update | VOS3 will update to OpenSSL v3 as this is the long-term supported release of OpenSSL. However, OpenSSL experied some incompatible changes when coming from earlier revisions of the library. | Applications that use OpenSSL directly twill need to adapt their application code to comply with changed APIs in OpenSSL v3. | | 14 | ADK COM: PKCS#12 support |

Following ADK COM features will not be supported on VOS3:
- PKCS#12 files for Wifi Cert loading - replaced with VRK packages for secure loading of Wifi certs

| Applications to load Wifi certs using VRK packages. | | 15 | ADK COM: Analog Modem Support removed | Analog Modem support (VOS3 products will not have any analog modem support. Only exception is FF base, but VOS3 will not support the analog modem in FF Base either) | No application impact. | | 16 | ADK COM: No Dial-up Networking Profile (DUN) | No dial-up network support in VOS3. Neither internal dial-up modem (no HW) nor the dial-up modem in a connected FF base are supported any longer. | no deployements with dial-up mode supported. | | 17 | ADK COM: STunnel API support removed | STunnel APIs for SDI based external pinpads - replaced in SDI internally |

No application impact.
SDI external pinpad connection is transparent to applications.

| | 18 | ADK COM: External Barcode reader | Support for HID based external barcode readers removed | no support of external barcode readers - use built-in camera or HW barcode decoder supported through ADK-GUI. | | 19 | Installation |

- Apps cannot be installed without reboot
- new installer API

| No impact on applications. Applications implementing own download mechanisms are recommended to use the new installer API. | ## Porting Guidelines ### VOS1/VOS2 Private APIs No longer supported and deprecated since ADK 4.6. Use ADK APIs. ### Application Packaging #### Translating VOS2 into VOS3 Package types The following table provides guidance on translating VOS2 packages into VOS3 packages. | | | | | | | ----------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | VOS2 package type | VOS2 destination | Possible VOS3 package types | VOS3 destination | Notes | | user | /home/\/ | user\_ro | /home/\/ | | | userflash | /mnt/flash/userdata/\/ |

system\_versioned\_data
system\_data
user\_versioned\_data
user\_data

|

/mnt/sysdata/versioned/\/
/mnt/sysdata/data/\/
/mnt/appdata/versioned/\/
/mnt/appdata/data/\/

| | | userflashshare | /mnt/flash/userdata/share/ |

share\_system\_versioned\_data
share\_user\_versioned\_data
share\_all\_versioned\_data

|

/mnt/sysdata/versioned/share/
/mnt/appdata/versioned/share/
/mnt/appdata/versioned/globalshare/

| | | userfont | /mnt/flash/system/fonts/ | font\_ro | /usr/share/fonts/ | | | config | /etc/config/ |

partial support
(sys\_<> can use system\_ro)
(usr\ can use user\_ro)

| | | | flashconfig | /mnt/flash/etc/config/ |

share\_system\_versioned\_data
share\_user\_versioned\_data
share\_all\_versioned\_data

|

/mnt/sysdata/versioned/share/
/mnt/appdata/versioned/share/
/mnt/appdata/versioned/globalshare/

| Global config is: /mnt/appdata/versioned/globalshare/etc/config/ | | vss | /etc/vss/\/ | not supported | | | | unsigned | /mnt/flash/userdata/\/unsigned/ | user\_unsigned\_data | /mnt/appdata/data/\/unsigned/ | | #### Application Manifests With VOS3 all applications get launched using the Multi-Application Controller. Applications need to provide a manifest file for getting started by MAC. Details on manifest parameter and example JSON manifests are provided as part of the MAC documentation. Both JSON and INI data format manifest files are compatible with VOS1/VOS2. The JSON manifest files need to be packaged with the applications and will be installed to user's home directory: ```fragment - /home/usr*/www - /home/sys_*/www ``` Manifest file names should end with **.mft** #### VHQ Manifest * New dlfile.mfg (packaged into dlfile.mft.tgz as part of the dlfile.tar) * JSON formatted file similar to Engage.mfg on VOS2 * Some field will be different * dlfile.mfg will be auto-generated by packman - no need to add Engage.mfg manually ### ADK MAC (Multi-application Controller) {% hint style="warning" %} MAC is a mandatory component on VOS3. Any application on VOS3 needs to provide a corresponding MAC manifest file to configure the appliaction for launching. This allows also to let MAC launch applications automatically to avoid manual start from MAC desktop. {% endhint %} MAC is a display controller daemon. It provides application developers a way to start/stop applications and controls treir visibility. #### API compatibility All APIs supported as on VOS1/VOS2. #### Launching via Multi-Application Controller (MAC) With VOS3 all applications get launched using the Multi-Application Controller. This enables: * auto-launching of applications and services * manual launch from desktop * assignment of UI resources for applications * switching between applications * access to system control panels {% hint style="warning" %} There is no support outside of MAC launching for applications. Applications should use following API for that: * [sysLaunchApp()](/adk-5.0-programmers-guide/readme/modules/group__mac/namespacevfimac.md#a52ed11c68234a6abcf53fa5edd596729) - run application by it's name in manifest file * [sysLaunchAppid()](/adk-5.0-programmers-guide/readme/modules/group__mac/namespacevfimac.md#a77748eeae43d8b50145564d0022ad886) - run application by it's identifier in manifest file {% endhint %} #### Hotkey combinations | Key combination | Action | | -------------------------- | ------------------------------------- | | X + 1 | starts Control Panel | | X + 3 | shows MAC Desktop | | 1 + 5 + 9 | shows MAC Desktop | | 1 + 5 + 9 (on MAC desktop) | sysmode is no more available on VOS3! | #### Manifests Application developers describe how MAC should handle their applications by providing a manifest file. Manifests are text files, whose names ends with .mft Manifest is accepted in JSON or INI data formats, as it was on previous VOS versions. MAC is looking for manifest files in the following locations: ```fragment - /home/usr*/www - /home/sys_*/www ``` MAC manifest example: ```cpp [application] id=mac_demo1 version=3.83.15 statusbar=y app_resource_dir=mac_demo1 depends=mac_demo2;mac_demo3; recover=n [desktop] label=mac_demo1 icon=mac_demo1/default/verifone-icon.png cmdline=../mac_demo1 args=r1d2 r2d3 [autolaunch] cmdline=../mac_demo1 start_hidden=y ``` {% hint style="warning" %} MAC manifest is not the same thing as installable package manifest. {% endhint %} #### Sample MAC application package ```cpp mac_sample ├── mac_demo1 │ ├── mac_demo1 Applicatyion binary │ └── www │ ├── mac_demo1 │ │ ├── 128x64M16N Specific screen resolution resources │ │ │ ├── gui.ini │ │ │ ├── mainmenu.html │ │ └── default default GUI resources │ │ ├── default-icon.png │ │ ├── gui.ini │ │ ├── mainmenu.html │ └── mac_demo1.mft MAC manifest └── manifest.json Packman manifest file ``` ### ADK-LOG (Logging) #### API compatibility All APIs supported as on VOS1/VOS2. ### ADK-IPC (Inter-Process Communication) #### API compatibility All APIs supported as on VOS1/VOS2. ### ADK-INF (Information Database Service) #### API compatibility All APIs supported as on VOS1/VOS2. ### ADK-EVT (Event Service) #### API compatibility All APIs supported as on VOS1/VOS2. ### ADK-COM (Network Setup and Communications) #### API compatibility In general all ADK-COM APIs are supported same way as on previous VOS1/VOS2 platform. Following deprecations/extensions are applicable for VOS3: * any analogue modem related device properties and connection profiles are not supported * e.g. COM\_PROP\_RAW\_MODEM\_CURRENT\_MODULATION * no support for external BC reader using USB HID * i.e. serial connection profile with por BC\_READER. Serial devices using dynUSB can still be used. * not supported API support for STunnel on VOS3. This configuration option for a "2-piece" PIN pad use-case is replaced by SDI EPP/EPM. * com\_SetStunnelConfig * new APIs for iBeacon- recommended to be used with VOS3 * [com\_IBeaconGetAdvertisement()](/adk-5.0-programmers-guide/readme/files/dir_33381b8c0566c9eb2048a95e4cccf925/dir_e4c66e267a8c8e9ea5ad4dbe1baeabc7/libcom_8h.md#a2c13209f2854692dc63309551fdc3de1) * [com\_IBeaconSetAdvertisement()](/adk-5.0-programmers-guide/readme/files/dir_33381b8c0566c9eb2048a95e4cccf925/dir_e4c66e267a8c8e9ea5ad4dbe1baeabc7/libcom_8h.md#acba33f21f870bf27b8e62a600ec1be17) * [com\_IBeaconStartAdvertisement()](/adk-5.0-programmers-guide/readme/files/dir_33381b8c0566c9eb2048a95e4cccf925/dir_e4c66e267a8c8e9ea5ad4dbe1baeabc7/libcom_8h.md#a4808892fb28569f7f949fa14aa103ef6) * [com\_IBeaconStopAdvertisement()](/adk-5.0-programmers-guide/readme/files/dir_33381b8c0566c9eb2048a95e4cccf925/dir_e4c66e267a8c8e9ea5ad4dbe1baeabc7/libcom_8h.md#a35633db6e2632562eff1452a5207408d) * new APIs for Eddystone Beacon - recommended to be used with VOS3 * [com\_EddystoneURLGetAdvertisementExt()](/adk-5.0-programmers-guide/readme/files/dir_33381b8c0566c9eb2048a95e4cccf925/dir_e4c66e267a8c8e9ea5ad4dbe1baeabc7/libcom_8h.md#a3163590cfa3a4ff5ff6cb5efb708883b) * [com\_EddystoneURLSetAdvertisementExt()](/adk-5.0-programmers-guide/readme/files/dir_33381b8c0566c9eb2048a95e4cccf925/dir_e4c66e267a8c8e9ea5ad4dbe1baeabc7/libcom_8h.md#a7eab5f7f7382383034c0b37d63d044ec) #### Communication and Network Descriptors VOS3 continues to use the same format and parameter for ADK connection and network profiles. Exeption: connection and network profiles for modem (MDM\_INT, BT\_DUN) and external barcode reader (BC\_READER). #### Custom Certificate Loading and pre-loaded authentication key VOS3 will no longer support loading certificates for TLS, Wifi EAP and LAN 802.1x using PKCS#12 files. The system now supports secure loading of these certificates using VRKv2. The loaded certificates will be stored securely in the system and can be referenced by the SSL\_OWN\_CERT and SSL\_OWN\_KEY parameter with "vault:\" in the related connection profile for TLS or network profile for Wifi or LAN. The \ needs to match the name of the loaded certificate / key used in the VRKv2 package. The preloaded Authentication Key (Authex/ AuthN) / warranty key can be referenced using "vault:" as a name for SSL\_OWN\_CERT and SSL\_OWN\_PKEY. #### Network Startup and Recovery handling Unlike VOS1/VOS2, the VOS3 system always implements an auto start and recovery for configured networks. With this the VOS3 system will always: * BT: try to re-establish connection via BT-PAN to the previously connected device when coming back in range * Wifi: try to re-establish Wifi connection to the previously connected SSID or other in-range configured SSID when coming back in range * Cellular: try to re-establish connection to the previously connected mobile network * LAN: try to re-establish connection to the previously connected LAN network The previous support for manual configuration of recovery handling using load packages is deprecated (previous: dl.comcfg-no-rc-1.0.0.tgz and dl.comcfg-no-rc-remove-1.0.0.tgz packages). #### Network Diagnose Functions Comunication Control Panel (CCP) supports network diagnose (ping sequence, NSLookup, connection test to remote host, extended http server tests). CCP also supports manual network restart for trouble shooting. Since VOS3 no longer supports Sysmode, CCP needs to be extended by a couple of diagnostics and communication related information previously provided by VOS2 Sysmode. #### Changes in configuration files Any user generated configuration for ADK-COM / CCP need to be regenerated with the new VOS3 packaging system using type flashconfig. e.g. the location is changed to /mnt/appdata/versioned/globalshare/etc/config/adk-com. ### ADK-GUIPRT (HTML Rendering, Video playback, Barcode Scanner) #### API compatibility All APIs supported as on VOS1/VOS2. #### HTML / CSS Resource files * As on VOS1/VOS2 resource files are expected to be stored in www in the home of the user. Depending on manifest configuration this is * /home/\/www/\ * /home/\/www/\/\ * \ depends on MAC manifest configuration * \ is handled the same way as on VOS1/VOS2, it can be the model name (e.g. P630) or based on display resolution and keypad, e.g. 320x480C15T * Since VOS3 no longer is using Grsecurity, setting up file permissions when packaging resource files is slightly different as on VOS1/VOS2: Files need to be in group share instead of group system. * Using makepackage3 use "--group share" * Directly preparing a Packman manifest, it looks like this: ```cpp { "name":"demo", "version":"1.2.3", "user":"usr1", "software_platforms":["vos3"], "packages":[{ "name":"executable", "type":"user_ro" },{ "name":"resource", "group":"share", "type":"user_ro" }], "signers":["SPONSOR"] } ``` {% hint style="info" %} group "share" shares the resource files with all users. Depending on context, group "usr1sys" ("usr2sys" for usr2, ...) may also be used. {% endhint %} #### Video files As on VOS1/VOS2 mplayer is used for playing videos. The supported video formats depend on those supported by mplayer. #### Barcode scanning Barcode scanning works the same as on VOS1/VOS2 (use \) #### Adding fonts Fonts may be installed using font packages. For this set the type of the package to "font\_ro". This takes care of generating the required fonts.dir file so that the font can be found later on. ### ADK-PRX (CPR proxy to access Verifone webservices) #### Prerequisites * VOS3 support added with version 3.0.5 * Requires at least ADKIPC 1.26.0 #### Compatibility * API compatibility: Pure service, no APIs as on VOS1/VOS2 * Interface compatibility: All interfaces (listen port, config interface) supported as on VOS1/VOS2 * Package format: Package format changed, but same naming for base and activation packages * Features: Same code base as on VOS1/VOS2, thus, the same features are provided #### No support for old CG endpoints * Support for old CG endpoints (dev.cgateway.verifone.com, test.cgateway.verifone.com, staging1.cgateway.verifone.com, cgateway.verifone.com) was dropped.

CG endpoints from now are deprecated!

* ADKPRX base package only installs GSC endpoints as default environments * Last option to use CG endpoints with version 3.5.0 is the installation of an user config package on top of ADKPRX (sample user config package coming along with ADKPRX documentation)

Customers are advised to do this for testing purposes only. Do NOT use old CG endpoints for productive installations, since old CG environment endpoints will go offline sooner or later.

* Old ADKs might can still use version 3.0.50 (VOS/VOS2 only), which still contains CG endpoints, but also these installations should move to GSC soon #### User config packages * Cloudproxy uses the same configuration files for all platforms (VOS/VOS2 and VOS3) * VOS3 platform uses a different package format and installation location on target * Wheras VOS/VOS2 has used global folder `/etc/config/proxy`, on VOS3 configuration files are looked up under `/home/usr` \/proxy: At startup ADK cloudproxy checks for the existence of the folder with included files starting from `usr1` up to `usr16`. If there are related files found under a specific user, this user directory is applied as source for user configuration files. This means, the first user providing the files wins, other users with higher user numbers will be ignored. * Since VOS3 no longer is using Grsecurity, setting up file permissions when packaging files is slightly different as on VOS1/VOS2: User config packages must use group `usrsys` with type `user_ro` (instead VOS/VOS2 has used group share and type `config`. For details please read documentation coming along with package `prx-doc-X.X.X-X.zip` with the ADK Cloud Proxy release. ### ADK-SND (Sound Playback) #### API compatibility * All APIs supported as on VOS1/VOS2. * Same WAV and MP3 files can be reused on VOS3. ### ADK-Cards (Card Acceptance, Processing and EMV kernels) #### API compatibility Migrating from VOS2 to VOS3 requires to migrate to Secure Data Interface (SDI) as SDI will be no longer an optional component on VOS3 systems. To simplify migration VOS3 introduced a new SDI client library (libSDIClient) that exports existing Cards/EMV APIs similar to ADK on VOS2. The provided VOS3 libSDIClient includes * ADK\_EMV CT functions * ADK EMV CTLS functions * ADK-MSR functions * ADK-NFC functions * ADK-TEC functions #### Transparent L1 card reader access APIs On VOS3 specifically the libSDIClient also provides the transparent L1 access together with loading a specific SDI Plugin for VOS3 called vos3-cards. This of course must not be loaded when using SDI in headed mode and/or with external connections. The SDI Plugin will add all the VOS/VOS2 APIs back on VOS3 and must be loaded / used in VOS3 application projects whenever transparent card reader access is required. All these legacy APIs for transparent access will then be available also in SDI environment on VOS3. Transaction data fetching functions (including cardholder sensitive data) such as [EMV\_CT\_fetchTxnTags()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___f_u_n_c___f_l_o_w___c_t.md#gab005fdec183a0c8fef18ae677cce6dc5) or [EMV\_CTLS\_fetchTxnTags()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t_l_s/group___f_u_n_c___f_l_o_w___c_t_l_s.md#ga8c9f0640ed818c3dc19da528f5f0b406) will also be fully supported when the specific vos3-cards plugin is loaded. #### Card Acceptance APIs (ADK-TEC) Although ADK-TEC APIs will be moved forward too, it is recommended to be replaced by the SDI card detection. This is due to the nature of the architecture of VOS3 terminals where parallel access to physical readers is restricted due to the command response interface to the K81, which will result in a different timing. The underlying K81 on VOS3 (and Android systems) has a single serial connection to the K81 main processor, where access must be controlled and organized (e.g. by SDI). Polling from multiple application threads and tasks on various hardware pieces on K81 side, e.g. CT / CTLS / MSR and other K81 resources in parallel may result in deviations from VOS2. All ADK-TEC features are covered with the SDI card detection and can be used in the 23-01 (synchronous) and 23-03 (asynchronous) card detection. For details, please refer to the SDI documentation. Both commands (23-01 and 23-03) are of course part of the libSDIClient. Your ADK-TEC calls can be replaced by these functions. #### General migration strategy towards SDI Currently the following type of solutions exist on VOS2: * TYPE1: Plain ADK/VOS2 implementations, not making use of SDI today * TYPE2: VOS2 implementations that are based on SDI and use the libSDIClient already, but still DO bypass SDI with direct ADK calls (i.e. do use not existing SDI functionality of ADK-CARDS ) * TYPE3: Implementations that are based on SDI and use the libSDIClient already but do NOT bypass SDI. Those implementations are also Android (Trinity and NEO) compliant \[Migration for Type 1]{.underline}: As explained in detail above. Use libSDIClient and load the plugin. The APIs for card handling are available in the same way as in VOS1/VOS2. **You are getting the payment/sensitive data in clear as on VOS2. You can NOT make use of the SDI P2PE certification.** You may want to consider to migrate from ADK-TEC to the SDI Card Detection (23-01 / 23-03), which is part of the libSDIClient APIs. \[Migration for TYPE 2]{.underline}: This is similar to TYPE 1. Instead of directly calling the VOS1/VOS2 ADK functions you will now simply call the counterpart functions of the libSDIClient (names and APIs will be the same), so nothing to do on application level. **The SDI plugin for VOS3 enables that you to get the payment/sensitive data in clear as on VOS2. You can NOT make use of the SDI P2PE certification.** You may want to consider to migrate from ADK-TEC to the SDI Card Detection (23-01 / 23-03), which is part of the libSDIClient. \[Migration for TYPE 3]{.underline}: You are already fully compliant to SDI. Please do **NOT** load the new SDI Plugin for VOS3. This way sensitive data is protected. **You are NOT getting the payment/sensitive data in clear as on VOS2. You CAN make use of the SDI P2PE certification. There is no need to change your existing VOS/VOS2 SDI solution on VOS3.** #### EMV L1/L2 Kernels on Neo Platforms (Android vs. VOS3) The same type-approved EMV kernels for CT and CTLS (L1 and L2) are used on Neo HW platforms between VOS3 and Android operating systems. Thus the emv\_allowed.xml and the emv\_desired.xml can be used for both OS variants with the same kernels, same LOAs and same certifications. The emv\_desired.xml configuration files on VOS3 has same format as on VOS1/VOS2. **Note on P630 and P630-2 units:** * earlier "P630" products had a different CTLS1 HW architecture compared to "P630-2" - for this reason new L1/L2 certifications are provided for P630-2 hardware * VOS3 will only run on P630-2 units, while Android can run on both P630 and P630-2 * Please make sure you configure the correct L1/L2 kernels for VOS3 on P630-2 **All other future Neo devices that can run VOS3 or Android will share the same L1 and L2 approvals between VOS3 and Android/NEO as long as the hardware has not deviations in the CTLS L1 architecture.** #### Customizations SDI supports customizations with SDI plugins. These plugins enable extensions and specific card schemes handling. {% hint style="info" %} **Customization Plugins** Customization Plugins for SDI can be provided to implement specific card processing extensions. Please work with Verifone Platform SW group on specific requirements and implementation plan. {% endhint %} ### ADK SEC (Security) #### API compatibility * VOS3 will no longer support a compatibility layer for ADK-SEC 1.x APIs. * VOS1/VOS2 ADK SEC transaction data APIs will no longer be supported with VOS3 - now implemented through SDI directly * extended secSetKSId parameter for MSK handling (optional for non-MSK handling) #### SDI as Security Provider on VOS3 Unlike VOS1/VOS2 the ADK SEC interface is provided through SDI service that works with the security processor directly for all security functions. There is no scapp2 daemon on VOS3. Applications continue to link against libsec2.so as a client library and this library connects to SDI. #### Key Identification Unlike VOS1/VOS2, keys in VOS3 are identified by a unique name. Keys are identified by a unique name across all loaded keys including pre-loaded warrantied keys. The use of former VOS1/VOS2 key slot IDs as unique key names is not recommended but speaking key names are suggested. #### Supported Schemes and Algorithms - Comparing to VOS1/VOS2 When migrating from VOS1/2 to VOS3 the following changes needs to be considered when configuring security engines and related operations: {% hint style="info" %} Supported Modules and Operations by Platform: ENC=secEncryptData, DEC=secDecryptData, SIG=secSign, VFY=secVerify, PIN=secRetrieveEncryptedPIN, UPD=secUpdateKey {% endhint %} | **Engine** | **VOS** | **VOS2** | **VOS3** | **Notes** | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | Verishield Security Scripts (VSS) | VSS: all operation | VSS: all operation | -- | - VOS3: replaced with VCCI, new Key Mgmt APIs | | Verifone Customizable Crypto Interface (VCCI) | -- | -- | X | - requires a Verifone signed SDI plug-in for VCCI extensions | | Triple-DES Master-/Session-Key |

IPPmsk: PIN, SIG, UPD
UPD key in GISKE format

|

IPPmsk: PIN, SIG, UPD
UPD key in GISKE format

| **TDES-MSK**: PIN, ENC, DEC, SIG, VFY, UPD |

- Master-Session Scheme Support, but no support for older IPP GISKE keyblock format
- PIN: SDI will provide PAN for ISO format #0 or #3

| | Triple-DES Fixed Key | -- | -- | **TDES-FIXED**: ENC, DEC, SIG, VFY | - PIN encryption with fixed keys not allowed! | | Triple DES-DUKPT |

IPPdukpt: PIN
ADE: ENC
SREDMAC: SIG, VFY, UPD

|

IPPdukpt: PIN
ADE: ENC
SREDMAC: SIG, VFY, UPD

| **TDES-DUKPT**: PIN, ENC, DEC, SIG, VFY, UPD |

- UPD=manual increment of Key Serial Number (KSN)
- PIN: SDI will provide PAN for ISO format #0 or #3

| | AES - DUKPT | -- | **AES:** PIN, ENC, DEC, SIG, VFY, UPD | **AES-DUKPT**: PIN, ENC, DEC, SIG, VFY, UPD |

- UPD=manual increment of Key Serial Number (KSN)
- PIN: PIN-Block Format #4 only
- Data: ECB and CBC mode
- MAC: CMAC only

| | RSA Operations | **RSA:** ENC, DEC, SIG, VFY | **RSA:** ENC, DEC, SIG, VFY | **RSA:** ENC, DEC, SIG, VFY | - allows use of AUTHN warrantied key | | SDI Secured File Storage (Crypto-RW) | X | X | X | - invalidates file content on tamper (no decryption possible) | | Verishield Protect (VSP/VCL) | X | X | X | - configured separately outside of SDI, not a module name | #### SDI Security Configuration File In general VOS3 continues to use the same sccfg.json security configuration file format as used in earlier VOS1/2 for SDI and ADK-SEC. SDI security configuration needs to be adapted for VOS3. Following items need to be checked: * key names (as per new unique name in the VRK loading package) * security module type (as per above table) Unlike VOS1/2 the security configuration file is no longer provided in the user home path of the application. For VOS3 the security configuration has to be loaded with SDI user config package. {% hint style="info" %} **Key Usage Checks.** The secure processor performs key usage checks for each crypto operation. That means VRK payloads have to be provided with proper key usage and mode according their intended usage. Keys with improper settings will be rejected by operations. {% endhint %} #### Replacement for VSS Scripts On VOS1/VOS2 Verifone Security Scripts (VSS) support was available and had been used by some applications for various security operations including * direct key loading, key derivation * PIN block generation * custom encryption, MACing * etc. On VOS3 there is no support for no support for direct key loading, but VRK key loading is the default key loading mechnism. However, if customizations are required, VOS3 provides new mechanisms for that purpose * Verifone Customizable Crypt Interface (VCCI) * Extended Key Management Mechanisms {% hint style="info" %} **Customization Plugins.** Customization Plugins for SDI can be provided to implement specific key derivation or custom key management solution. {% endhint %} ## Development environment for VOS3 Application Developers Developers use system development kit for developing applications. This includes the following: | **Item** | **Contents** | | ------------------------------------------- | ------------------------------------------------------------------------------ | | VOS3 build tools |

- gcc compiler
- gcc build tools

| | VOS3 host debug tools | - gdb debugger | | VOS3 device debug tools | - debug tools download package (dropbear, gdb, gdbserver, strace, etc.) | | VOS3 packaging and development signing tool | - packman | | VOS3 system download files | - VOS3 system download files for system update | | VOS3 / ADK APIs | - ADK headers, link libraries | | ADK Documentation |

- ADK release notes
- ADK component programmers guides
- examples

| ### ADK API Libraries Application use API prototypes from provided headers files and link against the ADK libraries to use | **Component** | **Client** Libraries | **Client** Header Files | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ADK GUIPRT | - libvfiguiprt.so |

- html/gui.h
- html/prt.h

| | ADK IPC |

- libvfiipc.so
- libvfiipctls.so

|

- ipc/ipc.h
- ipc/notify.h
- ipc/jsobject.h
- ipc/tls.h

| | ADK COM | - libcom.so |

- com/libcom.h
- com/libcom3.h

| | ADK CCP | - libccp.so | - com/libccp.h | | ADK MAC |

- libvfimac.so
- libvficpr.so

| - [sysinfo/mac.h](/adk-5.0-programmers-guide/readme/files/dir_e65d4d0c0ba9865676ee3897978ecbf1/dir_517ad9dc307a0538d3e19e98627cc0af/dir_619a55c4c313d761d1f6a99da403e1c9/mac_8h.md) | | ADK PM | - libvfisyspm.so | - [sysinfo/vfisyspm.h](/adk-5.0-programmers-guide/readme/files/dir_2fa442697ca4f3ad26ee86a05c70c5ba/dir_8c98103bf86c0a8e400b3720f3ef5f71/dir_c6564d074bdc7edceae1f5f34995b8b1/vfisyspm_8h.md) | | ADK EMV |

- libEMV\_CTLS\_Client.a
- libEMV\_CT\_Client.a
- libEMV\_CT\_Link.so
- libEMV\_CTLS\_Link.so
- libsdiclient.a
- libTLV\_Util.so

|

- emv/EMV\_Common\_Interface.h
- emv/EMV\_CT\_Interface.h
- emv/EMV\_CTLS\_Interface.h
- emv/EMV\_CT\_SerInterface.h
- emv/EMV\_CTLS\_SerInterface.h
- emv/E2E\_EMV\_CT\_Serialize.h
- emv/E2E\_EMV\_CTLS\_Serialize.h
- emv/btlv.h
- emv/EMV\_CT\_XML.h
- emv/EMV\_CTLS\_XML.h
- emv/hexutil.h

| | ADK MSR | - libsdiclient.a | - msr/msr.h | | ADK TEC | - libsdiclient.a | - [tec/tec.h](/adk-5.0-programmers-guide/readme/files/dir_c2b6fb90cbe225a4c7f5c562006e9b78/dir_797c2eec9d33c0e51d543580c2b239ca/dir_fa87c044aa590573d847d8ba2d3b48c1/tec_8h.md) | | ADK NFC | - libsdiclient.a |

- nfc/NFC\_Client.h
- nfc/NFC\_Interface.h

| | ADK SYS |

- libvfisysinfo.so
- libvfisysbar.so
- libutil.so

|

- sysinfo/sysinfo.h
- sysinfo/leds.h
- sysinfo/sysbar.h
- sysinfo/sysbeep.h
- sysinfo/util.h
- sysinfo/inifile.h

| | ADK CPL | - libcpl.so | - [commerce/commerce.h](/adk-5.0-programmers-guide/readme/files/dir_2002fcb36e937be08e088f9ab4e81de8/dir_fad52422ca9a0153aca9cfe879bff259/dir_613e11e510006a27889deef70cf7d9b4/_commerce_8h.md) | | ADK LOG | - liblog.so | - log/liblog2.h | | ADK ISO8583 | - libiso8583.so |

- iso8583/ConstData.h
- iso8583/dl\_err.h
- iso8583/dl\_str.h
- iso8583/dl\_iso8583.h
- iso8583/SafeBuffer.hpp
- iso8583/dl\_iso8583\_fields.
- iso8583/dl\_base.h
- iso8583/dl\_iso8583\_common.
- iso8583/dl\_mem.h
- iso8583/defs/dl\_iso8583\_de
- iso8583/defs/dl\_AS2805\_def
- iso8583/fwd/ConstData.h
- iso8583/fwd/SafeBuffer.hpp

| | ADK INF |

- libinf.so
- libinf\_util.so

|

- inf/infodb.h
- inf/inf\_util.h

| | ADK SND | - libsound.so | - [sound/sound.h](/adk-5.0-programmers-guide/readme/files/dir_15b7eb99384c20f55db7776b7b1ecdad/dir_7d99a5752ef00d9a9478541a793df8d8/dir_b95d7ee73b2963b5e37f0a7269e7a4c6/sound_8h.md) | | ADK SEC | - libsec2.so | - [sec/libsec.h](/adk-5.0-programmers-guide/readme/files/dir_16ebd1d2d73191fda1ea8e9cfc03e012/dir_8266e5c14dc74e90f33f07ca932afbf0/dir_b923322e571c7bbbdf8ca0235601f24c/dir_a4bd7de3367ab1637f06ad0eeada778b/dir_f7f8126e2ed8b92f6435c9f330cc6acf/libsec_8h.md) | | ADK EVT | - libevt.so | - evt/libevt.h | | ADK AGT | - libsvc\_tms.so |

- agt/svc\_tms.h
- agt/tms\_status.h

| | SDI CLIENT |

- libsdiclient.a
- libsdiprotocol.so

|

- sdiclient/sdi\_if.h
- sdiclient/sdiprotocol.h

| | SDI C++ API | - libsdiapi.so | - [sdiapi/sdi.h](/adk-5.0-programmers-guide/readme/files/dir_20ccae320a59b06ef6618c5b737d5c02/dir_5e53e51918e971c6ecb7778a0c977255/dir_e180e45849113f6ee3b1d48173f5e474/sdi_8h.md) | | INSTALLER | - libinstall.so | - installer/installer.hpp | ### Open Source libraries In addition to ADK APIs, applications can use the following provided Open Source libraries directly from within applications. | **Component** | **libraries** | **header** files | **Notes** | | ------------- | ------------------------------------ | ------------------------ | -------------------------- | | OpenSSL |

- libssl.so
- libcrypto.so

| | | | Compression | - libz.so | | | | CURL | - libcurl.so | | | | Expat | - libexpat.so | | | | SQLite | - libsqlite3.so | | | | Libxml |

- libxml.so
- libxml2.so

| all headers from libxml2 | added in OSS release 1.9.1 | ### Secondary Library dependencies Provided client libraries have additional dependencies that are usually not reflected to the applications and they are being resolved internally. Applications should only link to the above libraries, unless told differently. ### VOS3 Platform internal libraries {% hint style="warning" %} DO NOT USE INTERNAL LIBRARIES. The SDK contains additional libraries not listed above as supported ADK or Open Source libraries. These libraries do not expose public interfaces for applications and can be subject to change with new VOS3 releases. Please do not use these libraries directly! {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://sandbox-docs.verifone.com/adk-5.0-programmers-guide/readme/system_overview/pg_vos3_differences.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.