OpenEdge.Net.ServerConnection.TlsClientAuthenticationError

Namespace:

OpenEdge.Net.ServerConnection

Type: Class

TlsClientAuthenticationError

Parent Classes:

Progress.Lang.AppError

OpenEdge.Core.System.ApplicationError

OpenEdge.Net.ServerConnection.TlsClientAuthenticationError

Inherits:

OpenEdge.Core.System.ApplicationError

	Copyright (c) 2021, 2023, 2024 by Progress Software Corporation. All rights reserved.
File:	TlsClientAuthenticationError
Purpose:	Wrapper for P.L.SysError #9318 (SSL Failure)
Description:	Created in OCTA-34843, updated in OCTA-56721
Author(s):	pjudge/dugrau
Created:	2021-03-17
	This class is used to encapsulate any errors which may have been raised by
	an SSL failure, as indicated as a SysError #9318. While this was originally
	created for the TLS Client Authentication feature, the 9318 error is more
	of a catch-all to any TLS/SSL error which may be encountered by the ABL
	Sockets layer. These may be errors related to failed DNS, SSL handshakes,
	incorrect certificates or passphrases, unsupported TLS groups, or any other
	error condition related to HTTPS communications.
	The format of this error object is intended to provide an easier means of
	accessing the inner error noted by an SSL failure, and if necessary to change
	the message to a more user-friendly condition. As of TLS v1.3 multiple error
	numbers may refer to the same underlying condition so those are treated as
	a group when translated. Another reason for translation is to avoid returning
	an error message which may be directly used by a malicious user to gain
	knowledge of application security--providing generic messages for certain
	conditions will obfuscate the result but still allow a developer to trace
	back to the originating condition in the application logic.
	By default, this object will return 4 values within its error messages:
	1) The inner error code extracted from the 9318 SSL failure message
	2) The hostname from the request URI
	3) The port number from the request URI
	4) An error message either translated from the inner error code,
	or a generic message to indicate a TLS error was encountered
	Additionally, this error object will provide that same data via the
	following object properties, listed in the same order as their message
	counterparts above:
	TlsErrorNum: The inner SSL error code
	Host: Request hostname
	Port: Request port number
	TlsError: Translated or generic error message
	An ABL developer may then make use of the error messages or object properties
	as part of their business logic to assist either the user or a system admin
	to understand the reason for failure of a request.
	In cases where the new error messages are not desired, it is possible to
	revert to using the original SysError messages while still retaining the
	ability to utilize this new object's properties and error translations.
	Usage: Set a static property within the application code, either in a
	startup procedure or close to the execution of a request to the
	Http Client. This will force the order and contents of messages
	to remain consistent to the original object thrown.
	Example:
	using OpenEdge.Net.ServerConnection.TlsClientAuthenticationError.
	TlsClientAuthenticationError:ReturnOriginalMessages = true.
	Purpose:
	To allow this error object throw the original, expected error messages, set this property true.
	Example: OpenEdge.Net.ServerConnection.TlsClientAuthenticationError:ReturnOriginalMessages = true.

	Options	Name	Purpose
		LONGCHAR GetErrorMessage ()	/** Returns an error message constructed from the extracted properties from the 9318 error. @return longchar Error message. */
		CHARACTER GetShortMessage ()	/** Returns an error message constructed from the extracted properties from the 9318 error. @return character Error message. */
		ParseErrorNum (character)

	Options	Name	Purpose
		TlsClientAuthenticationError ()	/* Static constructor */
		TlsClientAuthenticationError (URI, Error)	/* Constructor @param URI The host that raised the error condition @param PLError The error raised. SysError 9318 is parsed for the error code */
		TlsClientAuthenticationError (URI, Stop)	/* Constructor @param URI The host that raised the stop condition @param PLStop The stop condition raised */

	Options	Name	Purpose
		CHARACTER Host
		INTEGER Port
		LOGICAL ReturnOriginalMessages
		CHARACTER TlsError
		INTEGER TlsErrorNum

LONGCHAR GetErrorMessage ()

CHARACTER GetShortMessage ()

ParseErrorNum (character)

STATIC TlsClientAuthenticationError ()

TlsClientAuthenticationError (URI, Error)

TlsClientAuthenticationError (URI, Stop)

CHARACTER Host

INTEGER Port

LOGICAL ReturnOriginalMessages

CHARACTER TlsError

INTEGER TlsErrorNum