/n software 3-D Secure V2 C++ Edition

Questions / Feedback?

Server Configuration

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

Server Configuration Settings

AccountAgeIndicator:   Cardholder Account Age Indicator.

Length of time that the cardholder has had the account with the 3DS Requestor.

Possible values are:

01 No account (guest check-out)
02 Created during this transaction
03 Less than 30 days
04 30-60 days
05 More than 60 days

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include.

The complete list of elements (all available as config settings) comprising Cardholder Account Information is:

  • AccountAgeIndicator
  • AccountChangeDate
  • AccountChangeIndicator
  • AccountDate
  • AccountPasswordChangeDate
  • AccountPasswordChangeIndicator
  • AccountPurchaseCount
  • AccountProvisioningAttempts
  • AccountDayTransactions
  • AccountYearTransactions
  • PaymentAccountAge
  • PaymentAccountAgeIndicator
  • ShipAddressUsageDate
  • ShipAddressUsageIndicator
  • ShipNameIndicator
  • SuspiciousAccountActivity

AccountChangeDate:   Cardholder Account Change Date.

Date that the cardholder's account with the 3DS Requestor was last changed. Accepted date format is YYYYMMDD.

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

AccountChangeIndicator:   Cardholder Account Change Indicator.

Length of time since the cardholder's account information with the 3DS Requestor was last changed.

Possible values are:

01 Changed during this transaction
02 Less than 30 days
03 30-60 days
04 More than 60 days

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

AccountDate:   Date cardholder account opened.

Date that the cardholder opened the account with the 3DS Requestor. Accepted date format is YYYYMMDD.

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

AccountDayTransactions:   Number of account transactions in the last day.

Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours.

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

AccountId:   Cardholder Account Identifier.

Additional information about the account optionally provided by the 3DS Requestor in AReq messages.

AccountPasswordChangeDate:   Cardholder Account Password Change Date.

Date that cardholder's account with the 3DS Requestor had a password change or account reset. Accepted date format is YYYYMMDD.

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

AccountPasswordChangeIndicator:   Cardholder Account Password Change Indicator.

Indicates the length of time since the cardholder's account with the 3DS Requestor had a password change or account reset.

Possible values are:

01 No change
02 Changed during this transaction
03 Less than 30 days
04 30-60 days
05 More than 60 days

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

AccountProvisioningAttempts:   Number of account provisioning attempts in the last day.

Number of Add Card attempts for the account in the last 24 hours.

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

AccountPurchaseCount:   Cardholder Account Purchase Count.

Number of purchases with this cardholder account during the previous six months.

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

AccountYearTransactions:   Number of account transactions in the last year.

Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year.

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

ACSChallengeMandatedIndicator:   ACS Challenge Mandated Indicator.

Indication of whether a challenge is required for the transaction to be authorized due to local/regional mandates or other variable. Required in ARes messages if TransactionStatus = C.

ACSOperatorId:   ACS identifier assigned by DS.

Each DS can provide a unique ID to each ACS on an individual basis. Requirements for the presence of this field in ARes messages are DS specific. Any individual DS may impose special formatting and character requirements on the contents of this field.

ACSReferenceNumber:   Unique ACS Reference Number.

Returned from the directory server in the Authentication Response Message (ARes), this field contains a unique identifier for the ACS. Used by the DS to identify the ACS and passed along to the Server in the ARes. This field will be set after a successful call to SendAuthRequest.

ACSRenderingInterface:   Challenge interface type presented to cardholder.

This setting specifies the ACS interface that must be used to present the challenge to the cardholder in an app-based flow. This setting is populated after calling CheckAuthResponse in the Client and SendAuthRequest in the 3DS Server. This is also populated after calling CheckResponse and passing the Results Request Message.

Possible values are:

01 Native UI
02 HTML UI

ACSRenderingUITemplate:   Challenge type presented to cardholder.

This setting holds the type of challenge that will be presented to the cardholder in an app-based flow. This setting is populated after calling CheckAuthResponse in the Client and SendAuthRequest in the 3DS Server. This is also populated after calling CheckResponse and passing the Results Request Message.

Possible values are:

01 Text
02 Single Select
03 Multi Select
04 OOB
05 HTML Other (valid only for HTML UI)

ACSSignedContent:   String value of the JWS object of the ARes message created by the ACS.

Contains the JWS object created by the ACS for the ARes message. The JWS object body contains the ACSURL, the ACS Ephemeral Public Key, and the SDK Ephemeral Public Key (available in the SDKEphemeralPublicKey configuration setting). These values will be used by the Client to confirm the authenticity of the ACS.

This setting is only applicable to the app-based flow and is informational. It does not need to be queried or set in most cases.

ACSTransactionId:   Unique transaction identifier assigned by the ACS.

This field contains a universally unique transaction identifier assigned by the ACS to identify a single transaction.

AddressMatch:   Address Match Indicator.

This field is used to indicate to the ACS whether the cardholder shipping address and billing address are the same.

YShipping address matches billing address.
NShipping address does not match billing address.

AllowNullMethodURL:   Allow null MethodURL when retrieving card ranges.

According to the EMVCo specification, if no MethodURL is available, the field should be omitted from the card ranges response. In some cases, however, the directory server has returned a "null" string instead. This is false by default, and this invalid data will result in an error raised by the RequestCardRanges method. Setting this configuration setting to true will allow a null MethodURL in the card range data.

AuthenticationType:   Type of authentication method used by the issuer.

After SendAuthRequest, this will be set if TransactionStatus is C or D and indicates the type of authentication method that will be used to challenge the cardholder. When a Results Request Message (RReq) is parsed, this will be set if the TransactionStatus is Y or N and indicates the authentication method that was used during the challenge.

Possible values include:

01Static
02Dynamic
03OOB
04Decoupled

BroadInfo:   Broadcast Information.

Unstructured information sent between the 3DS server, the DS, and the ACS.

CardholderInformation:   Information text presented to Cardholder during the transaction.

Text provided in ARes by the ACS/Issuer to Cardholder during a Frictionless or Decoupled transaction. The Issuer can provide information to Cardholder. If populated, this information is required to be conveyed to the cardholder. Required if DecoupledConfirmationIndicator is Y.

ChallengeCancellationIndicator:   Challenge Cancellation Indicator.

Indicator informing the ACS and the DS that the authentication has been canceled. Required in CReq for app-based if the authentication transaction was canceled for any of the reasons available as values. Required in the RReq if the ACS identifies that the authentication transaction was canceled for reasons indicated.

Possible values are:

