SDK Configuration

This section describes how the Netcetera Android 3DS SDK should be configured.

Directory Server Configuration

When transaction is initiated, the SDK get the information about the Directory Server that will participate in the message flow. With that, the SDK determinate which DS public key to use for the data encryption and which DS logo to be shown.

The SDK uses the DS public key and the DS logo. These are configured in the ConfigParameters in Initialization.

The encryption key or certificate and the root certificate can be obtained from each scheme respectively.

Following are the steps for the DS configuration:

  1. Schemes - Which schemes can be used.
  2. DS IDs - DS IDs that belong to a certain scheme.
  3. Schemes public key - Public key for each scheme used for encryption of the device data.
  4. Schemes root public key - Public key for each scheme used for verification of the certificate chain in the acsSignedContent during a challenge flow.
  5. Scheme logo Resource ID - Drawable Resource ID for each scheme that will be used as logo.
  6. Scheme dark logo Resource ID - Drawable Resource ID for each scheme that will be used as dark mode logo.

Some of the values can be omitted, please check Pre-configured Directory Servers for the pre-configured values that will be used instead.

Note: If public keys are provided, the keys can be either EC or RSA in PEM format. If certificates are provided, they need to be in the X.509 standard in either PEM or DER format.

Configuration with ConfigParameters

Configuring Schemes Directory Servers

To define the scheme DS, use the ConfigParameters.addParam(...) with the following arguments:

Argument Value
group null
paramName "schema_names"
paramValue Comma separated values of schemes.

Example:

1
configParameters.addParam(null, "schema_names", "mastercard, visa");

Configuring DS IDs

To define the DS IDs that belong to certain scheme, use the ConfigParameters.addParam(...) with the following arguments:

Argument Value
group "schema_ds_ids"
paramName The name of the scheme to define for.
paramValue Comma separated values of each DS id for the scheme.

The 3DS Requestor App uses the Cardholder Account Number and optionally other cardholder information to identify the DS ID. A DS ID is the Scheme’s Card RID (Registered application provider identifier). The identifier, usually 5 bytes in length, is issued by the ISO/IEC 7816-5 registration authority and is used to address an application in the card. For example, an RID could be: A000000003. Please refer to the configuration for more RID values.

Example:

1
2
configParameters.addParam("schema_ds_ids", "mastercard", "A000000004");
configParameters.addParam("schema_ds_ids", "visa", "A000000003");

Configuring DS Public Keys

To define the public key that will be used for certain scheme, use the ConfigParameters.addParam(...) with the following arguments:

Argument Value
group "schema_public_key"
paramName The name of the scheme to define for.
paramValue ASN.1 encoding of the public key or the certificate (DER/PEM) in Base64 encoded format.

Example:

1
2
configParameters.addParam("schema_public_key", "mastercard", "MIIDuzCCAqOgAwIBAgIBC...");
configParameters.addParam("schema_public_key", "visa", "MIIDuzCCAqOgAwIBAgIBC...");

Configuring DS Root Public Keys

To define the root public key that will be used for certain scheme, use the ConfigParameters.addParam(...) with the following arguments:

Argument Value
group "schema_root_public_key"
paramName The name of the scheme to define for.
paramValue ASN.1 encoding of the public key or the certificate (DER/PEM) in Base64 encoded format.

Note: To ensure a higher percentage of successful transactions, in the event where the configured root certificate cannot verify the acsSignedContent, the Netcetera 3DS SDK will try to use the corresponding Pre-configured DS Root Public Key instead.

Example:

1
2
configParameters.addParam("schema_root_public_key", "mastercard", "MIIDuzCCAqOgAwIBAgIBC...");
configParameters.addParam("schema_root_public_key", "visa", "MIIDuzCCAqOgAwIBAgIBC...");

Configuring Logos

