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.
1
Packaging format and tools
CHANGES:
Control files are replaced by manifest (json) files describing the bundle and its packages.
Adapt package types to vos3 package types.
IMPACTS: 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
CHANGES: VOS3 will no longer support signing via signing cards, but only via online signing service.
IMPACTS: Need to use VF online signing methods.
3
Compiler and Toolset
CHANGES: VOS3 will use newer compiler and tools for building applications. This is to enable more recent C/C++ standards.
IMPACTS: 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: #define __cplusplus 201703L, meaning C++17 standard.
4
Linux Kernel
CHANGES: VOS3 will use newer revisions of the Linux kernel. Also the Linux kernel revisions might be different between various products running VOS3.
IMPACTS: 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
CHANGES: VOS3 will support A/B scheme for supporting both seamless updates and allow fallback to previous image of the system.
IMPACTS:
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
CHANGES: 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.
IMPACTS: No changes to applications expected, but operational differences.
7
No VOS1 Private APIs
CHANGES: VOS3 will no longer support the VOS1/VOS2 private APIs. Older VOS1 services APIs have been deprecated and removed from VOS3 products.
IMPACTS: Users need to revise their application code to use and comply with ADK APIs.
8
No VSS Support
CHANGES: VOS3 will no longer support Verifone Secure Scripts (VSS).
IMPACTS: 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
CHANGES: VOS3 will not support direct key loading APIs.
IMPACTS: 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
CHANGES: 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.
IMPACTS: 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"
CHANGES: 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.
IMPACTS:
An application that needs a "file-based" transactional behavior (recommended):
store information to a temporary files in the same filesystem (ie: add a '.tmp' extension)
when finished, close the temporary file (this will flush) and then rename it (ie: remove '.tmp' extension). On the same filesystem, rename is atomic.
on reboot/restart always remove all the temporary files (ie: remove all files with '.tmp')
An application that really needs a "record-based" 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
CHANGES: VOS3 will no longer support a compatibility layer for ADK-SEC 1.x APIs.
IMPACTS: 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
CHANGES: 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.
IMPACTS: Applications that use OpenSSL directly will need to adapt their application code to comply with changed APIs in OpenSSL v3.
14
ADK COM : PKCS#12 support
CHANGES: 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
IMPACTS:
Applications to load Wifi certs using VRK packages
15
ADK COM : Analog Modem Support removed
CHANGES:
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)
IMPACTS:
No application impact
16
ADK COM: No
Dial-up Networking Profile (DUN)
CHANGES:
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.
IMPACTS:
no deployments with dial-up mode supported.
17
ADK COM : STunnel API support removed
CHANGES:
STunnel APIs for SDI based external pinpads - replaced in SDI internally
IMPACTS:
No application impact
SDI external pinpad connection is transparent to applications.
18
ADK COM: External Barcode reader
CHANGES:
Support for HID based external barcode readers removed
IMPACTS:
no support of external barcode readers - use built-in camera or HW barcode decoder supported through ADK-GUI.
19
Installation
CHANGES:
Apps cannot be installed without reboot
new installer API
IMPACTS:
no impact on applications
Applications implementing own download mechanisms are recommended to use the new installer API
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.
user
/home/<user>/
user_ro
/home/<user>/
userflash
/mnt/flash/userdata/<user>/
system_versioned_data
system_data
user_versioned_data
user_data
/mnt/sysdata/versioned/<user>/
/mnt/sysdata/data/<user>/
/mnt/appdata/versioned/<user>/
/mnt/appdata/data/<user>/
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<X> 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/<user>/
not supported
unsigned
/mnt/flash/userdata/<user>/unsigned/
user_unsigned_data
/mnt/appdata/data/<user>/unsigned/
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)
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.
MAC is a display controller daemon. It provides application developers a way to start/stop applications and controls their 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
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
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
MAC manifest is not related to the installer package manifest.
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:
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, 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) 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.
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
--
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
NOTE: 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
TBD
invalidates file content on tamper (no decryption possible)
Verishield Protect (VSP/VCL)
x
x
TBD (VCCI based)
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.
Sample Security Configuration File
The below sample config demonstrates large part of available options for the security configuration.
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
|
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
|
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
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
System Status Bar
Same as VOS1/VOS2 API: sysinfo/sysbar.h Library: libvfisysbar.so
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:
Software management
validate of the software download file
install of the software download file
get operation result (usually performed after reboot)
Software information
list software bundles + get their details
Workflow
Install
get/locate download files
create an installer session object (we act in terms of session entity)
add download files in the order they should be installed
request session ID
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.
save session ID in persistent location (file)
call session install method
device reboots to perform installation actions and switch over to A or B
application is requesting install operation result by session ID
Installer is keeping information for last 50 sessions. Older session results are getting discarded.
Operation result provides the following information:
overall operation result
action being requested (verify or install)
caller application name
request date and time
list of download files
error description (in case of failure)
faulty file (in case of failure)
Verify
get/locate download files
create an installer session object
add download files in the order they should be installed
request session ID
call session verify method
process verification result
(optionally) proceed with installation within same session context, preserving the ID
List installed software
list software bundles
Related documentation
Last updated
Was this helpful?