01 Cardholder selected "Cancel" by interaction with the cancellation button in the UI
02 3DS Requestor canceled Authentication
03 Transaction Abandoned
04 Transaction Timed out at ACS - other timeouts
05 Transaction Timed out at ACS - First CReq not received by ACS
06 Transaction Error
07 Unknown
08-79 Reserved for future EMV/Co use (values invalid until defined by EMVCo)
80-99 Reserved for future DS use

ChallengeTimeRemaining:   Amount of time left to complete challenge.

This field contains the time remaining to complete the challenge. This is based on the SDKMaxTimeout set when issuing the initial Authorization Request Message.

ClearCustomRequestFields:   Clear the custom request fields internal collection.

When PersistCustomRequestFields is true, the component will store request fields specified via the AddRequestField method to use for future generated requests. This configuration setting can be used to clear this internal collection.

ContinueParsingCardRangesOnError:   Whether or not to continue parsing card ranges when a validation error is encountered.

When RequestCardRanges is called, the class will parse the card ranges returned in the PRes response packet. By default, if an error is encountered, the component will stop parsing, send an Erro packet to the Directory Server, and throw an exception. This setting can be used to instruct the component to continue parsing the card ranges, and adding the ranges that do not fail validation to the CardRanges collection prior to raising the error. The default value is False.

DecoupledConfirmationIndicator:   ACS Decoupled Confirmation Indicator.

Returned in the authentication response, and indicates whether the ACS confirms utilization of Decoupled Authentication and agrees to utilize Decoupled Authentication to authenticate the Cardholder.

Possible values are:

Y Confirms decoupled authentication will be utilized.
N Decoupled authentication will not be utilized.

Note that if the 3DS Requestor decoupled request indicator = N, a value of Y cannot be returned. If the TransactionStatus is D, a value of N is not valid.

DecoupledMaxTimeout:   3DS Requestor Decoupled Max Time.

Indicates the maximum amount of time that the 3DS Requestor will wait for an ACS to provide the results of a Decoupled Authentication transaction (in minutes). Set prior to calling SendAuthRequest if allowing decoupled authentication.

DecoupledRequestIndicator:   3DS Requestor Decoupled Request Indicator.

Indicates whether the 3DS Requestor requests the ACS to utilize Decoupled Authentication and agrees to utilize Decoupled Authentication if the ACS confirms its use.

Possible values are:

Y Decoupled authentication is supported and preferred if challenge is necessary.
N Do not use decoupled authentication.

Note that if the element is not provided (default), the ACS would interpret this equivalent to a value of N.

DecoupledTimeRemaining:   Time remaining before a RReq should be received during a decoupled authentication.

When performing decoupled authentication, the 3DS Server will wait DecoupledMaxTimeout seconds for a Results Request (RReq) packet from the Directory Server indicating the results of the authentication. Generally, the ACS should send the RReq before the specified max time expires, even if authentication has not succeeded. If not successful, this would be indicated in the RReq. This config can be used to help track the time remaining before this RReq should be received, and is based on DecoupledMaxTimeout + 30 seconds.

DeliveryEmailAddress:   Merchandise Delivery Email Address.

The email address to which the merchandise was delivered for Electronic delivery.

An element of the Merchant Risk Indicator applicable in AReq messages, which is optional but strongly recommended to include. The data elements making up the Indicator will be formatted into a JSON object prior to being placed into the Device Merchant Risk Indicator field of the message. The Indicator is the Merchant's assessment of the level of fraud risk for the specific authentication for both the cardholder and the authentication being conducted.

The complete list of elements (all available as config settings) comprising the Merchant Risk Indicator is:

  • DeliveryEmailAddress
  • DeliveryTimeframe
  • GiftCardAmount
  • GiftCardCount
  • GiftCardCurrency
  • PreOrderDate
  • PreOrderPurchaseIndicator
  • ReorderItemsIndicator
  • ShipIndicator

DeliveryTimeframe:   Merchandise Delivery Timeframe.

Indicates the merchandise delivery timeframe.

Possible values are:

01 Electronic Delivery
02 Same day shipping
03 Overnight shipping
04 Two-day or more shipping

An element of the Merchant Risk Indicator applicable in AReq messages, which is optional but strongly recommended to include. See the DeliveryEmailAddress configuration setting for the complete list of elements (all available as config settings) comprising the Merchant Risk Indicator.

DSEndProtocolVersion:   DS End Protocol Version.

The most recent active protocol version that is supported for the directory server. This is the default value included in the PRes packet returned from the server during a call to RequestCardRanges. If the DSEndProtocolVersion is not specified (i.e. empty) at the CardRanges level, this should be utilized.

DSReferenceNumber:   DS Reference Number.

EMVCo-assigned unique identifier to track approved DS. The DS will populate the AReq with this element prior to passing to the ACS, and it will be returned in the ARes.

DSStartProtocolVersion:   DS Start Protocol Version.

The earliest (i.e. oldest) active protocol version that is supported for the directory server. This is the default value included in the PRes packet returned from the server during a call to RequestCardRanges. If the DSStartProtocolVersion is not specified (i.e. empty) at the CardRanges level, this should be utilized.

DSTransactionId:   Directory server transaction ID.

Universally unique transaction identifier assigned by the directory server to identify a single transaction.

EMVPaymentTokenIndicator:   EMV Payment Token Indicator.

A value of true indicates that the transaction was de-tokenised prior to being received by the ACS. This data element will be populated by the system residing in the 3-D Secure domain where the de-tokenization occurs (i.e., the 3DS Server or the DS). The Boolean value of true is the only valid response for this field when it is present. Required in CReq if there is a de-tokenization of an Account Number.

EMVPaymentTokenSource:   EMV Payment Token Source.

Indicates where the payment token was detokenized.

Valid values are:

01 3DS Server
02 DS

This is required to be set if EMVPaymentTokenIndicator is true.

EncodedSessionData:   Encoded session data that is sent in the challenge request and returned in the challenge response.

This setting holds the encoded version of SessionData after GetChallengeRequest is called. This may be set in the threeDSSessionData form variable in the post made in the challenge window.

When the ACS POSTs the final challenge response to the NotificationURL this setting may be set to the threeDSSessionData form variable value, and SessionData setting may then be queried to return the decoded session data.

ErrorCode:   Code from the last error message.

Code indicating the type of problem identified in the error message.

ErrorDescription:   Description from the last error message.

Text describing the problem identified in the error message.

ErrorDetail:   Additional details from the last error message.

Additional detail regarding the problem identified in the error message.

ExtractRReqServerTransactionId:   Extacts the ServerTransactionId from the RReq packet.

This setting can be used to extract the ServerTransactionId from the RReq packet. This field can then be used to look up details on the transaction prior to parsing the RReq packet using the CheckResponse method. Set this to the received RReq packet data and the ServerTransactionId will be returned from the Config method.

