This section describes how the Netcetera iOS 3DS SDK should be configured.
When a transaction is initiated, the SDK gets 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 when processing the transaction.
When processing transactions the SDK uses DS public key, DS root certificate and DS logo. They should be configured in a configuration file. The configuration file is a property list file: DSsConfiguration.plist.
In the DSsConfiguration.plist keys that need to be defined are:
To define a scheme DS, simply create a dictionary from the root of the DSsConfiguration.plist where the name of the scheme is the dictionary key. Each scheme DS dictionary contains the following: * dsPublicKey - public key in PEM format, or certificate in PEM or DER format. * dsRootCertificate - string value representation of the encryption certificate file name. * IDs - an array containing String representations of the DS IDs. * logoImageName - string value representation of the scheme logo image name.
Please note that the key names shall be set exactly as stated above for the configuration to be valid.
To define the DS IDs that belong to a certain scheme DS, create a new array named IDs containing string values of the DS IDs. Repeat for each scheme DS.
DS IDs | |
---|---|
parent | Scheme Dictionary |
key | IDs. |
value | ID of the scheme, each in a new row. |
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 file for more RID values.
To define the public key that will be used for encryption of Device Info, create a new element in the selected scheme name. The key should be dsPublicKey while the value should be the name of the DS certificate or the public key to be used.
DS Public Key | |
---|---|
parent | Scheme Dictionary |
key | dsPublicKey |
value | Name of the encryption certificate, or public key |
Note: If public keys are provided, the keys can be either EC or RSA in PEM format and in ASN1 notation. If certificates are provided, they need to be in the X.509 standard in either PEM or DER format. In case a Certificate chain is provided, the leaf certificate will be used. Make sure that the certificate is part of the application bundle.
To define the root certificate that will be used for a certain scheme DS, create a new element in the selected scheme name. The key should be dsRootCertificate while the value should be the name of the DS Root certificate.
DS Root Certificate | |
---|---|
parent | Scheme Dictionary |
key | dsRootCertificate |
value | Name of the root certificate. |
Note: The certificate need to be in the X.509 standard in either PEM or DER format. Make sure that the certificate is part of the application bundle.
To define the logo that will be used for a certain scheme DS, create a new element in the scheme DS dictionary. The key should be logoImageName, while the value should be the name of the logo image for the scheme DS. Make sure that the logo image is in the application bundle. Repeat the process for each scheme DS.
DS Logo image | |
---|---|
parent | Scheme Dictionary |
key | logoImageName |
value | Name of image filename. |
Example:
![dsConfigurationExample]
DSsConfiguration.plist example file can be downloaded from here.
The Netcetera iOS 3DS SDK comes bundled with configuration for the following directory servers, listed in the table below.
Scheme | RIDs | DS Public Key | DS Root Public Key | DS Logo |
---|---|---|---|---|
Mastercard | A000000005 |
|
|
mastercard.png |
Visa | |
|
|
visa.png |
Amex | |
|
|
amex.png |
Diners | |
|
|
diners.png |
JCB | |
|
|
jcb.gif |
MIR | |
|
|
mir.png |
Union | |
|
|
union.png |
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 and the ACS in use. The integrators are encouraged to complete the configuration.
The Netcetera iOS 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 about the UiCustomization API and how to use it, please refer to section 4.5 in the EMVCo 3DS SDK Specification.