A scheme can have 2 logos configured - standard and dark logo. The standard logo is mandatory for each scheme and therefore must be present either in the 3DS SDK preconfigured data or configured by the Requestor Application. On the other hand, the dark logo is optional and will only be used in case the Requestor Application enables dark mode on the 3DS SDK and necessary system conditions are met. If the 3DS SDK needs to use a dark logo that is missing, it will use the standard logo displayed under white surface as a fallback instead.

To define the standard logo that will be used for a certain scheme, use the ConfigParameters.addParam(...) with the following arguments:

Argument Value
group "schema_logo"
paramName The name of the scheme to define for.
paramValue String value of Drawable Resource ID.

To define the dark logo that will be used for a certain scheme, use the ConfigParameters.addParam(...) with the following arguments:

Argument Value
group "schema_logo_dark"
paramName The name of the scheme to define for.
paramValue String value of Drawable Resource ID.

Example:

1
2
3
4
5
// Schema with both logos
configParameters.addParam("schema_logo", "mastercard", Integer.toString(R.drawable.schema_logo_mastercard));
configParameters.addParam("schema_logo_dark", "mastercard", Integer.toString(R.drawable.schema_logo_mastercard_dark));
// Schema without dark logo
configParameters.addParam("schema_logo", "visa", Integer.toString(R.drawable.schema_logo_visa));

Configuration with ConfigurationBuilder (Recommended)

The ConfigurationBuilder is a feature that is not defined in the specification, but has been provided by the Netcetera Android 3DS SDK to allow easier configuration of the ConfigParameters. It provides ease of use methods to set the required fields for new or existing schemes, as to prevent possible misconfigurations.

Configuring schemes

To define the scheme, use the ConfigurationBuilder.configureScheme(...) with the following arguments

Argument Value
schemeConfiguration The configuration of the scheme

SchemeConfiguration

The Netcetera Android 3DS SDK provides a utility class to help with the configuration of the scheme. To define a new scheme use SchemeConfiguration.newSchemeConfiguration... with the following arguments:

Argument Value
schemeName The name of the current scheme
schemeIds List containing the DS ids for the scheme.
schemeLogo String value of Drawable Resource ID for the standard logo
schemeLogoDark String value of Drawable Resource ID for the dark logo
encryptionPublicKey ASN.1 encoding of the public key
rootPublicKey ASN.1 encoding of the public root key
certificatePath The path of the certificate (DER/PEM) in Base64 encoded format placed in the "assets" directory.

Example:

1
2
3
4
5
6
7
8
9
10
11
ConfigurationBuilder()  
    .configureScheme(
        SchemeConfiguration.newSchemeConfiguration("diners")
        .ids(Collections.singletonList("A000000152"))
        .logo(Integer.toString(R.drawable.ds_logo_diners))
        .logoDark(Integer.toString(R.drawable.ds_logo_diners_dark))
        .encryptionPublicKeyFromAssetCertificate(assetManager, "example-diners-sign-certeq-rsa.crt")
        .rootPublicKeyFromAssetCertificate(assetManager, "example-diners-sign-certeq-rsa.crt")
        .build()
    )
    .build();

The utility class also includes the option to modify a pre-configured scheme. For that purpose use SchemeConfiguration.{DSName}SchemeConfiguration..., with the aforementioned arguments, where {DSName} is the name of the scheme corresponding with a directory server from Pre-configured Directory Servers. The argument values that won’t be specified shall be taken from Pre-configured Directory Servers.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
ConfigurationBuilder()       
    //Mastercard configuration
    .configureScheme(
        SchemeConfiguration.mastercardSchemeConfiguration()
            .encryptionPublicKeyFromAssetCertificate(assetManager, "example-mc-sign-certeq-rsa.crt")
            .build()
    )
    //Visa configuration
    .configureScheme(
        SchemeConfiguration.visaSchemeConfiguration()
            .encryptionPublicKeyFromAssetCertificate(assetManager, "example-visa-sign-certeq-rsa.crt")
            .rootPublicKeyFromAssetCertificate(assetManager, "example-visa-sign-certeq-rsa.crt")
            .build()
    )
    .build();