GiftCardAmount:   Total gift card(s) amount.

For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units (for example, USD 123.45 is 123).

An element of the Merchant Risk Indicator applicable in AReq messages, which is optional but strongly recommended to include. See the DeliveryEmailAddress configuration setting for the complete list of elements (all available as config settings) comprising the Merchant Risk Indicator.

GiftCardCount:   Total number of gift cards purchased.

For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.

An element of the Merchant Risk Indicator applicable in AReq messages, which is optional but strongly recommended to include. See the DeliveryEmailAddress configuration setting for the complete list of elements (all available as config settings) comprising the Merchant Risk Indicator.

GiftCardCurrency:   Gift Card Currency.

For prepaid or gift card purchase, the currency code of the card.

An element of the Merchant Risk Indicator applicable in AReq messages, which is optional but strongly recommended to include. See the DeliveryEmailAddress configuration setting for the complete list of elements (all available as config settings) comprising the Merchant Risk Indicator.

IncomingExtensionCount:   The number of extensions received from the directory server.

This setting holds the number of extensions received in the last message from the directory server. The individual extension data can be accessed via the IncomingExtensionId, $rcfgIncomingExtensionName;, IncomingExtensionCritical, and IncomingExtensionData settings.

IncomingExtensionCritical[Index]:   Whether the extension is critical.

This setting specifies whether the recipient must understand the contents of the extension to interpret the entire message.

IncomingExtensionData[Index]:   The extension data as JSON.

This setting specifies the JSON formatted extension data.

IncomingExtensionId[Index]:   The id of the specified extension.

This setting specifies a unique identifier for the extension.

IncomingExtensionName[Index]:   The extension name.

This setting specifies the name of the extension as defined by the extension owner.

IncomingRawExtensions:   The full JSON formatted extension data received from the directory server.

This setting holds the full JSON formatted extension data that was received in the last message from the directory server. This corresponds to the value for the messageExtension JSON object defined in the specification.

InstalmentPaymentData:   Max authorizations permitted for installment payments.

Indicates maximum number of authorizations permitted for installment payments. Required in AReq messages if the Merchant and Cardholder have agree to installment payments (AuthenticationIndicator = 03). Value must be greater than 1.

InteractionCounter:   Interaction Counter.

Indicates the number of authentication cycles attempted by the cardholder. Value to be tracked by the ACS and present in the Results Response Message (RRes).

LogLevel:   Level of logging enabled.

This config specifies the level of logging enabled in the component. Possible values include:

0 (None)No events are logged.
1 (Info - default)Informational events are logged.
2 (Verbose)Detailed data is logged.
3 (Debug)Debug data is logged.

This is set to 1 (Info) by default.

MaskSensitive:   Whether to mask sensitive data in the Log event.

This setting controls whether sensitive data is masked in the Log event. When set to True (default) the CardNumber value will be replaced with the value *************.

Note: DataPacketOut will always contain the raw unmasked value regardless of this setting. This setting only applies to the Log event.

The default value is True.

MessageType:   Type of message that is passed.

This field identifies the type of the message being transmitted.

Possible values include:

AReqAuthentication Request Message
AResAuthentication Response Message
CReqChallenge Request Message
CResChallenge Response Message
PReqPreparation Request Message
PResPreparation Response Message
RReqResults Request Message
RResResults Response Message
ErroError Message

This setting is read-only.

MethodCompletionIndicator:   3DS Method Completion Indicator.

Indicates whether the 3DS Method was successfully completed or not. This is included in the Authorization Request Message (AReq) sent by the SendAuthRequest method. Possible values are:

Y (default)Successfully completed.
NDid not successfully complete.
UUnavailable. 3DS Method URL was not present in the PRes message data for the card range associated with the Cardholder Account Number.

OutgoingRawExtensions:   The full JSON formatted extension data sent to the directory server.

This setting holds the full JSON formatted extension data that will be included in the next outgoing packet. This corresponds to the value for the messageExtension JSON object defined in the specification.

Note: When sending extension data it is generally recommended to use Extensions instead of this setting.

PaymentAccountAge:   Payment Account Age.

Date that the payment account was enrolled in the cardholder's account with the 3DS Requestor. Accepted date format is YYYYMMDD.

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

PaymentAccountAgeIndicator:   Payment Account Age Indicator.

Indicates the length of time that the payment account was enrolled in the cardholder's account with the 3DS Requestor.

Possible values are:

01 No account (guest check-out)
02 Created during this transaction
03 Less than 30 days
04 30-60 days
05 More than 60 days

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

PersistCustomRequestFields:   Whether or not to store custom request fields for subsequent requests.

By default, fields added using the AddRequestField method are used once in the next generated requests and disposed of. When this configuration setting is set to true (false by default), the component will store these fields for use in subsequent requests. The ClearCustomRequestFields can then be used to clear the internal collection.

PreOrderDate:   Expected date pre-ordered purchase will be available.

For a pre-ordered purchase, the expected date that the merchandise will be available. Accepted date format is YYYYMMDD.

An element of the Merchant Risk Indicator applicable in AReq messages, which is optional but strongly recommended to include. See the DeliveryEmailAddress configuration setting for the complete list of elements (all available as config settings) comprising the Merchant Risk Indicator.

PreOrderPurchaseIndicator:   Pre-Order Purchase Indicator.

Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.

Possible values are:

01 Merchandise available
02 Future availability

An element of the Merchant Risk Indicator applicable in AReq messages, which is optional but strongly recommended to include. See the DeliveryEmailAddress configuration setting for the complete list of elements (all available as config settings) comprising the Merchant Risk Indicator.

PriorAuthData:   3DS Requestor Prior Transaction Authentication Data.

Data that documents and supports a specific authentication process.

Part of the optional 3DS Requestor Prior Transaction Authentication Information that contains information about a 3DS cardholder authentication that occurred prior to the current transaction.

In the current version of the specification this data element is not defined in detail, however the intention is that for each 3DS Requestor Authentication Method, this field carry data that the ACS can use to verify the authentication process. In future versions of the specification, these details are expected to be included.

PriorAuthMethod:   3DS Requestor Prior Transaction Authentication Method.

Mechanism used by the Cardholder to previously authenticate to the 3DS Requestor.

Part of the optional 3DS Requestor Prior Transaction Authentication Information that contains information about a 3DS cardholder authentication that occurred prior to the current transaction.

Possible values are:

01 Frictionless authentication occurred by ACS
02 Cardholder challenge occurred by ACS
03 ACS verified
04 Other issuer methods
05-79 Reserved for future EMVCo use (values invalid until defined by EMVCo)
80-99 Reserved for DS use

