> For the complete documentation index, see [llms.txt](https://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://docs.verifone.com/adk-os-platform/readme/migration-guide.md).

# Migration Guide from Previous Platforms

This guide is for ADK application developers migrating existing VOS1/VOS2 applications to run on VOS3. It first summarizes platform-level differences and their impact on applications, then walks through porting guidelines for each ADK component.

## Differences to existing Platforms

The following table provides summary on changes compared to existing VOS2 platform and lists potential impact to applications.

<table><thead><tr><th width="40"></th><th width="159">Area</th><th>Change overview</th></tr></thead><tbody><tr><td>1</td><td>Packaging format and tools</td><td><p><strong>CHANGES:</strong></p><p>Control files are replaced by manifest (json) files describing the bundle and its packages.</p><p>Adapt package types to vos3 package types.</p><p><strong>IMPACTS:</strong><br>Users to repackage applications with the new VOS3 packaging tools.</p><p>Notes:</p><ul><li>Bundles targeting read-only partitions (system_ro &#x26; user_ro) are not allowed to target the same file location on device (i.e. conflict). Installation will fail and report this error.</li><li>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.</li></ul></td></tr><tr><td>2</td><td>Signing</td><td><p><strong>CHANGES:</strong><br>VOS3 will no longer support signing via signing cards, but only via online signing service.</p><p><strong>IMPACTS:</strong><br>Need to use VF online signing methods.</p></td></tr><tr><td>3</td><td>Compiler and Toolset</td><td><p><strong>CHANGES:</strong><br>VOS3 will use newer compiler and tools for building applications. This is to enable more recent C/C++ standards.</p><p><strong>IMPACTS:</strong><br>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.</p><p>Plan is to use gcc-Version 11.2.1 20220111 (GNU Toolchain for the Arm Architecture 11.2-2022.02 (arm-11.14))</p><ul><li>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 <a href="https://gcc.gnu.org/onlinedocs/libstdc++/manual/status.html#status.iso.2017">the library documentation</a>.</li><li>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. <strong>Important</strong>: Because the ISO C++20 standard is very recent, GCC's support is <strong>experimental</strong>.</li><li>Default is: #define __cplusplus 201703L, meaning C++17 standard.</li></ul></td></tr><tr><td>4</td><td>Linux Kernel</td><td><p><strong>CHANGES:</strong><br>VOS3 will use newer revisions of the Linux kernel. Also the Linux kernel revisions might be different between various products running VOS3.</p><p><strong>IMPACTS:</strong><br>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.</p></td></tr><tr><td>5</td><td>A/B Images</td><td><p><strong>CHANGES:</strong><br>VOS3 will support A/B scheme for supporting both seamless updates and allow fallback to previous image of the system.</p><p><strong>IMPACTS:</strong></p><p>A VOS3 device will contain two versions of the installed software:</p><ul><li>"active" version (currently running)</li><li>"fallback" version (previous version)</li></ul><p>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.</p><p>To take advantage of this versioning, the read/write data storage for applications will come in two forms:</p><ul><li>"versioned data" : this storage is kept in two versions and will be restored as it was when falling back ("/home/usr1/versioned_data")</li><li>"flash" : this storage is not versioned and is thus common to all versions ("/home/usr1/flash")</li></ul></td></tr><tr><td>6</td><td>Sysmode vs. VOS3 control panels</td><td><p><strong>CHANGES:</strong><br>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.). A minimum System Mode will remain for some low-level setting, diagnose and recovery management of the system.</p><p><strong>IMPACTS:</strong><br>No changes to applications expected, but operational differences.</p></td></tr><tr><td>7</td><td>No VOS1 Private APIs</td><td><p><strong>CHANGES:</strong><br>VOS3 will no longer support the VOS1/VOS2 private APIs. Older VOS1 services APIs have been deprecated and removed from VOS3 products.</p><p><strong>IMPACTS:</strong><br>Users need to revise their application code to use and comply with ADK APIs.</p></td></tr><tr><td>8</td><td>No VSS Support</td><td><p><strong>CHANGES:</strong><br>VOS3 will no longer support Verifone Secure Scripts (VSS).</p><p><strong>IMPACTS:</strong><br>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).</p></td></tr><tr><td>9</td><td>No direct key loading</td><td><p><strong>CHANGES:</strong><br>VOS3 will not support direct key loading APIs.</p><p><strong>IMPACTS:</strong><br>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).</p></td></tr><tr><td>10</td><td>Transparent Card Data and Card Reader Access</td><td><p><strong>CHANGES:</strong><br>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.</p><p><strong>IMPACTS:</strong><br>Users can change behavior if needed by using one of the following methods:</p><ul><li>Configuration of BIN ranges that can be excluded from card holder data protection.</li><li>Installation of extension regional/customer plug-ins that enable transparent card reader access</li><li>Installation of vos3-cards plugin that offers VOS2 APIs and card data access compatible to VOS2</li></ul></td></tr><tr><td>11</td><td>Flash partitions not using "synchronized I/O"</td><td><p><strong>CHANGES:</strong><br>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 <strong>not</strong> 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.</p><p><strong>IMPACTS:</strong></p><p>An application that needs a "file-based" transactional behavior (recommended):</p><ol><li>store information to a temporary files in the same filesystem (ie: add a '.tmp' extension)</li><li>when finished, close the temporary file (this will flush) and then rename it (ie: remove '.tmp' extension). On the same filesystem, rename is atomic.</li><li>on reboot/restart always remove all the temporary files (ie: remove all files with '.tmp')</li></ol><p>An application that really needs a "record-based" transactional behavior on a specific file can use one of the following methods:</p><ul><li>open the file with "O_DSYNC": all writing to this file will be synchronized</li><li>use fsync() on a file to synchronize</li></ul></td></tr><tr><td>12</td><td>No ADK-SEC 1.x compatibility layer</td><td><p><strong>CHANGES:</strong><br>VOS3 will no longer support a compatibility layer for ADK-SEC 1.x APIs.</p><p><strong>IMPACTS:</strong><br>Users still using ADK-SEC 1.x APIs need to revise their application code to use and comply with ADK 2.x APIs.</p><ul><li>ADK-SEC 1.x has been deprecated since ADK 4.5 and eventually removed in ADK 4.8.</li><li>ADK-SEC 2.x has provided a compatibility layer with ADK-SEC 1.x interface (libseccmd.h) for the time of migration.</li></ul><p>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.</p></td></tr><tr><td>13</td><td>OpenSSL Update</td><td><p><strong>CHANGES:</strong><br>VOS3 will update to OpenSSL v3 as this is the long-term supported release of OpenSSL. However, OpenSSL experienced some incompatible changes when coming from earlier revisions of the library.</p><p><strong>IMPACTS:</strong><br>Applications that use OpenSSL directly will need to adapt their application code to comply with changed APIs in OpenSSL v3.</p></td></tr><tr><td>14</td><td>ADK COM : PKCS#12 support</td><td><p><strong>CHANGES:</strong><br>Following ADK COM features will <strong>not</strong> be supported on VOS3:</p><ul><li>PKCS#12 files for Wifi Cert loading - replaced with VRK packages for secure loading of Wifi certs</li></ul><p><strong>IMPACTS:</strong></p><ul><li>Applications to load Wifi certs using VRK packages</li></ul></td></tr><tr><td>15</td><td>ADK COM : Analog Modem Support removed</td><td><p><strong>CHANGES:</strong></p><ul><li>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)</li></ul><p><strong>IMPACTS:</strong></p><ul><li>No application impact</li></ul></td></tr><tr><td>16</td><td><p>ADK COM: No</p><p>Dial-up Networking Profile (DUN)</p></td><td><p><strong>CHANGES:</strong></p><ul><li>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.</li></ul><p><strong>IMPACTS:</strong></p><ul><li>no deployments with dial-up mode supported.</li></ul></td></tr><tr><td>17</td><td>ADK COM : STunnel API support removed</td><td><p><strong>CHANGES:</strong></p><ul><li>STunnel APIs for SDI based external pinpads - replaced in SDI internally</li></ul><p><strong>IMPACTS:</strong></p><ul><li>No application impact</li><li>SDI external pinpad connection is transparent to applications.</li></ul></td></tr><tr><td>18</td><td>ADK COM: External Barcode reader</td><td><p><strong>CHANGES:</strong></p><ul><li>Support for HID based external barcode readers removed</li></ul><p><strong>IMPACTS:</strong></p><ul><li>no support of external barcode readers - use built-in camera or HW barcode decoder supported through ADK-GUI.</li></ul></td></tr><tr><td>19</td><td>Installation</td><td><p><strong>CHANGES:</strong></p><ul><li>Apps cannot be installed without reboot</li><li>new installer API</li></ul><p><strong>IMPACTS:</strong></p><ul><li>no impact on applications</li><li>Applications implementing own download mechanisms are recommended to use the new installer API</li></ul></td></tr></tbody></table>

## Porting Guidelines

### VOS1/2 Private APIs

No longer supported and deprecated since ADK 4.6. Please use ADK APIs instead.

### Application Packaging

#### **Convert VOS2 into VOS3 Package types**

The following table provides guidance on translating VOS2 package types into VOS3 packages.

<table><thead><tr><th width="175">VOS2 package type</th><th>VOS2 destination</th><th>Possible VOS3 package types</th><th>VOS3 destination</th><th>Notes</th></tr></thead><tbody><tr><td><strong>user</strong></td><td>/home/&#x3C;user>/</td><td>user_ro</td><td>/home/&#x3C;user>/</td><td></td></tr><tr><td><strong>userflash</strong></td><td>/mnt/flash/userdata/&#x3C;user>/</td><td><p>system_versioned_data</p><p>system_data</p><p>user_versioned_data</p><p>user_data</p></td><td><p>/mnt/sysdata/versioned/&#x3C;user>/</p><p>/mnt/sysdata/data/&#x3C;user>/</p><p>/mnt/appdata/versioned/&#x3C;user>/</p><p>/mnt/appdata/data/&#x3C;user>/</p></td><td></td></tr><tr><td><strong>userflashshare</strong></td><td>/mnt/flash/userdata/share/</td><td><p>share_system_versioned_data</p><p>share_user_versioned_data</p><p>share_all_versioned_data</p></td><td><p>/mnt/sysdata/versioned/share/</p><p>/mnt/appdata/versioned/share/</p><p>/mnt/appdata/versioned/globalshare/</p></td><td></td></tr><tr><td><strong>userfont</strong></td><td>/mnt/flash/system/fonts/</td><td>font_ro</td><td>/usr/share/fonts/</td><td></td></tr><tr><td><strong>config</strong></td><td>/etc/config/</td><td><p>partial support</p><p>(sys_&#x3C;> can use system_ro)</p><p>(usr&#x3C;X> can use user_ro)</p></td><td></td><td></td></tr><tr><td><strong>flashconfig</strong></td><td>/mnt/flash/etc/config/</td><td><p>share_system_versioned_data</p><p>share_user_versioned_data</p><p>share_all_versioned_data</p></td><td><p>/mnt/sysdata/versioned/share/</p><p>/mnt/appdata/versioned/share/</p><p>/mnt/appdata/versioned/globalshare/</p></td><td>Global config is: /mnt/appdata/versioned/globalshare/etc/config/</td></tr><tr><td><strong>vss</strong></td><td>/etc/vss/&#x3C;user>/</td><td>not supported</td><td></td><td></td></tr><tr><td><strong>unsigned</strong></td><td>/mnt/flash/userdata/&#x3C;user>/unsigned/</td><td>user_unsigned_data</td><td>/mnt/appdata/data/&#x3C;user>/unsigned/</td><td></td></tr></tbody></table>

### **Application MAC Manifests**

On VOS3 systems 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:

* /home/usr\*/www
* /home/sys\_\*/www

Manifest file names should end with **.mft**

### **VHQ Manifest**

VOS3 still requires a VHQ manifest for dl files, when uploading as part of a reference set.

* Renamed to 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="danger" %}
**MAC is a mandatory component on VOS3.**

Any application on VOS3 needs to provide a corresponding MAC manifest file to configure the application 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 their visibility.

![](https://3462522456-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIfFmiYwINerMPYjzrAC6%2Fuploads%2Fgit-blob-b16df6cc183447e440b674fdae24d3d272a99b4d%2F0.png?alt=media)

#### **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()*** - run application by it's name in manifest file
* ***sysLaunchAppid()*** - 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) | Stop applications    |

#### **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 VOS1 versions.

MAC is looking for manifest files in the following locations:

* /home/usr\*/www
* /home/sys\_\*/www

<details>

<summary>MAC manifest example</summary>

```ini
[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
```

</details>

{% hint style="warning" %}
MAC manifest is not related to the installer package manifest.
{% endhint %}

<details>

<summary>Sample MAC application package</summary>

```
mac_sample
├── mac_demo1
│   ├── mac_demo1 Application 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
```

</details>

### 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 port 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()
  * com\_IBeaconSetAdvertisement()
  * com\_IBeaconStartAdvertisement()
  * com\_IBeaconStopAdvertisement()
* new APIs for Eddystone Beacon - recommended to be used with VOS3
  * com\_EddystoneURLGetAdvertisementExt()
  * com\_EddystoneURLSetAdvertisementExt()

#### **Communication and Network Descriptors**

VOS3 continues to use the same format and parameter for ADK connection and network profiles.\
Exception: connection and network profiles for modem (MDM\_INT, BT\_DUN) and external barcode reader (BC\_READER)

#### **Asymmetric customer keys and pre-loaded authentication key for TLS/EAP authentication**

In contradiction to VOS1 and VOS2, VOS3 **does not support** certificates and asymmetric keys stored in PKCS#12 container files.

The system now supports secure loading of customer keys plus associated certificate using VRKv2. The loaded key + certificate will be stored securely in the system's secure key store.\
When using ADK-COM API's, it can be referenced by the SSL\_OWN\_CERT and SSL\_OWN\_KEY profile parameters with string value "vault:\<keyname>" in the related connection profile for TLS or network profile for WiFi or LAN. The \<keyname> 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 (i.e. without any additional key 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**

Communication 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 troubleshooting.

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 directory of the user running the application. Depending on the manifest configuration this is
  * /home/\<user>/www/\<resourcedir>
  * /home/\<user>/www/\<appdir>/\<resourcedir>
* \<appdir> depends on MAC manifest configuration
* \<resourcedir> 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:

```json
{
   "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"]
}
```

* group "share" shares the resource files with all users. Depending on context, group "usr1sys" ("usr2sys" for usr2, ...) may also be used.

#### **Video files**

* As on VOS1/VOS2 mplayer is used for playing videos. The supported video formats depend on those supported by mplayer.
* supported video formats: Please check the ADK programmers guide for details

#### **Barcode scanning**

* Barcode scanning works the same as on VOS1/VOS2 (use \<input type="barcode" ....>)

#### **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](http://dev.cgateway.verifone.com/), [test.cgateway.verifone.com](http://test.cgateway.verifone.com/), [staging1.cgateway.verifone.com](http://staging1.cgateway.verifone.com/), [cgateway.verifone.com](http://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)\
  Note: 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 still be able to use version 3.0.50 (VOS1/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 (VOS1/VOS2 and VOS3)
* VOS3 platform uses a different package format and installation location on target
* Whereas VOS1/VOS2 has used global folder /etc/config/proxy, on VOS3 configuration files are looked up under /home/usr\<X>/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 usr\<X>sys with type user\_ro (instead of VOS1/VOS2, which 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 VOS1/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() or EMV\_CTLS\_fetchTxnTags() 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 not use 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: 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: 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 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: 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 VOS1/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:

**Operations: ENC=secEncryptData, DEC=secDecryptData, SIG=secSign, VFY=secVerify, PIN=secRetrieveEncryptedPIN, UPD=secUpdateKey**

**Supported Modules and Operations by Platform:**

| **Engine**                                    | **VOS1**                                                                                                            | **VOS2**                                                                                                            | **VOS3**                                     | **Notes**                                                                                                                                                     |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Verishield Security Scripts (VSS)             | **VSS**: all operation                                                                                              | **VSS**: all operation                                                                                              | --                                           | <ul><li>VOS3: replaced with VCCI, new Key Mgmt APIs</li></ul>                                                                                                 |
| Verifone Customizable Crypto Interface (VCCI) | --                                                                                                                  | --                                                                                                                  | X                                            | <ul><li>requires a Verifone signed SDI plug-in for VCCI extensions</li></ul>                                                                                  |
| Triple-DES Master-/Session-Key                | <p><strong>IPPmsk</strong>: PIN, SIG, UPD</p><p>UPD key in GISKE format</p>                                         | <p><strong>IPPmsk</strong>: PIN, SIG, UPD</p><p>UPD key in GISKE format</p>                                         | **TDES-MSK**: PIN, ENC, DEC, SIG, VFY, UPD   | <ul><li>Master-Session Scheme Support, but no support for older IPP GISKE keyblock format</li><li>PIN: SDI will provide PAN for ISO format #0 or #3</li></ul> |
| Triple-DES Fixed Key                          | --                                                                                                                  | --                                                                                                                  | **TDES-FIXED**: ENC, DEC, SIG, VFY           | <ul><li>NOTE: PIN encryption with fixed keys not allowed!</li></ul>                                                                                           |
| Triple DES-DUKPT                              | <p><strong>IPPdukpt</strong>: PIN</p><p><strong>ADE</strong>: ENC</p><p><strong>SREDMAC</strong>: SIG, VFY, UPD</p> | <p><strong>IPPdukpt</strong>: PIN</p><p><strong>ADE</strong>: ENC</p><p><strong>SREDMAC</strong>: SIG, VFY, UPD</p> | **TDES-DUKPT**: PIN, ENC, DEC, SIG, VFY, UPD | <ul><li>UPD=manual increment of Key Serial Number (KSN)</li><li>PIN: SDI will provide PAN for ISO format #0 or #3</li></ul>                                   |
| AES - DUKPT                                   | --                                                                                                                  | **AES**: PIN, ENC, DEC, SIG, VFY, UPD                                                                               | **AES-DUKPT**: PIN, ENC, DEC, SIG, VFY, UPD  | <ul><li>UPD=manual increment of Key Serial Number (KSN)</li><li>PIN: PIN-Block Format #4 only</li><li>Data: ECB and CBC mode</li><li>MAC: CMAC only</li></ul> |
| RSA Operations                                | **RSA**: ENC, DEC, SIG, VFY                                                                                         | **RSA**: ENC, DEC, SIG, VFY                                                                                         | **RSA**: ENC, DEC, SIG, VFY                  | <ul><li>allows use of AUTHN warrantied key</li></ul>                                                                                                          |
| SDI Secured File Storage (Crypto-RW)          | x                                                                                                                   | x                                                                                                                   | TBD                                          | <ul><li>invalidates file content on tamper (no decryption possible)</li></ul>                                                                                 |
| Verishield Protect (VSP/VCL)                  | x                                                                                                                   | x                                                                                                                   | <p>TBD (VCCI based)<br></p>                  | <ul><li>configured separately outside of SDI, not a module name</li></ul>                                                                                     |

### **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**\
Note: 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 to their intended usage. Keys with improper settings will be rejected by operations.
{% endhint %}

**Sample Security Configuration File**

The below sample config demonstrates large part of available options for the security configuration.

{% hint style="info" %}
**SDI Default Security Configuration**\
Note: This sample configuration is at the same time the SDI default configuration - Applications can make use of the provided sample hosts but need to load their payment keys according to the provided key names in this sample configuration.
{% endhint %}

Any other custom configuration will require loading a custom sccfg.json file to take precedence over the pre-installed default configuration.

The table spells out the sample host names used in the sample config file and details the applicable operations to that host as well as listing the possible attributes.

The Sample key payloads are just a reference for use with development devices only and are not applicable for production use.

|

Sample Hostname\
**(module name + \[PIN|MAC|DATA ])**

\| Sample Key Payloads for APP-DEV devices | Operations | Attributes(bold: attributes used in sample config) | | -------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | TDES\_DUKPT\_PIN | Neo: VRKv2-neo-TDES-DUKPT1.json (name 'DUKPT\_1') |

PIN\
UPD=KSN incrementation

\| KSNincrementation: **BY\_OPERATION**, BY\_API | | TDES\_DUKPT\_DATA | Neo: VRKv2-neo-TDES-DUKPT1.json (name 'DUKPT\_1') |

ENC\
UPD=KSN incrementation<br>

|

Padding: NONE, ZERO, **PKCS7**, ISO10126, X923, ISO7816

encMode: **CBC**, ECB

IVType: NONE, **ZERO**, RANDOM, USER\_DEFINED

KSNincrementation: **BY\_OPERATION**, BY\_API

keyVariant: **request**, response, both

\| | TDES\_DUKPT\_MAC | Neo: VRKv2-neo-TDES-DUKPT1.json (name 'DUKPT\_1') |

SIG, VFY\
UPD=KSN incrementation

|

Padding: NONE, ZERO, **PKCS7**, ISO10126, X923, ISO7816

Algo: **X99**, X919

IVType: NONE, **ZERO**, RANDOM, USER\_DEFINED

KSNincrementation: **BY\_OPERATION**, BY\_API

keyVariant: **request**, response, both

\| | AES\_DUKPT\_PIN | Neo: VRKv2-Neo-AES-DUKPT\_1.json (name 'AES-DUKPT\_1') |

PIN\
UPD=KSN incrementation

\| KSNincrementation: **BY\_OPERATION**, BY\_API | | AES\_DUKPT\_DATA | Neo: VRKv2-Neo-AES-DUKPT\_1.json (name 'AES-DUKPT\_1') |

ENC\
UPD=KSN incrementation

|

Padding: **NONE**, ZERO, PKCS7, ISO10126, X923, ISO7816

encMode: **CBC**, ECB

IVType: NONE, **ZERO**, RANDOM, USER\_DEFINED

KSNincrementation: **BY\_OPERATION**, BY\_API

keyVariant: **request**, response, both

\| | AES\_DUKPT\_MAC | Neo: VRKv2-Neo-AES-DUKPT\_1.json (name 'AES-DUKPT\_1') |

SIG, VFY\
UPD=KSN incrementation

|

Padding: NONE, ZERO, **PKCS7**, ISO10126, X923, ISO7816

Algo: **CMAC**

IVType: NONE, **ZERO**, RANDOM, USER\_DEFINED

KSNincrementation: **BY\_OPERATION**, BY\_API

keyVariant: **request**, response, both

\| | TDES\_MSK\_PIN | Neo: VRKv2-Neo-TDEA-MK\_1.json (name 'TDEA-MK\_1') |

PIN\
UPD=load session key

\| | | TDES\_MSK\_DATA | Neo: VRKv2-Neo-TDEA-MK\_1.json (name 'TDEA-MK\_1') |

ENC\
UPD=load session key

|

Padding: **NONE**, ZERO, PKCS7, ISO10126, X923, ISO7816

encMode: **CBC**, ECB

IVType: NONE, **ZERO**, RANDOM, USER\_DEFINED

\| | TDES\_MSK\_MAC | Neo: VRKv2-Neo-TDEA-MK\_1.json (name 'TDEA-MK\_1') |

SIG, VFY\
UPD=load session key

|

Padding: NONE, ZERO, **PKCS7**, ISO10126, X923, ISO7816

Algo: **X99**, X919

IVType: NONE, **ZERO**, RANDOM, USER\_DEFINED

\| | TDES\_FIXED\_DATA | Neo: VRKv2-Neo-TDEA-DATA\_15.json (name 'TDEA-DATA\_15') | ENC |

Padding: **NONE**, ZERO, PKCS7, ISO10126, X923, ISO7816

encMode: **CBC**, ECB

IVType: NONE, **ZERO**, RANDOM, USER\_DEFINED

\| | TDES\_FIXED\_MAC | Neo: VRKv2-Neo-TDEA-MAC\_17.json (name 'TDEA-MAC\_17') | SIG, VFY |

Padding: NONE, ZERO, **PKCS7**, ISO10126, X923, ISO7816

Algo: **X99**, X919

IVType: NONE, **ZERO**, RANDOM, USER\_DEFINED

\| | RSA | Neo: VFI\_AUTHN\_RSA |

ENC, DEC,\
SIG, VFY

|

Padding: NONE, **PKCS1**, PKCS1\_OAEP

hashType: SHA1, SHA224, **SHA256**, SHA384, SHA512

calcHash: **yes**, no

getKeyDataFormat: **PEM**, DER, PRINT

Note: padding PKCS1\_OAEP, hashType and calcHash are only valid for SIG, VFY operation

|

<details>

<summary>Detailed Sample configuration file (sccfg.json)</summary>

```json
{
  "adksecconfig": 
  {
    "description": "SDI/ADK-SEC sample configuration for Neo devices. Note: no VSS supported",
	"hosts":
    [
      {
        "name": "TDES_DUKPT_PIN",
        "description": "TDES DUKPT for PIN",
        "scheme": "scheme_TDES_DUKPT_PIN",
        "module": "TDES-DUKPT"
      },
	  {
        "name": "05",
        "description": "same as TDES-DUKPT-PIN: compatibility with old name scheme",
        "scheme": "scheme_TDES_DUKPT_PIN",
        "module": "TDES-DUKPT"
      },
      {
        "name": "TDES_DUKPT_DATA",
        "description": "TDES DUKPT for data encryption (aka ADE)",
        "scheme": "scheme_TDES_DUKPT_DATA",
        "module": "TDES-DUKPT"
      },
      {
        "name": "07",
        "description": "same as TDES-DUKPT-DATA: compatibility with old name scheme",
        "scheme": "scheme_TDES_DUKPT_DATA",
        "module": "TDES-DUKPT"
      },
      {
        "name": "ADE-DUKPT",
        "description": "same as TDES-DUKPT-DATA: compatibility with old name scheme",
        "scheme": "scheme_TDES_DUKPT_DATA",
        "module": "TDES-DUKPT",
        "settings":
        {
          "padding": "NONE"
        }
      },
      {
        "name": "TDES_DUKPT_MAC",
        "description": "TDES DUKPT mac calculation/verification",
        "scheme": "scheme_TDES_DUKPT_MAC",
        "module": "TDES-DUKPT"
      },
      {
        "name": "AES_DUKPT_PIN",
        "description": "AES DUKPT for PIN",
        "scheme": "scheme_AES_DUKPT_PIN",
        "module": "AES-DUKPT"
      },
      {
        "name": "AES_DUKPT_DATA",
        "description": "AES DUKPT for data encryption",
        "scheme": "scheme_AES_DUKPT_DATA",
        "module": "AES-DUKPT"
      },
      {
        "name": "AES_DUKPT_MAC",
        "description": "AES DUKPT mac calculation/verification",
        "scheme": "scheme_AES_DUKPT_MAC",
        "module": "AES-DUKPT"
      },
	  {
        "name": "TDES_MSK_PIN",
        "description": "TDES Master-Session-Key for PIN",
        "scheme": "scheme_TDES_MSK_PIN",
        "module": "TDES-MSK"
      },
      {
        "name": "TDES_MSK_DATA",
        "description": "TDES Master-Session-Key for data encryption",
        "scheme": "scheme_TDES_MSK_DATA",
        "module": "TDES-MSK"
      },
      {
        "name": "TDES_MSK_MAC",
        "description": "TDES Master-Session-Key for MAC calculation/verification",
        "scheme": "scheme_TDES_MSK_MAC",
        "module": "TDES-MSK"
      },
      {
        "name": "TDES_FIXED_DATA",
        "description": "TDES Fixed-Key for data encryption",
        "scheme": "scheme_TDES_FIXED_DATA",
        "module": "TDES-FIXED"
      },
      {
        "name": "TDES_FIXED_MAC",
        "description": "TDES Fixed-Key for MAC calculation/verification",
        "scheme": "scheme_TDES_FIXED_MAC",
        "module": "TDES-FIXED"
      },
      {
        "name": "RSA",
        "description": "RSA public and private key operations",
        "module": "RSA",
        "scheme": "scheme_RSA"
      }
    ],

    "serviceCfg":
    {
      "secSchemes":
      [
        {
          "name": "scheme_TDES_DUKPT_ANY",
          "settings":
          {
            "KeyAddressTable":
            [
			  {"description": "| 1  | 2  | 3  | 4  | 5  | 6  | 7  | 8 |  9 | 10 | <- KeySetId : array with assignments of key set IDs to key slots"},
              {"retrieveEncPIN": ["DUKPT_1"]},
              {"encryptData": ["DUKPT_1"]},
              {"sign": ["DUKPT_1"]}
            ],
			"description_KeyManagementType": "??",
            "KeyManagementType": "DUKPT",
			"description_padding": "padding for Data encryption and MAC: PKCS7, ZERO, NONE, ...",
            "padding": "PKCS7",
			"description_algo": "MAC algorithm: X99, X919",
			"algo": "X99"
          }
        },
        {
          "name": "scheme_TDES_DUKPT_PIN",
          "settings":
          {
            "KeyAddressTable":
            [
			  {"description": "| 1  | 2  | 3  | 4  | 5  | 6  | 7  | 8 |  9 | 10 | <- KeySetId : array with assignments of key set IDs to key slots"},
              {"retrieveEncPIN": ["DUKPT_1"]}
            ]
		  }
        },
        {
          "name": "scheme_TDES_DUKPT_DATA",
          "settings":
          {
            "KeyAddressTable":
            [
			  {"description": "| 1  | 2  | 3  | 4  | 5  | 6  | 7  | 8 |  9 | 10 | <- KeySetId : array with assignments of key set IDs to key slots"},
              {"encryptData": ["DUKPT_1"]}
            ],
			"description_padding": "padding for Data encryption and MAC: PKCS7, ZERO, NONE, ...",
            "padding": "PKCS7",
			"description_encMode": "encryption mode: MODE_CBC, MODE_ECB",
			"encMode": "MODE_CBC",
			"description_IVType": "initial vector type: ZERO, RANDOM, ...",
			"IVType":  "ZERO"
          }
        },
        {
          "name": "scheme_TDES_DUKPT_MAC",
          "settings":
          {
            "KeyAddressTable":
            [
			  {"description": "| 1  | 2  | 3  | 4  | 5  | 6  | 7  | 8 |  9 | 10 | <- KeySetId : array with assignments of key set IDs to key slots"},
              {"verify": ["DUKPT_1"]},
              {"sign": ["DUKPT_1"]}
            ],
			"description_padding": "padding for Data encryption and MAC: PKCS7, ZERO, NONE, ...",
            "padding": "PKCS7",
			"description_algo": "MAC algorithm: X99, X919",
			"algo": "X99"
          }
        },
        {
          "name": "scheme_AES_DUKPT_PIN",
          "settings":
          {
            "KeyAddressTable":
            [
			  {"description": "| 1  | 2  | 3  | 4  | 5  | 6  | 7  | 8 |  9 | 10 | <- KeySetId : array with assignments of key set IDs to key slots"},
              {"retrieveEncPIN": ["AES-DUKPT_1"]}
            ]
		  }
        },
        {
          "name": "scheme_AES_DUKPT_DATA",
          "settings":
          {
            "KeyAddressTable":
            [
			  {"description": "| 1  | 2  | 3  | 4  | 5  | 6  | 7  | 8 |  9 | 10 | <- KeySetId : array with assignments of key set IDs to key slots"},
              {"encryptData": ["AES-DUKPT_1"]}
            ],
			"description_padding": "padding for Data encryption and MAC: PKCS7, ZERO, NONE, ...",
            "padding": "NONE",
			"description_encMode": "encryption mode: MODE_CBC, MODE_ECB",
			"encMode": "MODE_CBC",
			"description_IVType": "initial vector type: ZERO, RANDOM, ...",
			"IVType":  "ZERO"
          }
        },
        {
          "name": "scheme_AES_DUKPT_MAC",
          "settings":
          {
            "KeyAddressTable":
            [
			  {"description": "| 1  | 2  | 3  | 4  | 5  | 6  | 7  | 8 |  9 | 10 | <- KeySetId : array with assignments of key set IDs to key slots"},
              {"verify": ["AES-DUKPT_1"]},
              {"sign": ["AES-DUKPT_1"]}
            ],
			"description_padding": "padding for Data encryption and MAC: PKCS7, ZERO, NONE, ...",
            "padding": "PKCS7",
			"description_algo": "MAC algorithm: CMAC",
			"algo": "CMAC"
          }
        },
       {
          "name": "scheme_TDES_MSK_PIN",
          "settings":
          {
			"KeyAddressTable":
			[
				{"description":
					[
						"| 1 |  2  | 3 |<- KeySetId (1 set)",
						"NOTES: - different containers with separate key index for ENC/DEC, SIGN/VERIFY, PIN",
						"          - each key set represents an session key to be used",
						"       - Keys Store:",
						"          - session keys in slot TDEA-SK-PIN",
						"          - master key in slot TDEA-MK_1",
						"       - Add/Update Master key (encrypted with existing Master Key)",
						"          - Not supported for Neo platform",


						"       - Add/Update Session Key (encrypted with existing Master Key)",
						"          - SETKEYSET operation: select Session Key slot (Key Set Id) - Key Set Id references container based on key type",
						"                                 select Master Key slot used as transport key (Master Key Set Id) - (Key Set Id in 'updateKey' attribute)",
						"          - UPDATAEKEY operation: KeyType=KEY_TYPE_PPK (PIN), KEY_TYPE_MGK (SIGN), KEY_TYPE_MVK (VERIFY), KEY_TYPE_DEK (ENC), KEY_TYPE_DDK (DEC)",
						"       - Protecting Master keys: ",
						"          - Master keys loaded via customRKL shall not be updateable - put the corresponding slots into to 'updateKey_protected'"
					]
				},
		        {"retrieveEncPIN": ["TDEA-SK-PIN"]},
				{"updateKey": ["TDEA-MK_1"]},
				{"updateKey_protected": ["TDEA-MK_1"]}
			]
		  }
        },
        {
          "name": "scheme_TDES_MSK_DATA",
          "settings":
          {
			"KeyAddressTable":
			[
				{"description":
					[
						"| 1 |  2  | 3 |<- KeySetId (1 set)",
						"NOTES: - different containers with separate key index for ENC/DEC, SIGN/VERIFY, PIN",
						"          - each key set represents an session key to be used",
						"       - Keys Store:",
						"          - session keys in slot TDEA-SK-DATA",
						"          - master key in slot TDEA-MK_1",
						"       - Add/Update Master key (encrypted with existing Master Key)",
						"          - Not supported for Neo platform",


						"       - Add/Update Session Key (encrypted with existing Master Key)",
						"          - SETKEYSET operation: select Session Key slot (Key Set Id) - Key Set Id references container based on key type",
						"                                 select Master Key slot used as transport key (Master Key Set Id) - (Key Set Id in 'updateKey' attribute)",
						"          - UPDATAEKEY operation: KeyType=KEY_TYPE_PPK (PIN), KEY_TYPE_MGK (SIGN), KEY_TYPE_MVK (VERIFY), KEY_TYPE_DEK (ENC), KEY_TYPE_DDK (DEC)",
						"       - Protecting Master keys: ",
						"          - Master keys loaded via customRKL shall not be updateable - put the corresponding slots into to 'updateKey_protected'"
					]
				},
				{"encryptData": ["TDEA-SK-DATA"]},
				{"updateKey": ["TDEA-MK_1"]},
				{"updateKey_protected": ["TDEA-MK_1"]}
			],
			"description_padding": "padding for Data encryption and MAC: PKCS7, ZERO, NONE, ...",
            "padding": "NONE",
			"description_encMode": "encryption mode: MODE_CBC, MODE_ECB",
			"encMode": "MODE_CBC",
			"description_IVType": "initial vector type: ZERO, RANDOM, ...",
			"IVType":  "ZERO"
          }
        },
        {
          "name": "scheme_TDES_MSK_MAC",
          "settings":
          {
			"KeyAddressTable":
			[
				{"description":
					[
						"| 1 |  2  | 3 |<- KeySetId (1 set)",
						"NOTES: - different containers with separate key index for ENC/DEC, SIGN/VERIFY, PIN",
						"          - each key set represents an session key to be used",
						"       - Keys Store:",
						"          - session keys in slot TDEA-SK-MAC",
						"          - master key in slot TDEA-MK_1",
						"       - Add/Update Master key (encrypted with existing Master Key)",
						"          - Not supported for Neo platform",


						"       - Add/Update Session Key (encrypted with existing Master Key)",
						"          - SETKEYSET operation: select Session Key slot (Key Set Id) - Key Set Id references container based on key type",
						"                                 select Master Key slot used as transport key (Master Key Set Id) - (Key Set Id in 'updateKey' attribute)",
						"          - UPDATAEKEY operation: KeyType=KEY_TYPE_PPK (PIN), KEY_TYPE_MGK (SIGN), KEY_TYPE_MVK (VERIFY), KEY_TYPE_DEK (ENC), KEY_TYPE_DDK (DEC)",
						"       - Protecting Master keys: ",
						"          - Master keys loaded via customRKL shall not be updateable - put the corresponding slots into to 'updateKey_protected'"
					]
				},
				{"sign": ["TDEA-SK-MAC"]},
				{"verify": ["TDEA-SK-MAC"]},
				{"updateKey": ["TDEA-MK_1"]},
				{"updateKey_protected": ["TDEA-MK_1"]}
			],
			"description_padding": "padding for Data encryption and MAC: PKCS7, ZERO, NONE, ...",
            "padding": "PKCS7",
			"description_algo": "MAC algorithm: X99, X919",
			"algo": "X99"
          }
        },
        {
          "name": "scheme_TDES_FIXED_DATA",
          "settings":
          {
            "KeyAddressTable":
            [
                {"description":
                    [
                        "| 1 |  2  | 3 |<- KeySetId (1 set)",
                        "NOTES: - different containers with separate key index for ENC/DEC, SIGN/VERIFY, PIN",
                        "          - each key set represents an fixed key to be used",
                        "       - Keys Store:",
                        "          - fixed keys in slot 1"
                    ]
                },
                {"encryptData": ["TDEA-DATA_15"]}
            ],
            "description_padding": "padding for Data encryption and MAC: PKCS7, ZERO, NONE, ...",
            "padding": "NONE",
            "description_encMode": "encryption mode: MODE_CBC, MODE_ECB",
            "encMode": "MODE_CBC",
            "description_IVType": "initial vector type: ZERO, RANDOM, ...",
            "IVType":  "ZERO"
          }
        },
        {
          "name": "scheme_TDES_FIXED_MAC",
          "settings":
          {
            "KeyAddressTable":
            [
                {"description":
                    [
                        "| 1 |  2  | 3 |<- KeySetId (1 set)",
                        "NOTES: - different containers with separate key index for ENC/DEC, SIGN/VERIFY, PIN",
                        "          - each key set represents a fixed key to be used",
                        "       - Keys Store:",
                        "          - session keys in slot 1"
                    ]
                },
                {"sign": ["TDEA-MAC_17"]},
                {"verify": ["TDEA-MAC_17"]}
            ],
            "description_padding": "padding for Data encryption and MAC: PKCS7, ZERO, NONE, ...",
            "padding": "PKCS7",
            "description_algo": "MAC algorithm: X99, X919",
            "algo": "X99"
          }
        },
        {
          "name": "scheme_RSA",
          "settings":
          {
            "KeyAddressTable":
            [
              {"description": "| 1 | <- KeySetId : array with assignments of key set IDs to key name alias"},
              {"encryptData": ["VFI_AUTHN_RSA"]},
              {"decryptData": ["VFI_AUTHN_RSA"]},
              {"sign": ["VFI_AUTHN_RSA"]},
              {"verify": ["VFI_AUTHN_RSA"]}
            ],
			"description_padding": "padding for Data encryption and MAC: PKCS7, ZERO, NONE, ...",
            "padding": "PKCS1",
			"description_hashtype": "hash type: SHA256, ...",
            "hashType": "SHA256",
			"description_calcHash": "calculate hash internally or provide as input parameter",
            "calcHash": "yes",
			"description_getKeyDataFormat": "format of the returned public key: PEM, DER, ...",
            "getKeyDataFormat":"PEM"
          }
        }
      ]
    }
  }
}
```

</details>

**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 direct key loading, but VRK key loading is the default key loading mechanism.

However, if customizations are required, VOS3 provides new mechanisms for that purpose

* Verifone SDI plug-ins
* 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.

Please work with Verifone support on specific requirements and implementation plans.
{% endhint %}

### ADK SYS (System Information and Status-bar)

#### **API compatibility**

Following APIs will not be provided on VOS3 since those have duplicate functions under ADK-PM. Please use ADK-PM APIs on VOS3 going forward.

| **ADK-SYS API** | **Alternate ADK-PM API** | **Notes**                                                  |                                                                                     |
| --------------- | ------------------------ | ---------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| SYS\_INFO\_API  | sysReboot()              | VFI\_SYS\_PM\_API vfisyspmError sys\_Reboot(int flags);    | if flags==PM\_SUPPRESS\_CRITICAL\_SECTION then the Critical section will be ignored |
| SYS\_INFO\_API  | sysSleep()               | VFI\_SYS\_PM\_API vfisyspmError sys\_Sleep(int flags);     |                                                                                     |
| SYS\_INFO\_API  | sysDeepSleep()           | VFI\_SYS\_PM\_API vfisyspmError sys\_DeepSleep(int flags); |                                                                                     |
| SYS\_INFO\_API  | sysHibernate()           | VFI\_SYS\_PM\_API vfisyspmError sys\_Hibernate(int flags); |                                                                                     |
| SYS\_INFO\_API  | sysShutdown()            | VFI\_SYS\_PM\_API vfisyspmError sys\_Shutdown(int flags);  |                                                                                     |
| SYS\_INFO\_API  | sysRebootDock()          |                                                            | API will be implemented later                                                       |

Not supported APIs will return **SYS\_ERR\_UNSUPPORTED**.

**System Properties**

Same as VOS1/VOS2\
**API:** sysinfo/sysinfo.h\
**Library:** libvfisysinfo.so

<details>

<summary>Supported SYS Properties on all platforms</summary>

| **Int type property name**              | **VOS1** | **VOS2** | **VOS3** |
| --------------------------------------- | -------- | -------- | -------- |
| SYS\_PROP\_BATTERY\_AVAILABLE           | -        | +        | +        |
| SYS\_PROP\_BATTERY\_STATUS\_OK          | -        | +        | +        |
| SYS\_PROP\_BATTERY\_DEVICE              | +        | +        | +        |
| SYS\_PROP\_BATTERY\_VOLTAGE             | -        | +        | +        |
| SYS\_PROP\_BATTERY\_CAPACITY            | -        | +        | +        |
| SYS\_PROP\_BATTERY\_CHARGE\_LEVEL       | -        | +        | +        |
| SYS\_PROP\_BATTERY\_CHARGING            | -        | +        | +        |
| SYS\_PROP\_BATTERY\_FULL                | -        | +        | +        |
| SYS\_PROP\_BATTERY\_TEMP                | -        | +        | +        |
| SYS\_PROP\_BATTERY\_CURRENT             | -        | +        | +        |
| SYS\_PROP\_BATTERY\_CRITICAL            | -        | +        | +        |
| SYS\_PROP\_BATTERY\_LOW                 | -        | +        | +        |
| SYS\_PROP\_BATTERY\_NORMAL              | -        | +        | +        |
| SYS\_PROP\_BATTERY\_TECHNOLOGY          | -        | +        | +        |
| SYS\_PROP\_BATTERY\_FCC                 | -        | +        | +        |
| SYS\_PROP\_BATTERY\_SOH                 | -        | +        | +        |
| SYS\_PROP\_BATTERY\_CHARGE\_IN\_SLEEP   | -        | +        | +        |
| SYS\_PROP\_BATTERY\_CALIBRATION         | -        | +        | +        |
| SYS\_PROP\_BATTERY\_TYPE                | -        | +        | +        |
| SYS\_PROP\_BATTERY\_CHARGE\_MODE        | -        | +        | +        |
| SYS\_PROP\_CHARGE\_CYCLE\_COUNT         | -        | +        | +        |
| SYS\_PROP\_UX100\_AVAILABLE             | +        | -        | -        |
| SYS\_PROP\_UX100\_OPERATIONAL\_MODE     | +        | -        | -        |
| SYS\_PROP\_UX100\_BACKLIGHT             | +        | -        | -        |
| SYS\_PROP\_UX400\_AVAILABLE             | +        | -        | -        |
| SYS\_PROP\_UX115\_UNIT                  | +        | -        | -        |
| SYS\_PROP\_UX\_UNIT                     | +        | -        | -        |
| SYS\_PROP\_INTERNAL\_BATTERY\_STATUS    | +        | +        | +        |
| SYS\_PROP\_INTERNAL\_BATTERY\_VOLTAGE   | +        | +        | +        |
| SYS\_PROP\_DOCKING\_STATUS              | +        | +        | -        |
| SYS\_PROP\_DOCK\_SUPPORT                | +        | +        | -        |
| SYS\_PROP\_USB1\_MODE                   | -        | +        | +        |
| SYS\_PROP\_USB2\_MODE                   | -        | +        | +        |
| SYS\_PROP\_USB1\_CONFIGURABLE           | -        | +        | -        |
| SYS\_PROP\_USB2\_CONFIGURABLE           | -        | +        | -        |
| SYS\_PROP\_USB1\_DEFAULT                | -        | +        | +        |
| SYS\_PROP\_USB2\_DEFAULT                | -        | +        | +        |
| SYS\_PROP\_USB1\_CHARGE                 | -        | +        | -        |
| SYS\_PROP\_USB2\_CHARGE                 | -        | +        | -        |
| SYS\_PROP\_USB\_HIGH\_POWER\_MODE       | -        | +        | -        |
| SYS\_PROP\_PRINTER\_AVAILABLE           | +        | +        | -        |
| SYS\_PROP\_POWER\_STATUS                | +        | +        | -        |
| SYS\_PROP\_POWER\_ON                    | -        | +        | -        |
| SYS\_PROP\_CHARGE\_ON\_SAVING           | -        | +        | -        |
| SYS\_PROP\_KEYBOARD\_BEEP               | +        | +        | +        |
| SYS\_PROP\_KEYB\_BACKLIGHT              | +        | +        | +        |
| SYS\_PROP\_KEYBOARD\_HW                 | +        | +        | +        |
| SYS\_PROP\_KEYBOARD\_SIZE               | +        | +        | +        |
| SYS\_PROP\_DISP\_CONTRAST               | +        | -        | -        |
| SYS\_PROP\_DISP\_BACKLIGHT              | +        | +        | +        |
| SYS\_PROP\_DISP                         | +        | +        | +        |
| SYS\_PROP\_DISP\_HW                     | +        | +        | +        |
| SYS\_PROP\_DISP\_COLOR                  | +        | +        | +        |
| SYS\_PROP\_DISP\_HEIGHT                 | +        | +        | +        |
| SYS\_PROP\_DISP\_WIDTH                  | +        | +        | +        |
| SYS\_PROP\_DISP\_TOUCH                  | +        | +        | +        |
| SYS\_PROP\_ANDROID                      | +        | +        | -        |
| SYS\_PROP\_HW\_RAM\_SIZE                | +        | +        | +        |
| SYS\_PROP\_HW\_RAM\_USED                | +        | +        | +        |
| SYS\_PROP\_HW\_FLASH\_SIZE              | +        | +        | +        |
| SYS\_PROP\_HW\_FLASH\_USED              | +        | +        | +        |
| SYS\_PROP\_HW\_EXE\_PARTITION\_SIZE     | +        | +        | +        |
| SYS\_PROP\_HW\_EXE\_PARTITION\_USED     | +        | +        | +        |
| SYS\_PROP\_HW\_DATA\_PARTITION\_SIZE    | +        | +        | +        |
| SYS\_PROP\_HW\_DATA\_PARTITION\_USED    | +        | +        | +        |
| SYS\_PROP\_HW\_TOUCH\_GROUNDED          | -        | -        | -        |
| SYS\_PROP\_LED                          | +        | +        | +        |
| SYS\_PROP\_PCI                          | +        | +        | +        |
| SYS\_PROP\_VOLUME                       | -        | +        | +        |
| SYS\_PROP\_SPEAKER\_AVAILABLE           | -        | +        | +        |
| SYS\_PROP\_BUZZER\_AVAILABLE            | +        | +        | +        |
| SYS\_PROP\_ADE\_STATUS                  | +        | +        | -        |
| SYS\_PROP\_CERT\_SPONSOR\_PROD          | +        | +        | -        |
| SYS\_PROP\_ATTACK\_STATUS               | +        | +        | +        |
| SYS\_PROP\_ATTACK\_STATUS\_CODE         | -        | -        | -        |
| SYS\_PROP\_VCL\_ENCRYPTION\_STATUS      | +        | +        | -        |
| SYS\_PROP\_VOLTAGE\_ENCRYPTION\_STATUS  | +        | +        | -        |
| SYS\_PROP\_POSEIDON\_ENCRYPTION\_STATUS | +        | +        | -        |
| SYS\_PROP\_NAVIGATOR\_STATUS            | -        | +        | -        |
| SYS\_PROP\_SERVICE\_SWITCH\_STATUS      | +        | +        | +        |
| SYS\_PROP\_DEVICE\_MODE                 | +        | +        | +        |
| SYS\_PROP\_SYSMODE\_BUTTON              | +        | +        | +        |
| SYS\_PROP\_DEVICE\_TYPE                 | +        | +        | +        |
| SYS\_PROP\_VATS                         | +        | +        | +        |
| SYS\_PROP\_UX100\_ANTI\_REMOVAL\_SWITCH | +        | -        | -        |
| SYS\_PROP\_SLP\_TAINTED\_STATUS         | -        | +        | +        |
| SYS\_PROP\_UPTIME                       | +        | +        | +        |
| SYS\_PROP\_BARCODE\_SCANNER             | -        | +        | +        |
| SYS\_PROP\_CAMERA                       | -        | +        | +        |
| SYS\_PROP\_SWITCH\_THRESHOLD\_VOLTAGE   | -        | +        | -        |
| SYS\_PROP\_LOW\_THRESHOLD\_VOLTAGE      | -        | +        | -        |
| SYS\_PROP\_CONSOLE\_STATE               | +        | +        | -        |
| SYS\_PROP\_UX\_MDB                      | +        | +        | +        |
| SYS\_PROP\_CARD\_SLOT2\_MODE            | -        | +        | -        |
| SYS\_PROP\_CARD\_SLOT\_COUNT            | -        | +        | -        |
| SYS\_PROP\_KEYBOARD\_TYPE               | +        | +        | +        |
| SYS\_PROP\_EXT\_NFC\_ANTENNA            | +        | -        | +        |
| SYS\_PROP\_VRK2\_SUPPORT                | -        | +        | -        |
| SYS\_PROP\_USB\_C\_CHARGING\_STATE      | -        | +        | -        |
| SYS\_PROP\_POGO\_CHARGING\_STATE        | -        | +        | -        |

| **String type property name**               | **VOS1** | **VOS2** | **VOS3** |
| ------------------------------------------- | -------- | -------- | -------- |
| SYS\_PROP\_HW\_MODEL\_NAME                  | +        | +        | +        |
| SYS\_PROP\_HW\_MODEL\_NAME\_SHORT           | +        | +        | +        |
| SYS\_PROP\_HW\_SERIALNO                     | +        | +        | +        |
| SYS\_PROP\_OS\_VERSION                      | +        | +        | +        |
| SYS\_PROP\_HW\_PTID                         | +        | +        | +        |
| SYS\_PROP\_HW\_VARIANT\_NAME                | +        | +        | +        |
| SYS\_PROP\_HW\_PART\_NO                     | +        | +        | +        |
| SYS\_PROP\_HW\_VERSION                      | +        | +        | +        |
| SYS\_PROP\_HW\_LOT\_NO                      | +        | +        | +        |
| SYS\_PROP\_BOOT\_VERSION                    | +        | +        | +        |
| SYS\_PROP\_TERMINAL\_SPONSOR                | +        | +        | +        |
| SYS\_PROP\_MANUF\_DATE                      | +        | +        | -        |
| SYS\_PROP\_CERT\_SPONSOR\_SN                | +        | +        | +        |
| SYS\_PROP\_CERT\_SPONSOR\_MODE              | +        | +        | -        |
| SYS\_PROP\_ADK\_VERSION                     | +        | +        | +        |
| SYS\_PROP\_UX100\_SERIALNO                  | +        | -        | -        |
| SYS\_PROP\_UX100\_PARTNO                    | +        | -        | -        |
| SYS\_PROP\_UX100\_FW\_VERSION               | +        | -        | -        |
| SYS\_PROP\_SBI\_VERSION                     | +        | +        | +        |
| SYS\_PROP\_VAULT\_VERSION                   | +        | +        | +        |
| SYS\_PROP\_CIB\_VERSION                     | +        | +        | -        |
| SYS\_PROP\_MIB\_VERSION                     | +        | +        | +        |
| SYS\_PROP\_KERNEL\_VERSION                  | +        | +        | +        |
| SYS\_PROP\_RFS\_VERSION                     | +        | +        | -        |
| SYS\_PROP\_RELEASE\_VERSION                 | +        | +        | +        |
| SYS\_PROP\_RFS\_SECURITY\_VERSION           | +        | +        | -        |
| SYS\_PROP\_SRED\_VERSION                    | +        | +        | -        |
| SYS\_PROP\_SRED\_MODE                       | +        | +        | -        |
| SYS\_PROP\_OPENPROTOCOL\_VERSION            | +        | +        | -        |
| SYS\_PROP\_PCI\_REBOOT\_TIME                | +        | +        | +        |
| SYS\_PROP\_FILE\_NAME\_TO\_INSTALL          | +        | +        | -        |
| SYS\_PROP\_MSR\_COUNTERS                    | +        | +        | -        |
| SYS\_PROP\_SCR\_COUNTERS                    | +        | +        | -        |
| SYS\_PROP\_CTLS\_COUNTERS                   | +        | +        | -        |
| SYS\_PROP\_DOCK\_STATION\_SN                | -        | +        | -        |
| SYS\_PROP\_DOCK\_STATION\_PN                | -        | +        | -        |
| SYS\_PROP\_DOCK\_STATION\_MODEL             | -        | +        | -        |
| SYS\_PROP\_DOCK\_STATION\_MAC               | -        | +        | -        |
| SYS\_PROP\_DOCK\_STATION\_HW\_REV           | -        | +        | -        |
| SYS\_PROP\_DOCK\_STATION\_INSTALL           | -        | +        | -        |
| SYS\_PROP\_GSM\_FIRMWARE\_VERSION           | -        | +        | -        |
| SYS\_PROP\_DOCK\_STATION\_OS\_VERSION       | -        | +        | -        |
| SYS\_PROP\_DOCK\_STATION\_IP\_ADDRESS       | -        | +        | -        |
| SYS\_PROP\_DOCK\_STATION\_IP\_V6\_ADDRESS   | -        | +        | -        |
| SYS\_PROP\_DOCK\_STATION\_USB1\_IP\_ADDRESS | -        | +        | -        |
| SYS\_PROP\_ANDROID\_IP\_V4\_ADDRESS         | -        | +        | -        |
| SYS\_PROP\_ANDROID\_IP\_V6\_ADDRESS         | -        | +        | -        |
| SYS\_PROP\_ANDROID\_MAC                     | -        | +        | -        |
| SYS\_PROP\_WARRANTIED\_KEYS                 | +        | +        | +        |
| SYS\_PROP\_SECAPP\_VERSION                  | +        | +        | -        |
| SYS\_PROP\_VSS\_VERSION                     | +        | +        | -        |
| SYS\_PROP\_STBY\_MCU\_VERSION               | +        | -        | -        |
| SYS\_PROP\_EXT\_STORAGE                     | +        | +        | -        |
| SYS\_PROP\_INSTALLED\_PCKG\_LIST            | +        | +        | -        |
| SYS\_PROP\_PKG\_LIST                        | +        | +        | -        |
| SYS\_PROP\_APP\_PKG\_LIST                   | +        | +        | -        |
| SYS\_PROP\_BUNDLE\_LIST                     | +        | +        | -        |
| SYS\_PROP\_APP\_BUNDLE\_LIST                | +        | +        | -        |
| SYS\_PROP\_MSR\_INFO                        | +        | +        | -        |
| SYS\_PROP\_SCR\_INFO                        | +        | +        | -        |
| SYS\_PROP\_CTLS\_INFO                       | +        | +        | -        |
| SYS\_PROP\_HW\_STRING                       | +        | +        | -        |
| SYS\_PROP\_DEV\_ID                          | +        | +        | +        |
| SYS\_PROP\_FET                              | +        | +        | -        |
| SYS\_PROP\_BT\_MAC                          | +        | +        | +        |
| SYS\_PROP\_WIFI\_MAC                        | +        | +        | +        |
| SYS\_PROP\_ETH\_MAC                         | +        | +        | +        |
| SYS\_PROP\_ETH2\_MAC                        | +        | +        | -        |
| SYS\_PROP\_COUNTRY                          | +        | +        | -        |
| SYS\_PROP\_RTC                              | +        | +        | +        |
| SYS\_PROP\_NTP\_SERVER                      | +        | +        | +        |
| SYS\_PROP\_BATTERY\_SERIALNO                | -        | -        | -        |
| SYS\_PROP\_TIME\_ZONE                       | +        | +        | -        |
| SYS\_PROP\_TIME\_ZONE\_LIST                 | +        | +        | -        |
| SYS\_PROP\_TIME\_ZONE\_FROM\_FILE           | +        | +        | -        |
| SYS\_PROP\_TIME\_ZONE\_NAME                 | +        | +        | -        |
| SYS\_PROP\_TIME\_ISO8601                    | +        | +        | -        |
| SYS\_PROP\_REBOOT\_REASON                   | -        | +        | +        |
| SYS\_PROP\_ALL\_LOADED\_KEYS                | +        | +        | +        |
| SYS\_PROP\_ALL\_LOADED\_KEYS\_V2            | -        | +        | -        |
| SYS\_PROP\_TAMPER\_RECORDS                  | +        | +        | +        |
| SYS\_PROP\_BARCODE\_SCANNER\_FW\_VERSION    | -        | +        | -        |
| SYS\_PROP\_ANDROID\_VERSION                 | -        | +        | -        |
| SYS\_PROP\_STATUSBAR\_COLOR                 | -        | +        | -        |
| SYS\_PROP\_ANDROID\_TIME                    | -        | +        | -        |
| SYS\_PROP\_MTD\_INFO                        | -        | +        | -        |
| SYS\_PROP\_HW\_ID                           | -        | +        | +        |

</details>

{% hint style="info" %}
**Notes:**\
For local date and time settings please use the SYS\_PROP\_TIME\_ISO8601, which is available on VOS3.\
The SYS\_PROP\_RTC is used to change the real-time clock, and on VOS3 it can be changed only in the manufacturing device state or when the device is tampered.
{% endhint %}

**System Status Bar**

Same as VOS1/VOS2\
**API:** sysinfo/sysbar.h\
**Library:** libvfisysbar.so

![](https://3462522456-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIfFmiYwINerMPYjzrAC6%2Fuploads%2Fgit-blob-b16df6cc183447e440b674fdae24d3d272a99b4d%2F0.png?alt=media)

### ADK PM (Power Management)

#### **API compatibility**

* all APIs supported as on VOS1/VOS2

### ADK Agent (VHQ Agent)

#### **API compatibility**

* Mostly compatible with previous versions

**Reporting the Operating system**

VHQ agent will report back the OS name to the VHQ server to tell about the used operating system (VOS3 or AOS) on hardware that can be run with operating systems.

### CP Applications (ADK CPR)

VOS3 supports Verifone Commerce Platform (CP) applications similar to VOS2 platform. The integration APIs for triggering CP applications is same as on VOS2 using the CP library. The cloud proxy component provides secured connectivity to the gateway for routing to end-points for the CP applications.

#### **API compatibility**

* all APIs supported as on VOS1/VOS2

**CP-APP packaging and installation**

Verifone Commerce Platform (CP) applications are packaged and signed normally. The ZIP package format used for VOS2 CP applications is no longer supported. CP applications can thus be installed locally or remotely as any other package.

**Endpoint Configuration**

Please use the specific CP-Proxy release for VOS3 that configure the supported gateways.

### System Installer API

#### **API compatibility**

There is no direct mapping between VOS2 Secure Installer API.

Comparing to SecIns, new Installer API is only providing installation functionality. No API for Key loading, application start/stop, etc.

Functions that are not related to installation were moved to a different components:

| **Functionality**                  | **Responsible component**   |
| ---------------------------------- | --------------------------- |
| Application/service start and stop | MAC by the help of Launcher |
| Integrity checking                 | Verifier, CDD               |
| Key management                     | Security tools/libraries    |

**Installer API**

Installer API may be categorized into two major groups:

1. Software management
   1. validate of the software download file
   2. install of the software download file
   3. get operation result (usually performed after reboot)
2. Software information
   1. list software bundles + get their details

{% hint style="info" %}
Installer header file is located in SDK ***include/instaler/installer.hpp***
{% endhint %}

**Workflow**

**Install**

1. get/locate download files
2. create an installer session object (we act in terms of session entity)
3. add download files in the order they should be installed

{% hint style="info" %}
Dlfiles can be added to the session entity only until it is acquired. This is session context consistency measure.
{% endhint %}

1. request session ID

{% hint style="info" %}
Session IDs are unique unsigned integers. Once acquired they will never repeat.
{% endhint %}

{% hint style="warning" %}
There can be only one active installer session at a time.\
To prevent deadlocks for installer API calls, sessions have a 15 second timeout.\
If no install/verify action is started during a timeout period, session is rejected.
{% endhint %}

5. save session ID in persistent location (file)
6. call session **install** method
7. **device reboots** to perform installation actions and switch over to A or B
8. application is requesting install operation result by session ID

{% hint style="warning" %}
Installer is keeping information for last 50 sessions. Older session results are getting discarded.
{% endhint %}

Operation result provides the following information:

1. overall operation result
2. action being requested (verify or install)
3. caller application name
4. request date and time
5. list of download files
6. error description (in case of failure)
7. faulty file (in case of failure)

```c
#include <cstdio>
#include <iostream>
#include <filesystem>
#include <fstream>
#include <string>
#include <installer/installer.hpp>

using namespace std;
using namespace vfi;
namespace fs = std::filesystem;

#define SID_FILE "flash/sid"

int main()
{
	bool keep_files = true; // set to false to remove installation file during installation (default behaviour)
	installer::Status status;
	error_code ec;


	if ( fs::exists( SID_FILE, ec ) )
	{
		// post reboot installation result check
		ifstream is( SID_FILE );
		stringstream buffer;
		buffer << is.rdbuf();
		std::string sid_s = buffer.str();
		unsigned int sid = stoul( sid_s, nullptr, 0);
		cout << "sid:" << sid << endl;

		installer::Session session( sid );
		if ( session.get_state() == installer::Session::Complete )
		{
			// check installation result
			installer::Session::SessionResult res;
			if ( session.get_result( res ).is_ok() )
			{
				cout << "installation of sid:" << sid << " is successful" << endl;
			}
			else
			{
				cout << "installation of sid:" << sid << " has failed" << endl;
			}
			fs::remove( SID_FILE, ec );
		}
		else
		{
			cout << "Session " << sid << " is not known" << endl;
			fs::remove( SID_FILE, ec );
			exit(1);
		}
	}
	else
	{
		// installation
		auto session = installer::Session();
		// It is strongly recommended to use flash/ to store installation files
		status = session.add( "flash/dl.example.tar" );

		if ( !status.is_ok() )
		{
			cout << "Bad argument: " << status.to_string() << endl;
			exit(1);
		}

		status = session.acquire();
		if ( status.is_ok() )
		{
			cout << "Session ID: " << session.get_id() << endl;
			// save session ID
			ofstream os( SID_FILE );
			os << session.get_id();
			os.close();
			// perform installation
			status = session.install( keep_files ); // last call before reboot
			///////// REBOOT /////////////////
			if ( status.is_ok() )
			{
				// Should never get here
			}
			else
			{
				cout << "Install failed: " << status.to_string() << endl;
				exit(1);
			}
		}
		else
		{
			cout << "Failed to acquire session" << endl;
			exit(1);
		}
	}

	return 0;
}
```

**Verify**

1. get/locate download files
2. create an installer session object
3. add download files in the order they should be installed
4. request session ID
5. call session **verify** method
6. process verification result
7. (optionally) proceed with installation within same session context, preserving the ID

```c
#include <cstdio>
#include <iostream>
#include <installer/installer.hpp>

using namespace std;
using namespace vfi;

int main()
{

	installer::Status status;

	// verification
	auto session = installer::Session();
	// It is strongly recommended to use flash/ to store installation files
	status = session.add( "flash/dl.example.tar" );

	if ( !status.is_ok() )
	{
		cout << "Bad argument: " << status.to_string() << endl;
		exit(1);
	}

	status = session.acquire();
	if ( status.is_ok() )
	{
		cout << "Session ID: " << session.get_id() << endl;
		// perform verification
		status = session.verify();
		if ( status.is_ok() )
		{
			cout << "Verification successful" << endl;
		}
		else
		{
			cout << "Verification failed: " << status.to_string() << endl;
		}
		// release session ( if installation is not intended )
		session.release();
	}
	else
	{
		cout << "Failed to acquire session" << endl;
		exit(1);
	}

	return 0;
}
```

**List installed software**

1. list software bundles

```c
#include <cstdio>
#include <iostream>
#include <installer/installer.hpp>

using namespace std;
using namespace vfi;

int main()
{
	list<installer::BundleInfo> bundles;
	installer::Status status;

	bool get_from_active = true; // Set to false if want to get information for fallback image
	status = installer::get_bundle_list( bundles, get_from_active );

	if ( status == installer::Status::Ok )
	{
		for ( const auto &bundle : bundles )
		{
			cout << "Bundle: " << bundle.get_name() << endl;
			cout << "\tVersion: " << bundle.get_version().to_string() << endl;
			cout << "\tExtended version: " << bundle.get_extended_version() << endl;
			cout << "\tUser: " << bundle.get_user() << endl;
			cout << "\tDigest: " << bundle.get_digest() << endl;
		}

	}
	else
	{
		cout << "Failed to get bundle list" << endl;
		exit(1);
	}

	return 0;
}
```

## Related documentation

* [Packaging](/adk-os-platform/readme/developing-applications/packaging.md)
* [Managing CP applications](/adk-os-platform/readme/developing-applications/managing-cp-applications.md)
* [Platform security model](/adk-os-platform/readme/security-and-system-protection/platform-security-model.md)
* [Security functions and key management](/adk-os-platform/readme/security-and-system-protection/security-functions-and-key-management.md)
* [User interface and application control](/adk-os-platform/readme/user-interface-and-application-control.md)


---

# 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://docs.verifone.com/adk-os-platform/readme/migration-guide.md?ask=<question>&goal=<endgoal>
```

`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.