Pre-configured Directory Servers

The Netcetera Android 3DS SDK comes bundled with configuration for the following directory servers, listed in the table below.

SDK Configured Scheme RIDs DS Public Key DS Root Public Key DS Logo DS Dark Logo
Mastercard
A000000004

3ds2.directory.mastercard.com
Expiry: 15.06.2024

PRD MasterCard Identity Check Root CA
Expiry: 15.07.2030

R.drawable.ds_logo_mastercard

R.drawable.ds_logo_mastercard_dark
Visa
A000000003

3ds2.rsa.encryption.visa.com
Expiry: 22.08.2024

Visa Public RSA Root CA
Expiry: 15.03.2041

R.drawable.ds_logo_visa

R.drawable.ds_logo_visa
Amex
A000000025

sdk.safekey.encryptkey.com
Expiry: 19.08.2023

American Express Private Certification Authority
Expiry: 11.08.2029

R.drawable.ds_logo_amex

R.drawable.ds_logo_amex_dark
Diners
A000000152

Discover SDK Key

ProtectBuy Root
Expiry: 03.02.2027

R.drawable.ds_logo_diners

R.drawable.ds_logo_diners
JCB
A000000065

ds2apr.jcb-tds.com
Expiry: 03.03.2051

JCB DS Root CA EMV 3-D Secure
Expiry: 09.01.2036

R.drawable.ds_logo_jcb

R.drawable.ds_logo_jcb
MIR

R.drawable.ds_logo_mir

R.drawable.ds_logo_mir
Union
A000000333

银联国际有限公司
Expiry: 02.08.2022

CFCA ACS CA
Expiry: 28.09.2035

R.drawable.ds_logo_union

R.drawable.ds_logo_union
Cartes Bancaires
A000000042

CartesBancaires SDK Key

Root 3DS CB CA
Expiry: 31.07.2048

R.drawable.ds_logo_cb

R.drawable.ds_logo_cb

The binding between the configuration and the pre-configured values is done with the RID value of the Directory Server.

The configuration has precedence over pre-configured values and overwrites them i.e. if a configuration is provided for a parameter, that one will be used, instead of the pre-configured one.

Note: The pre-configured DS Public Key and DS Root Public Key serve for convenience, while the integrators have to verify their compatibility to the Directory Server. The integrators are encouraged to complete the configuration.

DS RID Values

The Netcetera Android 3DS SDK has a utility API DsRidValues that contains the DS RIDs for the SDK Preconfigured Schemes.

Restricted Device Info Parameters Configuration

Configuration with ConfigParameters

To define which device info parameters shall be considered as restricted and thus not collected, use the ConfigParameters.addParam(...) with the following arguments:

Argument Value
group null
paramName "restricted_device_info_parameters"
paramValue Comma separated values of IDs of the device info parameters.

Example:

1
configParameters.addParam(null, "restricted_device_info_parameters", "A001,A016,C005");

Configuration with ConfigurationBuilder (Recommended)

To define which device info parameters shall be considered as restricted and thus not collected, use the ConfigurationBuilder.restrictedParameters(...) with the following arguments:

Argument Value
restrictedParameters List containing the IDs of the device info parameters.

Example:

1
ConfigurationBuilder().restrictedParameters(Arrays.asList("A001","A016","C005")).build();

List of device info parameters and their corresponding IDs can be found at EMVCo 3DS SDK Device Info. If a entry in the restricted device info parameters configuration has value that doesn’t correspond to any predefined device info parameter ID, an InvalidInputException is thrown.

Weak Validation of Challenge Response

The Netcetera Android 3DS SDK provides a method that loosens the level of validation of the challenge response parameters received by the ACS. If enabled, the weak validation removes the mandatory status and the string length validation of several challenge response parameters. By default, weak validation is disabled, and it is recommended not to be enabled. This configuration should only be used temporary and preferably while developing or testing, when SDK integrators have problems with the ACS CRes returning values not reflecting the latest EMVCo bulletins rules that the SDK supports. In that case the end users are blocked and cannot complete a transaction. If such problems arise please inform the issuers which version of the SDK you are using and what is the latest bulletin supported by the SDK.