PriorAuthTimestamp:   3DS Requestor Prior Transaction Authentication Timestamp.

Date and time in UTC of the prior cardholder authentication. Accepted date format is YYYYMMDDHHMM.

Part of the optional 3DS Requestor Prior Transaction Authentication Information that contains information about a 3DS cardholder authentication that occurred prior to the current transaction.

PriorReference:   3DS Requestor Prior Transaction Reference.

This data element provides additional information to the ACS to determine the best approach for handling a request. It contains an ACS Transaction ID for a prior authenticated transaction (for example, the first recurring transaction that was authenticated with the cardholder).

Part of the optional 3DS Requestor Prior Transaction Authentication Information that contains information about a 3DS cardholder authentication that occurred prior to the current transaction.

ProtocolVersion:   Protocol version identifier.

This field indicates the protocol version. This should be the protocol version number of the specification utilized by the system creating this message. By default, this is set to 2.1.0. The most recent version of the protocol is 2.2.0.

ReorderItemsIndicator:   Reorder Items Indicator.

Indicates whether the cardholder is reordering previously purchased merchandise.

Possible values are:

01 First time ordered
02 Reordered

An element of the Merchant Risk Indicator applicable in AReq messages, which is optional but strongly recommended to include. See the DeliveryEmailAddress configuration setting for the complete list of elements (all available as config settings) comprising the Merchant Risk Indicator.

ReqAuthData:   3DS Requestor Authentication Data.

Data that documents and supports a specific authentication process. In the current version of the specification, this data element is not defined in detail, however the intention is that for each 3DS Requestor Authentication Method, this field carry data that the ACS can use to verify the authentication process.

Part of the 3DS Requestor Authentication Information which contains optional information about how the cardholder authenticated during login to their 3DS Requestor account.

ReqAuthMethod:   3DS Requestor Authentication Method.

Method used by the Cardholder to authenticate to the 3DS Requestor.

Part of the 3DS Requestor Authentication Information which contains optional information about how the cardholder authenticated during login to their 3DS Requestor account.

Possible values are:

01 No 3DS Requestor authentication occurred (i.e. cardholder "logged in" as guest)
02 Login to the cardholder account at the 3DS Requestor system using 3DS Requestor's own credentials
03 Login to the cardholder account at the 3DS Requestor system using federated ID
04 Login to the cardholder account at the 3DS Requestor system using issuer credentials
05 Login to the cardholder account at the 3DS Requestor system using third-party authentication
06 Login to the cardholder account at the 3DS Requestor system using FIDO Authenticator
07-79 Reserved for EMVCo future use (values invalid until defined by EMVCo)
80-99 Reserved for future DS use

ReqAuthTimestamp:   3DS Requestor Authentication Timestamp.

Date and time in UTC of the cardholder authentication. Accepted date format is YYYYMMDDHHMM.

Part of the 3DS Requestor Authentication Information which contains optional information about how the cardholder authenticated during login to their 3DS Requestor account.

RequestorChallengeInd:   3DS Requestor Challenge Indicator.

Indicates whether a challenge is requested for this transaction. For example: For MessageCategory 01 (PA), a 3DS Requestor may have concerns about the transaction, and request a challenge. For 02 (NPA), a challenge may be necessary when adding a new card to a wallet. Allows 3DS Requestor to request a challenge such as to follow local/regional mandates or other variables.

Possible values are:

01 No preference
02 No challenge requested
03 Challenge requested: 3DS Requestor Preference
04 Challenge requested: Mandate
05 No challenge requested (transactional risk analysis is already performed). Valid for ProtocolVersion 2.2.0 only
06 No challenge requested (data share only). Valid for ProtocolVersion 2.2.0 only
07 No challenge requested (strong consumer authentication is already performed). Valid for ProtocolVersion 2.2.0 only
08 No challenge requested (utilize whitelist exemption if no challenge required). Valid for ProtocolVersion 2.2.0 only
09 Challenge requested (whitelist prompt requested if challenge required). Valid for ProtocolVersion 2.2.0 only
10-79 Reserved for EMVCo future use (values invalid until defined by EMVCo)
80-99 Reserved for future DS use

If not provided, the ACS action would be identical to 01 (no preference).

ResendRequestCardRanges:   Whether or not to resend the card ranges request.

If an error is identified with the card range data received from the directory server when calling the RequestCardRanges method, this configuration setting will be true, indicating that the request should be resent. When resending, if SerialNumber was specified for the initial request, it should be set to an empty string before calling RequestCardRanges again. Otherwise, the request can be sent without the serial number again, but the server may respond with an error due to multiple requests within an hour.

ServerOperatorId:   3DS Server identifier.

Directory server assigned 3DS Server identifier. This may be assigned by a directory server. If this is assigned it should be set here.

SessionData:   Session data that is sent in the challenge request and returned in the challenge response.

This setting specifies session information that may be used to associate the notification of challenge completion with the original transaction. This may be set before calling GetChallengeRequest.

When the ACS POSTs the final challenge response to the NotificationURL the EncodedSessionData may be set to the threeDSSessionData form variable value, and this setting may then be queried to return the decoded session data.

ShipAddressUsageDate:   Shipping address first usage date.

Date when the shipping address used for this transaction was first used with the 3DS Requestor. Accepted date format is YYYYMMDD.

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

ShipAddressUsageIndicator:   Shipping address usage indicator.

Indicates the length of time since the shipping address used for this transaction was first used with the 3DS Requestor.

Possible values are:

01 This transaction
02 Less than 30 days
03 30-60 days
04 More than 60 days

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

ShipIndicator:   Shipping method indicator.

Indicates shipping method chosen for the transaction. Merchants must choose the Shipping Indicator code that most accurately describes the cardholder's specific transaction, not their general business. If one or more items are included in the sale, the Shipping Indicator code for the physical goods is used, or if all digital goods, the Shipping Indicator code that describes the most expensive item.

Possible values are:

01 Ship to cardholder's billing address
02 Ship to another verified address on file with merchant
03 Ship to address that is different than the cardholder's billing address
04 "Ship to Store" / Pick-up at local store (Store address shall be populated in shipping address fields)
05 Digital goods (includes online services, electronic gift cards and redemption codes)
06 Travel and Event tickets, not shipped
07 Other (for example, Gaming, digital services not shipped, emedia subscriptions, etc.)

An element of the Merchant Risk Indicator applicable in AReq messages, which is optional but strongly recommended to include. See the DeliveryEmailAddress configuration setting for the complete list of elements (all available as config settings) comprising the Merchant Risk Indicator.

ShipNameIndicator:   Shipping Name Indicator.

Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction.

Possible values are:

01 Account Name identical to shipping Name
02 Account Name different than shipping Name

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

StoreCardRangeData:   Whether or not to store the card ranges in the CardRanges collection.

Indicates whether or not the component should store card ranges in the internal CardRanges collection after the RequestCardRanges method completes. When False, the card range data will only be available via the CardRange event. This can be useful in limiting memory usage of the component, especially when large amounts of ranges are returned.

The default value is True.

SuspiciousAccountActivity:   Suspicious account activity indicator.

Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.

Possible values are:

01 No suspicious activity has been observed
02 Suspicious activity has been observed

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

ThreeRIIndicator:   3RI Indicator.

Indicates the type of 3RI request. This data element provides additional information to the ACS to determine the best approach for handing a 3RI request. Included in the Authorization Request Message (ARes) sent by the SendAuthRequest. Valid when DeviceChannel is set to "03," indicating 3RI.

Possible values are:

01Recurring transaction
02Installment transaction
03Add card
04Maintain card information
05Account verification
06Split/delayed shipment
07Top-up
08Mail Order
09Telephone Order
10Whitelist status check
11Other payment

Values of 06-11 are only applicable when ProtocolVersion is 2.2.0.

TransactionStatusReason:   Reason for value of TransactionStatus.

Provides information on why the Transaction Status field has the specified value. For MessageCategory 01 (PA), always included when TransactionStatus = N, U, or R. For MessageCategory 02 (NPA), as defined by the DS.

Possible values are:

01 Card authentication failed
02 Unknown device
03 Unsupported device
04 Exceeds authentication frequency limit
05 Expired card
06 Invalid card number
07 Invalid transaction
08 No Card record
09 Security failure
10 Stolen card
11 Suspected fraud
12 Transaction not permitted to cardholder
13 Cardholder not enrolled in service
14 Transaction timed out at the ACS
15 Low confidence
16 Medium confidence
17 High confidence
18 Very high confidence
19 Exceeds ACS maximum challenges
20 Non-Payment transaction non supported
21 3RI transaction not supported
22 ACS technical issue
23 Decoupled Authentication required by ACS but not requested by 3DS Requestor
24 3DS Requestor Decoupled Max Expiry Time exceeded
25 Decoupled Authentication was provided insufficient time to authenticate cardholder. ACS will not make attempt
26 Authentication attempted but not performed by the cardholder
27-79 Reserved for future EMVCo use (values invalid until defined by EMVCo)
80-99 Reserved for DS use

TransactionType:   Transaction Type.

Identifies the type of transaction being authenticated. This field is required in AReq messages in some markets (e.g. for Merchants in Brazil). Otherwise, optional.

Possible values (derived from ISO Standard) are:

01 Goods/ Service Purchase
03 Check Acceptance
10 Account Funding
11 Quasi-Cash Transaction
28 Prepaid Activation and Load

UseAESGCM:   Whether or not to use AESGCM as the encryption algorithm.

By default, the component will use JWS_ENC_ALG_ID_A128CBC_HS256AES when encrypting packets to send to the ACS. Setting this to true will instruct the component to use JWE_ENC_ALG_ID_A128GCM instead.

UseJsonDOM:   Whether or not the component should build an internal DOM when parsing card ranges.

When the RequestCardRanges method is called, by default the component will construct an internal DOM (Document Object Model) when parsing the returned data. When set to False, this will instruct the component not to build this model, which can be useful in limiting memory usage of the component, especially when large amounts of ranges are returned.

The default value is True. Note that when False, the XPath settings will not be available.

WhitelistStatus:   Whitelist Status.

Enables the communication of trusted beneficiary/whitelist status between the ACS, the DS and the 3DS Requestor.

Y 3DS Requestor is whitelisted by cardholder
N 3DS Requestor is not whitelisted by cardholder
E Not eligible as determined by issuer
P Pending confirmation by cardholder
R Cardholder rejected
U Whitelist status unknown, unavailable, or does not apply

This may be set prior to calling the SendAuthRequest method. In this case, only values of Y or N are valid. This may also be set when the Authentication Response message or Results Request messages are received, and will be set to the values received from the Directory Server.

WhitelistStatusSource:   Whitelist Status Source.

The system setting the Whitelist Status. When setting WhitelistStatus prior to calling the SendAuthRequest method, this should be set to 01. Possible values are:

01 3DS Server
02 DS
03 ACS

XChildCount:   The number of child elements of the current element.

The number of child attributes of the current element. The XChild configuration settings will be indexed from 0 to (XChildCount - 1).

The current element is specified via the XPath configuration setting. This configuration setting is read-only.

XChildName[i]:   The name of the child element.

Provides the name of the i'th child element of the current element.

The current element is specified via the XPath configuration setting. This configuration setting is read-only.

XChildXText[i]:   The inner text of the child element.

Provides the inner text of the i'th child element of the current element.

The current element is specified via the XPath configuration setting. This configuration setting is read-only.

XElement:   The name of the current element.

Provides the name of the current element.

The current element is specified via the XPath configuration setting. This configuration setting is read-only.

XParent:   The parent of the current element.

Provides the parent of the current element.

The current element is specified via the XPath configuration setting. This configuration setting is read-only.

XPath:   Provides a way to point to a specific element in the returned XML or JSON response.

The XPath setting allows you to point to specific elements in the XML or JSON response.

When XPath is set to a valid path, XElement points to the name of the element, with XText, XParent, XSubTree, XChildCount, XChildName[i], and XChildXText[i] providing other properties of the element.

XPath Syntax

XPath syntax is available for both XML and JSON documents. An XPath is a series of one or more element accessors separated by the / character, for example: /A/B/C/D. An XPath can be absolute (i.e., it starts with /), or it can be relative to the current XPath location.

The following are possible values for an element accessor, which operates relative to the current location specified by the XPath accessors which proceed it in the overall XPath string:

Accessor Description
name The first element with a particular name. Can be *.
[i] The i-th element.
name[i] The i-th element with a particular name.
[last()] The last element.
[last()-i] The element i before the last element.
name[@attrname="attrvalue"]The first element with a particular name that contains the specified attribute-value pair.
Supports single and double quotes. (XML Only)
. The current element.
.. The parent element.

Note: XPath indices are 1-based.

XPath Examples

Assuming the following XML response:

<firstlevel>
  <one>value</one>
  <two>
    <item>first</item>
    <item>second</item>
  </two>
  <three>value three</three>
</firstlevel>

Or, alternatively, the following JSON response:

{
  "firstlevel": {
    "one": "value",
    "two": ["first", "second"],
    "three": "value three"
  }
}

Here are some examples of valid XPaths:

DescriptionXML XPath JSON XPath
Document root / /json
Specific element /firstlevel/one /json/firstlevel/one
i-th child /firstlevel/two/item[2]/json/firstlevel/two/[2]

This is not an exhaustive list by any means, but should provide a general idea of the possibilities.

XSubTree:   A snapshot of the current element in the document.

Provides the entirety of the current element (including its sub-elements).

The current element is specified via the XPath configuration setting. This configuration setting is read-only.

XText:   The text of the current element.

Provides the inner text of the current element.

The current element is specified in the XPath configuration setting. This configuration setting is read-only.

SSL Configuration Settings

LogSSLPackets:   Controls whether SSL packets are logged when using the internal security API.

When the UseInternalSecurityAPI configuration setting is True, this setting controls whether SSL packets should be logged. By default, this setting is False, as it is only useful for debugging purposes.

When enabled, SSL packet logs are output using the SSLStatus event, which will fire each time an SSL packet is sent or received.

Enabling this setting has no effect if UseInternalSecurityAPI is False.

OpenSSLCADir:   The path to a directory containing CA certificates.

This functionality is available only when the provider is OpenSSL.

The path set by this property should point to a directory containing CA certificates in PEM format. The files each contain one CA certificate. The files are looked up by the CA subject name hash value, which must hence be available. If more than one CA certificate with the same name hash value exist, the extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). OpenSSL recommends to use the c_rehash utility to create the necessary links. Please refer to the OpenSSL man page SSL_CTX_load_verify_locations(3) for details.

OpenSSLCAFile:   Name of the file containing the list of CA's trusted by your application.

This functionality is available only when the provider is OpenSSL.

The file set by this property should contain a list of CA certificates in PEM format. The file can contain several CA certificates identified by

-----BEGIN CERTIFICATE-----

... (CA certificate in base64 encoding) ...

-----END CERTIFICATE-----

sequences. Before, between, and after the certificates text is allowed which can be used e.g. for descriptions of the certificates. Please refer to the OpenSSL man page SSL_CTX_load_verify_locations(3) for details.

OpenSSLCipherList:   A string that controls the ciphers to be used by SSL.

This functionality is available only when the provider is OpenSSL.

The format of this string is described in the OpenSSL man page ciphers(1) section "CIPHER LIST FORMAT". Please refer to it for details. The default string "DEFAULT" is determined at compile time and is normally equivalent to "ALL:!ADH:RC4+RSA:+SSLv2:@STRENGTH".

OpenSSLPrngSeedData:   The data to seed the pseudo random number generator (PRNG).

This functionality is available only when the provider is OpenSSL.

By default OpenSSL uses the device file "/dev/urandom" to seed the PRNG and setting OpenSSLPrngSeedData is not required. If set, the string specified is used to seed the PRNG.

ReuseSSLSession:   Determines if the SSL session is reused.

If set to true, the class will reuse the context if and only if the following criteria are met:

  • The target host name is the same.
  • The system cache entry has not expired (default timeout is 10 hours).
  • The application process that calls the function is the same.
  • The logon session is the same.
  • The instance of the class is the same.

SSLCACertFilePaths:   The paths to CA certificate files on Unix/Linux.

This setting specifies the paths on disk to CA certificate files on Unix/Linux.

The value is formatted as a list of paths separated by semicolons. The class will check for the existence of each file in the order specified. When a file is found the CA certificates within the file will be loaded and used to determine the validity of server or client certificates.

The default value is:

/etc/ssl/ca-bundle.pem;/etc/pki/tls/certs/ca-bundle.crt;/etc/ssl/certs/ca-certificates.crt;/etc/pki/tls/cacert.pem

SSLCACerts:   A newline separated list of CA certificate to use during SSL client authentication.

This setting specifies one or more CA certificates to be included in the request when performing SSL client authentication. Some servers require the entire chain, including CA certificates, to be presented when performing SSL client authentication. The value of this setting is a newline (CrLf) separated list of certificates. For instance:


-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
..
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

SSLCipherStrength:   The minimum cipher strength used for bulk encryption.

This minimum cipher strength largely dependent on the security modules installed on the system. If the cipher strength specified is not supported, an error will be returned when connections are initiated.

Please note that this setting contains the minimum cipher strength requested from the security library. The actual cipher strength used for the connection is shown by the SSLStatus event.

Use this setting with caution. Requesting a lower cipher strength than necessary could potentially cause serious security vulnerabilities in your application.

When the provider is OpenSSL, SSLCipherStrength is currently not supported. This functionality is instead made available through the OpenSSLCipherList config setting.

SSLEnabledCipherSuites:   The cipher suite to be used in an SSL negotiation.

The enabled cipher suites to be used in SSL negotiation.

By default, the enabled cipher suites will include all available ciphers ("*").

The special value "*" means that the class will pick all of the supported cipher suites. If SSLEnabledCipherSuites is set to any other value, only the specified cipher suites will be considered.

Multiple cipher suites are separated by semicolons.

Example values when UseInternalSecurityAPI is False (default):

obj.config("SSLEnabledCipherSuites=*");
obj.config("SSLEnabledCipherSuites=CALG_AES_256");
obj.config("SSLEnabledCipherSuites=CALG_AES_256;CALG_3DES");
Possible values when UseInternalSecurityAPI is False (default) include:
  • CALG_3DES
  • CALG_3DES_112
  • CALG_AES
  • CALG_AES_128
  • CALG_AES_192
  • CALG_AES_256
  • CALG_AGREEDKEY_ANY
  • CALG_CYLINK_MEK
  • CALG_DES
  • CALG_DESX
  • CALG_DH_EPHEM
  • CALG_DH_SF
  • CALG_DSS_SIGN
  • CALG_ECDH
  • CALG_ECDH_EPHEM
  • CALG_ECDSA
  • CALG_ECMQV
  • CALG_HASH_REPLACE_OWF
  • CALG_HUGHES_MD5
  • CALG_HMAC
  • CALG_KEA_KEYX
  • CALG_MAC
  • CALG_MD2
  • CALG_MD4
  • CALG_MD5
  • CALG_NO_SIGN
  • CALG_OID_INFO_CNG_ONLY
  • CALG_OID_INFO_PARAMETERS
  • CALG_PCT1_MASTER
  • CALG_RC2
  • CALG_RC4
  • CALG_RC5
  • CALG_RSA_KEYX
  • CALG_RSA_SIGN
  • CALG_SCHANNEL_ENC_KEY
  • CALG_SCHANNEL_MAC_KEY
  • CALG_SCHANNEL_MASTER_HASH
  • CALG_SEAL
  • CALG_SHA
  • CALG_SHA1
  • CALG_SHA_256
  • CALG_SHA_384
  • CALG_SHA_512
  • CALG_SKIPJACK
  • CALG_SSL2_MASTER
  • CALG_SSL3_MASTER
  • CALG_SSL3_SHAMD5
  • CALG_TEK
  • CALG_TLS1_MASTER
  • CALG_TLS1PRF
