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

Possible values are:

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

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.

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

Possible values are:

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.

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.

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.

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

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.

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

Possible values are:

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.

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.

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.

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.

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.

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.

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.

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:

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:

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.

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

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

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.

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:

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

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.

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:

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

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.

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.

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:

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.

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.

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:

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

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.

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

Indicates the merchandise delivery timeframe.

Possible values are:

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.

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.

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.

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.

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

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.

Indicates where the payment token was detokenized.

Valid values are:

This is required to be set if EMVPaymentTokenIndicator is true.

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.

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

Text describing the problem identified in the error message.

Additional detail regarding the problem identified in the error message.

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.

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.

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.

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.

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.

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

This setting specifies the JSON formatted extension data.

This setting specifies a unique identifier for the extension.

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

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.

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.

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

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

This is set to 1 (Info) by default.

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.

This field identifies the type of the message being transmitted.

Possible values include:

This setting is read-only.

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:

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.

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.

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

Possible values are:

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.

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.

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.

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

Possible values are:

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.

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.

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:

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.

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.

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.

Indicates whether the cardholder is reordering previously purchased merchandise.

Possible values are:

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.

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.

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:

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.

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:

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

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.

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

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.

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.

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

Possible values are:

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.

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:

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.

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

Possible values are:

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.

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.

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

Possible values are:

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.

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:

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

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:

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:

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.

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.

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

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.

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

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.

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.

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.

Provides the name of the current element.

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

Provides the parent of the current element.

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

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:

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:

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

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.

Provides the inner text of the current element.

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

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.

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.

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.

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

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.

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.

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

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

This setting specifies whether the class will check the Certificate Revocation List specified by the server certificate. If set to true the class will first obtain the list of CRL URLs from the server certificate's CRL distribution points extension. The class will then make HTTP requests to each CRL endpoint to check the validity of the server's certificate. If the certificate has been revoked or any other issues are found during validation the class fails with an error.

When set to false (default) the CRL check will not be performed by the class.

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.

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");

• 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

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");

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

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:

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.

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.

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.

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]");

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]");

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]");

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]");

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]");

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]");

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 .

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

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

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

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");

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.

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)

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"

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)

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)