Note: By enabling weak validation, the Netcetera Android 3DS SDK will no longer be compliant with the latest bulletin of the EMVCo Protocol and Core Functions Specification. If any legal actions or consequences arise, the responsibility for using this feature falls on the integrator of the Netcetera Android 3DS SDK.

Configuration with ConfigParameters

To enable or disable the weak validation, call ConfigParameters.addParam(...) with the following arguments:

Argument Value
group null
paramName "weak_validation"
paramValue Boolean value as string, such as "true" or "false"

Example:

1
2
// enables weak validation
configParameters.addParam(null, "weak_validation", "true");

Configuration with ConfigurationBuilder (Recommended)

To enable or disable the weak validation, call ConfigurationBuilder.useWeakDataElementValidation(...) with the following arguments:

Argument Value
useWeakValidation true to enable, false(default) to disable the weak validation

Example:

1
2
3
4
ConfigurationBuilder()
    // enables weak validation
    .useWeakValidation(true)
    .build()

UI Customization

The Netcetera Android 3DS SDK supports customization of the UI elements that are being shown by the SDK itself. For this purpose UiCustomization is used.

For detailed information of the UiCustomization API and how to be used, refer to 4.5 in the EMVCo 3DS SDK Specification.

Moreover, the Netcetera Android 3DS SDK adds support for the system wide dark mode available in Android 10 and above with additional UI customization parameters. The dark mode is disabled by default in the 3DS SDK. To enable, configure and use this feature, please see UICustomization.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
UiCustomization uiCustomization = new UiCustomization();
 
//Setting that the challenge UI should change based on whether system wide dark mode is active or not.
uiCustomization.supportDarkMode(true)
 
ButtonCustomization buttonCustomization = new ButtonCustomization();
 
//Setting light mode background color.
buttonCustomization.setBackgroundColor("#000000");
 
//Setting dark mode background color.
buttonCustomization.setDarkBackgroundColor("#FFFFFF");

Accessibility Consideration

The Netcetera Android 3DS SDK follows the latest guidelines and best practices defined by Google for building accessible apps. If a custom UiCustomization is provided to the 3DS SDK, we recommend that a tool such as the Accessibility Scanner is used to check for any accessibility improvements on the custom UI.

Logging Configuration

The Netcetera Android 3DS SDK uses SLF4J for logging purposes, logging only messages on level WARN and ERROR. The logging of this log levels can be configured by using any logging implementation on top of SLF4J.

Sample implementation that uses logback-android can be found in the guide for the demo reference application and the source code itself.

Permissions

This section describes which Android permissions are required to be granted and which are optional.

Permission Mandatory Description
android.permission.INTERNET Yes Required for communication with the ACS in Challenge Flow. Must be permitted before Starting of Challenge Flow.
android.permission.ACCESS_COARSE_LOCATION No Required for collecting the device coarse location that will be provided as device info parameter. Should be permitted before Initialization.
android.permission.ACCESS_FINE_LOCATION No Required for collecting the device fine location that will be provided as device info parameter. Should be permitted before Initialization.
android.permissions.ACCESS_NETWORK_STATE No Required for collecting device’s IP Address that will be provided as device info parameter. Should be permitted before Initialization.
android.permission.BLUETOOTH No Required for collecting bluetooth hardware info that will be provided as device info parameter. Should be permitted before Initialization.
android.permission.READ_PHONE_STATE No Required for collecting Telephony information that will be provided as device info parameters. Should be permitted before Initialization.
android.permission.SEND_SMS No Required for collecting Telephony information that will be provided as device info parameters. Should be permitted before Initialization.
android.permission.ACCESS_WIFI_STATE No Required for collecting WiFi and Network related information that will be provided as device info parameters. Should be permitted before Initialization.