Example values when UseInternalSecurityAPI is True:
obj.config("SSLEnabledCipherSuites=*");
obj.config("SSLEnabledCipherSuites=TLS_DHE_DSS_WITH_AES_128_CBC_SHA");
obj.config("SSLEnabledCipherSuites=TLS_DHE_DSS_WITH_AES_128_CBC_SHA;TLS_DH_ANON_WITH_AES_128_CBC_SHA");
Possible values when UseInternalSecurityAPI is True include:
  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_RSA_WITH_AES_256_GCM_SHA384
  • TLS_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_DHE_DSS_WITH_AES_256_GCM_SHA384
  • TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256
  • TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_DHE_DSS_WITH_AES_128_GCM_SHA256
  • TLS_DH_RSA_WITH_AES_128_GCM_SHA256 (Not Recommended)
  • TLS_DH_RSA_WITH_AES_256_GCM_SHA384 (Not Recommended)
  • TLS_DH_DSS_WITH_AES_128_GCM_SHA256 (Not Recommended)
  • TLS_DH_DSS_WITH_AES_256_GCM_SHA384 (Not Recommended)
  • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384
  • TLS_DHE_DSS_WITH_AES_256_CBC_SHA256
  • TLS_RSA_WITH_AES_256_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
  • TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_RSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256
  • TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
  • TLS_RSA_WITH_AES_256_CBC_SHA
  • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
  • TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA
  • TLS_ECDH_RSA_WITH_AES_256_CBC_SHA
  • TLS_DHE_DSS_WITH_AES_256_CBC_SHA
  • TLS_RSA_WITH_AES_128_CBC_SHA
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
  • TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA
  • TLS_ECDH_RSA_WITH_AES_128_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA
  • TLS_DHE_DSS_WITH_AES_128_CBC_SHA
  • TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
  • TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA
  • TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA
  • TLS_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_RSA_WITH_DES_CBC_SHA
  • TLS_DHE_RSA_WITH_DES_CBC_SHA
  • TLS_DHE_DSS_WITH_DES_CBC_SHA
  • TLS_RSA_WITH_RC4_128_MD5
  • TLS_RSA_WITH_RC4_128_SHA

When TLS 1.3 is negotiated (see SSLEnabledProtocols) only the following cipher suites are supported:

  • TLS_AES_256_GCM_SHA384
  • TLS_CHACHA20_POLY1305_SHA256
  • TLS_AES_128_GCM_SHA256

SSLEnabledCipherSuites is used together with SSLCipherStrength.

SSLEnabledProtocols:   Used to enable/disable the supported security protocols.

Used to enable/disable the supported security protocols.

Not all supported protocols are enabled by default (the value of this setting is 4032). If you want more granular control over the enabled protocols, you can set this property to the binary 'OR' of one or more of the following values:

TLS1.312288 (Hex 3000)
TLS1.23072 (Hex C00) (Default)
TLS1.1768 (Hex 300) (Default)
TLS1 192 (Hex C0) (Default)
SSL3 48 (Hex 30)
SSL2 12 (Hex 0C)

When the provider is OpenSSL, SSLCipherStrength is currently not supported. This functionality is instead made available through the OpenSSLCipherList setting.

Note: TLS 1.1 and TLS1.2 support are only available starting with Windows 7.

Note: Enabling TLS 1.3 will automatically set UseInternalSecurityAPI to True.

SSLEnableRenegotiation:   Whether the renegotiation_info SSL extension is supported.

This setting specifies whether the renegotiation_info SSL extension will be used in the request when using the internal security API. This setting is true by default, but can be set to false to disable the extension.

This setting is only applicable when UseInternalSecurityAPI is set to true.

SSLIncludeCertChain:   Whether the entire certificate chain is included in the SSLServerAuthentication event.

This setting specifies whether the Encoded parameter of the SSLServerAuthentication event contains the full certificate chain. By default this value is False and only the leaf certificate will be present in the Encoded parameter of the SSLServerAuthentication event.

If set to True all certificates returned by the server will be present in the Encoded parameter of the SSLServerAuthentication event. This includes the leaf certificate, any intermediate certificate, and the root certificate.

SSLNegotiatedCipher:   Returns the negotiated ciphersuite.

Returns the ciphersuite negotiated during the SSL handshake.

Note: For server components (e.g. IPDaemon) this is a per-connection setting accessed by passing the ConnectionId. For example:

server.Config("SSLNegotiatedCipher[connId]");

SSLNegotiatedCipherStrength:   Returns the negotiated ciphersuite strength.

Returns the strength of the ciphersuite negotiated during the SSL handshake.

Note: For server components (e.g. IPDaemon) this is a per-connection setting accessed by passing the ConnectionId. For example:

server.Config("SSLNegotiatedCipherStrength[connId]");

SSLNegotiatedCipherSuite:   Returns the negotiated ciphersuite.

Returns the ciphersuite negotiated during the SSL handshake represented as a single string.

Note: For server components (e.g. IPDaemon) this is a per-connection setting accessed by passing the ConnectionId. For example:

server.Config("SSLNegotiatedCipherSuite[connId]");

SSLNegotiatedKeyExchange:   Returns the negotiated key exchange algorithm.

Returns the key exchange algorithm negotiated during the SSL handshake.

Note: For server components (e.g. IPDaemon) this is a per-connection setting accessed by passing the ConnectionId. For example:

server.Config("SSLNegotiatedKeyExchange[connId]");

SSLNegotiatedKeyExchangeStrength:   Returns the negotiated key exchange algorithm strength.

Returns the strenghth of the key exchange algorithm negotiated during the SSL handshake.

Note: For server components (e.g. IPDaemon) this is a per-connection setting accessed by passing the ConnectionId. For example:

server.Config("SSLNegotiatedKeyExchangeStrength[connId]");

SSLNegotiatedVersion:   Returns the negotiated protocol version.

Returns the protocol version negotiated during the SSL handshake.

Note: For server components (e.g. IPDaemon) this is a per-connection setting accessed by passing the ConnectionId. For example:

server.Config("SSLNegotiatedVersion[connId]");

SSLProvider:   The name of the security provider to use.

Change this setting to use security providers other than the system default.

Use this setting with caution. Disabling SSL security or pointing to the wrong provider could potentially cause serious security vulnerabilities in your application.

The special value "*" (default) picks the default SSL provider defined in the system.

Note: On Windows systems, the default SSL Provider is "Microsoft Unified Security Protocol Provider" and cannot be changed .

SSLSecurityFlags:   Flags that control certificate verification.

The following flags are defined (specified in hexadecimal notation). They can be or-ed together to exclude multiple conditions:

0x00000001Ignore time validity status of certificate.
0x00000002Ignore time validity status of CTL.
0x00000004Ignore non-nested certificate times.
0x00000010Allow unknown Certificate Authority.
0x00000020Ignore wrong certificate usage.
0x00000100Ignore unknown certificate revocation status.
0x00000200Ignore unknown CTL signer revocation status.
0x00000400Ignore unknown Certificate Authority revocation status.
0x00000800Ignore unknown Root revocation status.
0x00008000Allow test Root certificate.
0x00004000Trust test Root certificate.
0x80000000Ignore non-matching CN (certificate CN not-matching server name).

This functionality is currently not available when the provider is OpenSSL.

SSLServerCACerts:   A newline separated list of CA certificate to use during SSL server certificate validation.

This setting optionally specifies one or more CA certificates to be used when verifying the server certificate. When verifying the server's certificate the certificates trusted by the system will be used as part of the verification process. If the server's CA certificates are not installed to the trusted system store, they may be specified here so they are included when performing the verification process. This setting should only be set if the server's CA certificates are not already trusted on the system and cannot be installed to the trusted system store.

The value of this setting is a newline (CrLf) separated list of certificates. For instance:


-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
..
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

TLS12SignatureAlgorithms:   Defines the allowed TLS 1.2 signature algorithms when UseInternalSecurityAPI is True.

This setting specifies the allowed server certificate signature algorithms when UseInternalSecurityAPI is True and SSLEnabledProtocols is set to allow TLS 1.2.

When specified the class will verify that the server certificate signature algorithm is among the values specified in this setting. If the server certificate signature algorithm is unsupported the class fails with an error.

The format of this value is a comma separated list of hash-signature combinations. For instance:

IPPort.Config("UseInternalSecurityAPI=true");
IPPort.Config("SSLEnabledProtocols=3072"); //TLS 1.2
IPPort.Config("TLS12SignatureAlgorithms=sha256-rsa,sha256-dsa,sha1-rsa,sha1-dsa");
The default value for this setting is sha512-ecdsa,sha512-rsa,sha512-dsa,sha384-ecdsa,sha384-rsa,sha384-dsa,sha256-ecdsa,sha256-rsa,sha256-dsa,sha224-ecdsa,sha224-rsa,sha224-dsa,sha1-ecdsa,sha1-rsa,sha1-dsa.

In order to not restrict the server's certificate signature algorithm, specify an empty string as the value for this setting, which will cause the signature_algorithms TLS 1.2 extension to not be sent.

TLS12SupportedGroups:   The supported groups for ECC.

This setting specifies a comma separated list of named groups used in TLS 1.2 for ECC.

The default value is ecdhe_secp256r1,ecdhe_secp384r1,ecdhe_secp521r1.

When using TLS 1.2 and UseInternalSecurityAPI is set to True, the values refer to the supported groups for ECC. The following values are supported:

  • "ecdhe_secp256r1" (default)
  • "ecdhe_secp384r1" (default)
  • "ecdhe_secp521r1" (default)

TLS13KeyShareGroups:   The groups for which to pregenerate key shares.

This setting specifies a comma separated list of named groups used in TLS 1.3 for key exchange. The groups specified here will have key share data pregenerated locally before establishing a connection. This can prevent an additional round trip during the handshake if the group is supported by the server.

The default value is set to balance common supported groups and the computational resources required to generate key shares. As a result only some groups are included by default in this setting.

Note: All supported groups can always be used during the handshake even if not listed here, but if a group is used which is not present in this list it will incur an additional round trip and time to generate the key share for that group.

In most cases this setting does not need to be modified. This should only be modified if there is a specific reason to do so.

The default value is ecdhe_x25519,ecdhe_secp256r1,ecdhe_secp384r1,ffdhe_2048,ffdhe_3072

The values are ordered from most preferred to least preferred. The following values are supported:

  • "ecdhe_x25519" (default)
  • "ecdhe_x448"
  • "ecdhe_secp256r1" (default)
  • "ecdhe_secp384r1" (default)
  • "ecdhe_secp521r1"
  • "ffdhe_2048" (default)
  • "ffdhe_3072" (default)
  • "ffdhe_4096"
  • "ffdhe_6144"
  • "ffdhe_8192"

TLS13SignatureAlgorithms:   The allowed certificate signature algorithms.

This setting holds a comma separated list of allowed signature algorithms. Possible values are:

  • "ed25519" (default)
  • "ed448" (default)
  • "ecdsa_secp256r1_sha256" (default)
  • "ecdsa_secp384r1_sha384" (default)
  • "ecdsa_secp521r1_sha512" (default)
  • "rsa_pkcs1_sha256" (default)
  • "rsa_pkcs1_sha384" (default)
  • "rsa_pkcs1_sha512" (default)
  • "rsa_pss_sha256" (default)
  • "rsa_pss_sha384" (default)
  • "rsa_pss_sha512" (default)
The default value is rsa_pss_sha256,rsa_pss_sha384,rsa_pss_sha512,rsa_pkcs1_sha256,rsa_pkcs1_sha384,rsa_pkcs1_sha512,ecdsa_secp256r1_sha256,ecdsa_secp384r1_sha384,ecdsa_secp521r1_sha512,ed25519,ed448. This setting is only applicable when SSLEnabledProtocols includes TLS 1.3.
TLS13SupportedGroups:   The supported groups for (EC)DHE key exchange.

This setting specifies a comma separated list of named groups used in TLS 1.3 for key exchange. This setting should only be modified if there is a specific reason to do so.

The default value is ecdhe_x25519,ecdhe_x448,ecdhe_secp256r1,ecdhe_secp384r1,ecdhe_secp521r1,ffdhe_2048,ffdhe_3072,ffdhe_4096,ffdhe_6144,ffdhe_8192

The values are ordered from most preferred to least preferred. The following values are supported:

  • "ecdhe_x25519" (default)
  • "ecdhe_x448" (default)
  • "ecdhe_secp256r1" (default)
  • "ecdhe_secp384r1" (default)
  • "ecdhe_secp521r1" (default)
  • "ffdhe_2048" (default)
  • "ffdhe_3072" (default)
  • "ffdhe_4096" (default)
  • "ffdhe_6144" (default)
  • "ffdhe_8192" (default)

Copyright (c) 2022 /n software inc. - All rights reserved.
/n software 3-D Secure V2 C++ Edition - Version 2.2 [Build 8318]