SocketTools 9.0 has been released and includes support for Windows 10 and Windows Server 2016, along with new and improved security features that will enable your applications to be PCI DSS 3.1 compliant. This release also includes the FileTransfer and InternetMail components as part of each edition. There’s also been general improvements throughout all of the networking components, while continuing backwards compatibility with previous versions and older Windows platforms.

SocketTools includes both 32-bit and 64-bit components, along with support for IPv6, the next-generation Internet protocol. All three SocketTools editions include support for both standard and secure connections using TLS, SSL and SSH. The components can be installed side-by-side with previous versions, and upgrading your applications to use the new version will typically require very few changes to existing projects.

If your SocketTools Subscription is active, you can download the current version of SocketTools using the same subscription link that was provided to you when you ordered the software. However, you will not be able to use your current version 8.0 serial number to install the new version. Please contact the sales office to obtain your new serial number for version 9.0.

The post SocketTools 9.0 Released appeared first on SocketTools.

A new update for SocketTools is available for download. SocketTools 9.1 has been released and includes updated support for the current Windows server and desktop platforms, along with Visual Studio 2017. Version 9.1.9100.2138 was released on March 24th, 2017. This is a complete product release that incorporates fixes from the previous general release, as well as all subsequent hotfixes. Developers who are currently using SocketTools 9.0 can upgrade to the current version for free.

This update includes fixes and improvements to security and performance, as well as internal changes for compatibility with the latest Windows updates. While SocketTools will continue to support older Windows platforms such as Windows XP and Windows Vista for backwards compatibility, it is important to note that some critical security features are only available on newer versions of Windows. For example, support for stricter security using TLS 1.2 and AES-256 is only available on Windows 7 and later versions.

You can download the update using the same link that was provided to you when you ordered the software, or you can download the current version from the website. Developers who are using SocketTools 8.0 or earlier versions are eligible for an upgrade at a discounted price.

The post SocketTools 9.1 Released appeared first on SocketTools.

The SocketTools 9.1 Library Edition has function prototypes and constants available for the Clarion programming language. The minimum supported version of Clarion is 8.0 and we recommend that you use both the current release of SocketTools and Clarion in your projects.

You can download the current Clarion support files at:

http://sockettools.com/download/cstools91_clarion.zip

You should extract these files into the accessory folder under the root installation folder for Clarion, and then you’ll need to register the cstools.tpl template in the Clarion registry. The cstools9.inc file defines the constants and structures, and the cstools9.clw file defines the function prototypes for each of the libraries.

We would like to thank Robert Paresi of InnQuest Software for his assistance and contributing the example code for Clarion.

The post SocketTools Clarion Support Files appeared first on SocketTools.

A new update for SocketTools is available for download. SocketTools 9.2 has been released and includes security and performance improvements, corrections and updated documentation. Version 9.2.9200.2450 was released on August 2nd, 2017. This is a complete product release that incorporates fixes from the previous general release, as well as all subsequent hotfixes. Developers who are currently using SocketTools 9.0 or later versions can upgrade to the current version for free.

This update includes general fixes, as well as compatibility updates for the latest Windows updates. While SocketTools will continue to support older Windows platforms such as Windows XP and Windows Vista for backwards compatibility, it is important to note that some critical security features are only available on newer versions of Windows. For example, support for TLS Session Resumption is only available on Windows 8 and later versions. Please review the release notes and product documentation for more information.

You can download the update using the same link that was provided to you when you ordered the software, or you can download the current version from the website. Developers who are using SocketTools 8.0 or earlier versions are eligible for an upgrade at a discounted price.

When installing SocketTools on a Windows 10 system, not all of the shortcuts are displayed in the Start menu.

More Information

This can occur when there is more than one edition of SocketTools installed on the same system. If Windows 10 finds multiple shortcuts that point to the same information (for example, a shortcut that is a link to one of the areas on our website) then it will only show one instance of that shortcut, under the first SocketTools edition folder that is listed in the menu on the left-hand side.

Where this is most problematic is when a shortcut to the License Manager utility is not shown for one of the SocketTools editions because all editions share the same version of the utility. We have changed the installer for the current version of SocketTools to install each edition for the current user, with unique links to the License Manager.

If you’re using an older version of SocketTools and can’t find a shortcut to the License Manager utility in the Start menu, look for it in one of the following folders:

C:\Program Files\Common Files\Catalyst Shared\Licensing\cdlicmgr.exe
C:\Program Files (x86)\Common Files\Catalyst Shared\Licensing\cdlicmgr.exe

This is a digitally signed executable which can be used to generate your runtime license key by selecting License | Runtime Key from the menu. If you have any questions about how to use the License Manager, generate your license key or redistribute your application, please contact technical support and we can assist you.

When building a SocketTools project using Visual C++ 6.0 on Windows XP or later, make sure that you have installed Visual Studio 6.0 Service Pack 6 (SP6) and the Windows Platform SDK February 2003 Edition.

More Information

SocketTools can be used Visual C++ 6.0 on Windows XP, however there are several requirements. The Windows XP system must have been updated with Service Pack 3 (SP3) and current security updates. After installing Visual Studio 6.0 or Visual C++ 6.0, you also need to update it with Service Pack 6 (SP6). This was made available as part of MSDN and can be downloaded from Microsoft Download Center.

When you attempt to compile one of the SocketTools examples (or your own code) you may get a warning that the WINVER preprocessor macro has been defined as 0x0500 or greater. This means that you do not have the correct Windows header files and import libraries installed. You need to obtain the Platform SDK – February 2003 Edition and install the Core SDK files.

There are also other components to the Platform SDK which you may wish to install, such as the database APIs and debugging tools. After you have installed the Platform SDK, integrate it with Visual C++ 6.0 by selecting All Programs > Microsoft Platform SDK February 2003 > Visual Studio Registration > Register PSDK Directories with Visual Studio.

Downloads

Service Pack 6 for Visual Basic 6.0, Visual C++ 6.0
Microsoft Platform SDK February 2003

SocketTools uses the Windows CryptoAPI and Schannel security provider to provide support for Transport Security Layer (TLS), which is used with secure connections. The latest version of TLS that is supported on the Windows XP platform is TLS 1.0. However, an update that was released for Windows Embedded POSReady 2009 can be used to provide support for TLS 1.2.

More Information

Microsoft has released an update for Windows Embedded POSReady 2009 that provides support for TLS 1.2 and AES-256. This platform is a specialized version of Windows XP designed for point-of-service systems. If you are already developing for this platform, you can download update KB4019276 from Microsoft’s Update Catalog.

If you are using Windows XP and your application requires support for TLS 1.2, it is possible to apply this update. You must be running Windows XP SP3 and you must make a change to the registry. It is strongly recommended that you upgrade to Windows 10 to ensure that you have the latest security updates and the strongest cipher suites available. However, if that is not a possibility, then you can follow these steps to install the update.

If you decide to make these changes, you acknowledge that you are doing this entirely at your own risk. Make sure that you have a full backup of the system.

1. Verify that you are running Windows XP SP3 with all of the available updates installed. If you have automatic updates enabled, it is recommended that you disable them at this time. After this change, Windows Update will now see your Windows XP system as Windows Embedded POSReady 2009 and there may be updates that are released for that platform that do no apply to your system. You will need to manually check and verify all updates after this change has been made.
2. Open the Registry Editor and create HKEY_LOCAL_MACHINE\SYSTEM\WPA\POSReady then select that key and define a DWORD value named Installed as 1. Once you have made this registry change, you will not be able to delete this key from the registry, even as an Administrator. This is effectively a permanent change to the system. To make this change easier, create a registry script by copying the following to a text file, name it “PosReady.reg” and then execute it by double-clicking on the file in Windows Explorer:
   

   Windows Registry Editor Version 5.00
   
   [HKEY_LOCAL_MACHINE\SYSTEM\WPA\POSReady]
   "Installed"=dword:00000001

3. Download the KB4019276 update for Windows XP Embedded from the Microsoft Update Catalog. [Direct Link (English)] and install the update. You can verify that the update has installed correctly by using Windows Explorer to display the properties of the Schannel.dll and Rsaenh.dll files in \Windows\System32. Both files should be version 5.1.2600.7346 or later.
4. Reboot the system. Remember to manually check all subsequent updates made available through Windows Update and you should not automatically install updates for the POSReady 2009 platform. Microsoft has stated that these updates are not tested on Windows XP.

After this update has been installed, the system will support TLS 1.1 and TLS 1.2, as well as AES-256 and other stronger cipher suites. Note that Internet Explorer 8 does not provide support for TLS 1.2 even after this update has been installed. If you need TLS 1.2 support in a browser, you will need to download an alternate browser such as Chrome or Firefox.

External Links

Microsoft Update KB4019276
Microsoft Update Catalog

A new update for SocketTools is available for download. SocketTools 9.3 has been released and includes improved support for Unicode and Internationalized Domain Names (IDNs), along with security and performance improvements, corrections and updated documentation. Version 9.3.9300.2758 was released on February 7th, 2018.

This is a complete product release that incorporates fixes from the previous general release, as well as all subsequent hotfixes. Developers who are currently using SocketTools 9.0 or later versions can upgrade to the current version for free.

This update includes general fixes, as well as compatibility with the latest updates to Windows 10 and Visual Studio 2017. While SocketTools will continue to support older Windows platforms such as Windows XP and Windows Vista for backwards compatibility, it is important to note that some critical security features are only available on newer versions of Windows.

This version includes support for TLS 1.2 connections on Windows XP, Windows POSReady 2009 and Windows Server 2008, however it may require the installation of specific Windows updates. Refer to Support for TLS 1.2 on Windows XP for more information.

You can download the update using the same link that was provided to you when you ordered the software, or you can download the current version from the website. Developers who are using SocketTools 8.0 or earlier versions are eligible for an upgrade at a discounted price.

When attempting to manually register a control from the command line using the RegSvr32.exe utility, an error is displayed stating that the ActiveX control was loaded but the call to DllRegisterServer failed with error code 0x80040200.

More Information

This error can occur on Windows Vista or Windows Server 2008 and later platforms with UAC enabled. Because registration requires access to a restricted area of the registry, it must be done with elevated privileges using an administrative command prompt. This can be done by right-clicking on the Command Prompt icon and selecting “Run as Administrator” or, on Widows 8.1 or Windows 10, right-clicking on the Windows icon in the taskbar and selecting “Command Prompt (Admin)”.

If you are using a 64-bit version of Windows, you should also make sure that you’re registering the correct version of the control. On 32-bit versions of Windows, the SocketTools ActiveX controls are installed in C:\Windows\System32. On 64-bit Windows, the 32-bit ActiveX controls are installed in C:\Windows\Syswow64 and the 64-bit ActiveX controls are installed in C:\Windows\System32. To register a 32-bit control on a 64-bit Windows system, the command should look like this:

%windir%\syswow64\regsvr32 %windir%\syswow64\control.ocx

Where control is the file name of the ActiveX control you want to register. If you are manually copying a control from one system to another, it should also be noted that registering a control is different from licensing. To deploy an application that uses a SocketTools ActiveX control, it must be compiled on the system with a SocketTools development license. A registered control will still generate a runtime licensing error if the application is not properly licensed for redistribution.

SocketTools includes support for Unicode in several different ways, depending on the edition and development tools used. This article discusses how Unicode support is implemented for each edition.

Character Encoding and Unicode

Legacy applications for earlier versions of Windows typically used code pages and multi-byte character sets (MBCS), where characters can be represented by one or two bytes. These character sets were predominantly used in consumer versions of Windows prior to Windows 2000. In the Win32 API, those functions that accept string parameters were given an “A” (ANSI) suffix to indicate they expected 8-bit characters using the current code page.

The current standard is to use Unicode, which supports over 135,000 characters and more than 130 languages. In Windows, Unicode is natively implemented using UTF-16 encoding, which means that each character is represented by two (or sometimes four) bytes. Win32 functions that accept UTF-16 encoded strings (also called “wide strings”) were given a “W” suffix to indicate they expected 16-bit characters. The SocketTools API uses the same conventions, with “A” and “W” versions of all functions that accept string parameters.

However, UTF-16 encoding presents a problem for most Internet protocols because they were designed with the presumption that a single character could be represented by a single byte. At a lower level, TCP also handles all data as “octets” which are 8-bit (byte) values. To address this, there is another Unicode encoding called UTF-8 which represents Unicode characters as a sequence of one to four bytes. Because the first 127 characters that make up the ASCII character set are the same in UTF-8, an ASCII string is by definition also a UTF-8 string.

Today, most services recognize and accept UTF-8 as a standard character encoding. Internet protocols have been changed or expanded to either explicitly opt-in to use UTF-8 encoding, or implicitly expect it as the default. However, there one notable exception with the Domain Name Service (DNS). It only accepts a limited subset of ASCII characters in domain name labels. Names that use Unicode characters are called Internationalized Domain Names (IDNs), and to make them compatible with the DNS system, they are converted to ASCII using an alternative encoding called Punycode.

International Domain Names

Domain names that contain Unicode characters must be encoded before they are resolved to an IP address. This is accomplished using an encoding called Punycode, which converts a Unicode domain name into a format that is compatible with the DNS system. For example, the domain name δοκιμή.sockettools.com is an IDN. When this is passed to SocketTools, it automatically encodes it using Punycode, resulting in the domain name xn--jxalpdlp.sockettools.com which is then resolved to an IP address.

Earlier versions of SocketTools required that the developer explicitly perform this encoding if necessary. With the current version, this is done automatically with any host name (or the host name portion of a URL) that contains Unicode characters. Whenever you call a function or method in SocketTools that requires a host name, that value will go through a normalization process that removes any leading or trailing whitespace, converts it to lower case and performs any necessary encoding. If the host name is specified using UTF-16 or UTF-8 encoding, it’s also checked to ensure that the encoding is valid and invisible code points are removed (this process is referred to as Nameprep).

SocketTools .NET Edition

The SocketTools .NET classes use the managed System.String type, which is a UTF-16 encoded string. All methods that accept a string parameter will automatically encode it as UTF-8 before sending it to the remote host. Text data that is received will be converted from UTF-8 to a UTF-16 encoded string prior to be returned to the caller. This conversion only occurs with string types, not binary data exchanged using byte arrays. The versions of methods that use byte arrays or MemoryStream objects will exchange data as-is without any encoding.

This conversion can have implications for some methods, such as ReadLine and WriteLine which will convert strings between UTF-16 and UTF-8. For example, if you use WriteLine to send a text string to a service, that text will be automatically converted to UTF-8 and then written to the socket. The service that is reading the text that you’re sending must be able to recognize and process UTF-8 encoding correctly. It may choose to retain the UTF-8 encoding, or it may convert it back to UTF-16 prior to storing or displaying the text.

SocketTools Library Edition

The SocketTools libraries provide an API that includes both Unicode and ANSI versions of functions. If a function accepts a string parameter, or a structure which contains strings, the Unicode version of the function will have a “W” suffix and the ANSI (MBCS) version will have an “A” suffix. For example, the function FtpGetFile actually has two implementations, FtpGetFileW and FtpGetFileA. With C/C++, the default version of the function used is determined by the project configuration, which defines the UNICODE macro. If your project is configured to use Unicode, then a call to FtpGetFile is changed to actually call FtpGetFileW; otherwise, it will call FtpGetFileA.

When the Unicode version of a function is called, the UTF-16 (wide) string parameters are converted to use UTF-8 encoding internally. This can have implications for some functions, such as InetReadLineW and InetWriteLineW which will convert strings between UTF-16 and UTF-8. For example, if you use InetWriteLineW to send Unicode text to a service, that text will be automatically converted to UTF-8 and then written to the socket. The service that is reading the text that you’re sending must be able to recognize and process UTF-8 encoding correctly. It may choose to retain the UTF-8 encoding, or it may convert it back to UTF-16 prior to storing or displaying the text.

Although it is recommended that you build your projects using Unicode, it is possible to use Unicode names with legacy projects built using multi-byte character sets (MBCS). The ANSI versions of most SocketTools functions (those with the “A” suffix) will recognize UTF-8 encoded strings. This means it is possible for an MBCS application to use the WideCharToMultiByte function to convert a UTF-16 string to UTF-8 and then use that value. However, keep in mind that if you use the ANSI version of a function, text returned to you may also be UTF-8 encoded. The MultiByteToWideChar function can be used to convert it back to a UTF-16 encoded string if required.

It is important to note that this conversion only applies to C/C++ style null-terminated strings (an array of characters terminated with a null character). In the SocketTools API these are your typical LPTSTR or LPCTSTR types. Those functions that accept byte values or pointers to byte arrays (LPBYTE) are handled as-is and are not subject to UTF-8 encoding.

SocketTools ActiveX Edition

The SocketTools ActiveX controls use the BSTR string type, which is a special UTF-16 encoded string typically used with COM and ActiveX. Property values use BSTRs and all methods accept VARIANTARG parameters (which can represent any data type). If the method expects a string value, it will attempt to convert the VARIANTARG parameter to a BSTR, which will then be converted to a UTF-8 encoded string. If text is returned back to the caller, it will be converted to a UTF-16 encoded string and returned as a BSTR value.

When using Visual Basic, the conversion between UTF-16 and UTF-8 encoding only occurs with String types, and not byte arrays. If your code calls a method and passes in a byte array, then the data will be sent or received as-is without any encoding. Generally speaking, this entire conversion process will be transparent and handled automatically.

Although strings in Visual Basic are internally managed as UTF-16 strings, the default common controls used in Visual Basic 6.0 do not support Unicode. Those controls, such as buttons, text boxes and labels, will automatically convert the Unicode text to ANSI using the current code page. This means that text in the end-user’s native language (depending on system settings) will display correctly, although text in other languages using different character sets may not. Also note that the VB6 IDE is not Unicode aware and may display corrupted string values or invalid characters (e.g.: tooltip values when debugging).

For Unicode support in Visual Basic 6.0, it’s recommended that you use third-party controls. An alternative that some developers have used is the Microsoft Forms 2.0 Object Library (FM20.DLL) that is part of Microsoft Office. It includes a collection of controls that support Unicode, however they are not redistributable and Microsoft has stated that their use with VB6 is unsupported.

The SocketTools server components can use self-signed certificates to enable secure connections without requiring that you purchase and install a certificate from a Certificate Authority. These certificates are installed on the local host, and are typically used for testing purposes. However, when attempting to connect to the server using Chrome or Firefox, an error is returning specifying that the certificate is invalid.

More Information

After following the instructions to create a self-signed certificate, attempting to use that certificate with the SocketTools HttpServer component results in an error when using Chrome or Firefox. Chrome will report ERR_CERT_COMMON_NAME_INVALID and Firefox will report SEC_ERR_UNKNOWN_ISSUER. In the case of Chrome, this error occurs because they have deprecated the use of the common name field and the test certificate does not have a subjectAlternativeName field.

The workaround for this is to create a registry entry that tells Chrome it should accept locally-installed certificates with a matching host name. Copy the following registry script text to a file named ChromeCommonNames.reg and then double-click on the file in WIndows Explorer to add it to the registry:

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome]
"EnableCommonNameFallbackForLocalAnchors"=dword:00000001

With Firefox, the solution is to import the local test certificate. Open Firefox, select Options and scroll down to the bottom where you should see a View Certificates button. Click this, and it will open the Firefox Certificate Manager. Select the Servers tab, and then click Add Exception. Make sure you have your server running, and provide the URL to your server, such as https://localhost/ and click Get Certificate. Check the “Permanently store this exception” option and confirm the exception. This will add your test certificate to the list of trusted certificates and Firefox will permit the connection.

See Also

Creating A TLS Server Certificate

SocketTools includes several server components, including a multi-threaded HTTP server. Initial testing is often done with the client and server connecting to one another on the local system, rather than over the Internet. When using the Chrome, Firefox or Internet Explorer browsers, the connection to the local server is successful. However, connection attempts fail when using the Microsoft Edge browser on Windows 10.

More Information

The SocketTools server components can be configured to listen for connections that can only be made on the local system. This is done by having the server listen for connections using the localhost address (also known as the loopback address). For IPv4 connections, this is 127.0.0.1 and for IPv6 it is ::1

There are several advantages to this approach when it comes to initial testing of a server application. By using the localhost address, it bypasses most firewall restrictions, since firewalls are typically configured to permit connections between local clients and servers. It also allows the server to be tested in an environment where it’s not necessary to have a static external IP address or be concerned with NAT router configurations.

For the HTTP server component, the application only needs to configure the component to listen on the “localhost” address and browser can be used to connect to the server at http://localhost/ or https://localhost/ depending on whether security is enabled. This works for most browsers, however, the Microsoft Edge browser may fail to connect to the server. This is because Edge is a Universal Windows Platform (UWP) app that normally executes in a network isolation mode which blocks localhost connections.

To enable Edge to connect to your server listening on the local system, first close any open instances of Edge that you have running. Then open an Administrative command prompt and enter the following command:

CheckNetIsolation LoopbackExempt -a -n=Microsoft.MicrosoftEdge_8wekyb3d8bbwe

You should get an “OK” message in response to the command. Next, open Edge and enter about:flags in the address bar. Make sure that the “Allow localhost loopback” option is checked, and if not, enable it. Now you should be able to connect to your local server using the Edge browser.

See Also

Creating A TLS Server Certificate
Connections Fail Using Test Certificate

A new update for SocketTools is available for download. Version 9.3.9310.2784 was released on March 21st, 2018. This is a complete product release that incorporates fixes from the previous general release, as well as all subsequent updates. Refer to the release notes for information about all of the changes in this update.

A security related change to SocketTools has deprecated the use of MD5 and RC4 when establishing secure connections. These algorithms are not considered cryptographically secure, and will not be used by default. A new option has been added to permit the components to fallback to using older, less secure cipher suites for backwards compatibility with older servers. However, it is only recommended that you enable this option if absolutely necessary.

You can download the updated version of SocketTools using the same link that was provided to you when you ordered the software, or you can download the current version from the website. Developers who are using earlier versions of SocketTools are eligible for an upgrade at a discounted price.

There are a few important development considerations when exchanging binary data over a network connection. For most applications, strings should never be used to send or receive binary data; instead, applications should use byte arrays to exchange binary data.

SocketTools .NET Edition

Many of the .NET classes include overloaded versions of Read and Write methods, which are used receive and send data. All implementations provide support for the native string type and byte arrays, and some also include support for MemoryStream objects. If your application only sends ASCII text, then it is safe to use strings. However, if the data contains binary data or uses extended ASCII characters, then using a string may have unexpected results. This is because all strings are internally represented as Unicode, and any strings that are sent using the Write method will be sent as UTF-8 encoded Unicode. Likewise, any data read into a string will be treated as Unicode and converted from UTF-8 encoding to UTF-16 encoding. This may result in corruption of data that is sent or received using a string, but is not actually Unicode text.

It is recommended that you always use byte arrays or MemoryStream objects to exchange binary data, or data that uses extended ASCII characters which are not Unicode strings. For example, a string that contains extended ASCII (ANSI) characters used by the local code page should be converted to a byte array before being sent using the Write method. Typically this would only affect legacy applications that don’t support Unicode or the use UTF-8 encoded text.

Some classes include ReadLine and WriteLine methods that are used to read and write lines of text, up to a terminating newline character. These methods should never be used with binary data under any circumstances.

SocketTools Library Edition

Many of the SocketTools libraries provide lower level functions that enable you to read or write on the socket used to establish the connection. The C/C++ prototypes for these functions typically either use LPVOID or LPBYTE for the pointer to the buffer that contains the data to be sent or received. In this case, the function will send or receive the data as-is for the number of bytes specified. However, if the function expects a string type (e.g.: the InetReadLine or InetWriteLine functions) then that data will be handled as text. This means if the ANSI version of the function is called, it will be sent as text using the current code page, up to a terminating null character. If the Unicode version of the function is called, the text will be sent as UTF-8 encoded Unicode, up to the terminating null character.

You should never use functions that expect a pointer to a string when sending or receiving binary data. Null bytes in the data will be interpreted as the end of the string. If the project is compiled to use Unicode, they will automatically encode any written data as UTF-8 and attempt to convert any data received back to using UTF-16 encoding. In both cases, this can result in corruption of the data.

SocketTools ActiveX Edition

The SocketTools ActiveX controls have Read and Write methods which will accept both strings (BSTRs) and byte arrays as arguments. If your application only sends ASCII text, then it is safe to use strings. However, if the data contains binary data or uses extended ASCII characters, then using a string may have unexpected results. This is because all strings are internally represented as Unicode, and any strings that are sent using the Write method will be sent as UTF-8 encoded Unicode. Likewise, any data read into a string will be treated as Unicode and converted from UTF-8 encoding to UTF-16 encoding. This may result in corruption of data that is sent or received using a string, but is not actually Unicode text.

It is recommended that you always use byte arrays to exchange binary data, or data that uses extended ASCII characters which are not Unicode strings. For example, a string that contains extended ASCII (ANSI) characters used by the local code page should be converted to a byte array before being sent using the Write method. Typically this would only affect legacy applications that don’t support Unicode or the use UTF-8 encoded text.

Some controls include ReadLine and WriteLine methods that are used to read and write lines of text, up to a terminating newline character. These methods should never be used with binary data under any circumstances.

Note that although Visual Basic 6.0 uses Unicode internally, the common controls do not support Unicode and will represent text using the current code page. If you are reading input entered using a control like a TextBox, and international characters are used, then you may get unexpected results. A solution is to either use controls which natively support Unicode, or convert the ANSI text back to Unicode. The StrConv function can be used to convert to and from Unicode, and the vbFromUnicode option can be used to convert a string to a byte array which can then be passed to the Write method.

See Also

Unicode Support in SocketTools
Structured Data Over Stream Sockets

A new update for SocketTools is available for download. Version 9.3.9320.2834 was released on May 14th, 2018. This is a complete product release that incorporates fixes from the previous general release, as well as all subsequent updates. Refer to the release notes for information about all of the changes in this update.

You can download the updated version of SocketTools using the same link that was provided to you when you ordered the software, or you can download the current version from the website. Developers who are using earlier versions of SocketTools are eligible for an upgrade at a discounted price.

An error is returned when attempting to create a secure SSL or TLS connection indicating that the SocketTools component cannot establish a security context. This error can occur for several reasons, depending on the server configuration and the version of Windows the application is running on.

More Information

When the application attempts to connect to a server, the connection fails with error code 12102 (0x80042F46) which means that it cannot establish a security context. This is a general error that can occur when SocketTools is unable to successfully complete the initial handshake with the server in which certificate information is exchanged and the encryption ciphers are selected for the session. This error may occur under the following circumstances:

1. The server is not accepting new connections, or it does not support secure connections on the port number that was specified. If the server is not accepting new client connections, it may accept the TCP connection and then immediately close it, or return an error message and close the connection. If the server is not configured to accept secure connections, it will not know how to respond to the initial TLS handshake and this will cause the connection to fail.

2. The server is not configured for implicit TLS connections on the specified port number. If the server was configured to use explicit TLS, then the initial connection is made with the client connecting normally using a standard (non-secure) connection. To initiate a secure session, the client must send a specific command to the server that tells the server it wants a secure connection and then follows that with the TLS handshake. SocketTools supports both implicit and explicit TLS sessions, and by default will select the correct option based on the port number used. However, if the server has a non-standard configuration or is using an alternate port number, it may be necessary to explicitly specify the correct security option when calling the Connect method or function.

3. The server does not understand how to handle requests for TLS version 1.1 or 1.2. By default, SocketTools will always attempt to use the latest version of TLS and the strongest encryption ciphers available to both the client and server. When SocketTools advertises that it would like to use TLS 1.2, some older server software may not correctly negotiate for an earlier version of TLS and instead reject the connection or fail unexpectedly. This is a flaw in the server software, not SocketTools, and it is recommended that you upgrade the server if possible. An alternative is to set your application compatibility to Windows XP SP3 and see if the connection succeeds. This tells SocketTools to not use the current versions of TLS and it will only attempt to use older, less secure options. SocketTools 9.0 and later will only request TLS 1.2 by default. TLS 1.0 will only be used if the application is running on an older, unsupported version of Windows.

4. The client application is running on Windows XP or Windows Server 2003 and is connecting to a server that uses certificates that were signed using SHA-256, or has been configured to not permit connections using SSL 3.0 or the RC4-SHA cipher suite. Servers may be configured to require connections using the current version of TLS and reject less secure cipher suites. Because Windows XP and Windows Server 2003 do not support TLS 1.2 or AES encryption, the server may refuse the connection attempt. If a secure connection to the same server is successful when the application runs on Windows 7 or later versions of Windows, this is likely the cause of the failure. Microsoft does offer an update that may resolve the issue for Windows Server 2003, but no hotfix is available for Windows XP.

See Also

Support for TLS 1.2 on Windows XP
Microsoft Update 948963 for Windows Server 2003.

Support for secure credit card transactions using TLS 1.0 is coming to an end after June 30, 2018. The new standards defined by the PCI Security Standard Council requires all payment processors and third-party providers to explicitly disable support for TLS 1.0 and switch to exclusively using TLS 1.1 or later versions, preferably using TLS 1.2.

More Information

If you use SocketTools to send or receive credit card payment data, upgrade to the current version before June 30, 2018. The current version of SocketTools includes several important security related updates that will ensure that your users will be able to continue to connect to these service providers.

Previous versions of SocketTools would negotiate for a secure connection using any version of TLS that was available. SocketTools 6.0 and earlier versions would also attempt to use SSL 3.0. Because SSL and the earlier versions of TLS are no longer secure, you cannot use them to connect to a PCI DSS 3.2 compliant service. The current version of SocketTools will only establish a secure connection using TLS 1.2, and will automatically disable the use of weaker cryptographic algorithms that can potentially cause the server to reject the connection.

SocketTools uses the Windows CryptoAPI and Schannel provider to implement support for TLS on the Windows platform. This provides several advantages to the developer because it is part of the core operating system. The application developer does not need to redistribute additional libraries, and updates are included as part of the normal Windows Update process, ensuring that their end users have the most current security updates and improvements.

This means that the security functionality in SocketTools is directly tied to the version of the Windows operating system that their end-user is running their application on (not the version of Windows that was used to develop the application). Versions of Windows that are currently supported by Microsoft, from Windows 7 on the desktop to Windows Server 2008 R2, provide support for TLS 1.2. However, older versions of Windows that are no longer supported by Microsoft only provide support for TLS 1.0. Applications on those older platforms will fail to connect to credit card payment processors, gateways, and other payment service providers after June 30, 2018.

If you are using Windows Embedded POSReady 2009 (commonly used with devices such as cash registers and automated teller machines), Microsoft has released a hotfix that provides support for TLS 1.2. Because this is a variant of Windows XP SP3, it is also possible to install the hotfix on Windows XP systems. However, it is strongly recommended that you upgrade to the current version of Windows. Although the hotfix enables support for TLS 1.2, it does not update the cryptographic cipher suites supported on Windows XP. Less secure cipher suites will continue to be presented to the server, which may cause it to reject the connection. If you install the hotfix, you must also upgrade to the current version of SocketTools to establish a secure connection.

See Also

Unable to Establish Security Context
Support for TLS 1.2 on Windows XP

In older versions of Windows, it was common for regular users to run with administrative privileges. In fact, most Windows applications made the assumption that the user was a member of the Administrators group and therefore had unrestricted access to the entire system. This has changed with the User Account Control (UAC) system, which limits access to critical system resources, even when the user has administrative privileges.

Least Privilege Applications
Whenever you attempt to install an application, copy files in a protected folder, modify the registry or change the system configuration, UAC will block the operation and prompt the user to confirm the action being taken. When UAC is enabled, all applications effectively run with restricted privileges, regardless of the groups the current user is a member of.

As a software developer, the most significant change you need to make is with the general assumption that you have control over the entire system. For example, you may presume that you can create files in the same directory where your application is installed, or that you can create keys anywhere in the registry. You may also assume that you can do things like register ActiveX components, install message hooks or attach to another process. All of these things are now restricted, and unlike previous versions of Windows, telling the user that they are required to have administrative privileges won’t resolve the issue. The UAC system is specifically designed to limit access to system resources, even when the user is an administrator.

The most important things to keep in mind are:

1. Do not assume that you can create files in the same directory as the application. You will not have privilege to create files under C:\Program Files or C:Windows. This is a particularly important because many applications create data and configuration files in their installation folder.

2. Store shared application data and configuration files in the common AppData folder. This is typically the C:\ProgramData folder. For per-user data and configuration files, store them in the user’s AppData folder, typically C:\Users\UserName\AppData\Roaming. Keep in mind that you should never make an assumption about what the actual path is. Use the SHGetFolderPath function that is part of the shell API to determine the correct location.

3. Never assume that you can create registry keys anywhere other than HKEY_CURRENT_USER. Access to other parts of the registry is generally read-only. Any information that your program needs to store in the registry should be stored under HKEY_CURRENT_USER\Software\Company\AppName.

4. Don’t request more privilege than required when accessing a file or registry key. For example, if you are only reading a file, don’t attempt to open it with read-write access. The same applies to the registry; don’t open a key with KEY_ALL_ACCESS rights if you’re only going to read a key value. Request only those privileges that you need at the time that you need them.

5. Never make the assumption that a particular Windows API function will always succeed. Functions which have “always worked” under older versions of Windows may fail under Windows 10 due to access restrictions. For example, installing message filters or system-wide hooks can fail because the process doesn’t have the appropriate access rights. Always check the return values and practice defensive coding. Because it worked under previous versions of Windows is no guarantee that it will work correctly under Windows 10.

User Virtualization
What do you do about applications that have already been written which don’t follow those rules? For example, what if your program creates INI files in the same folder as the executable, or stores configuration data in the registry under HKEY_LOCAL_MACHINE\Software? The good news is that your application will probably work correctly. This is because Windows includes support for user virtualization of specific parts of the filesystem and the registry.

When your program attempts to create or modify a file under C:\Program Files or C:\Windows it is automatically redirected to the user’s virtual store, which is typically C:\Users\UserName\AppData\Local\VirtualStore. If you are modifying a file that already exists, a copy of it will be made in the virtual store for the user. If you are creating a new file, it will only exist in the user’s virtual store. This happens transparently, and as far as your program is concerned there has been no change in the file path.

The system also virtualizes registry access under the HKEY_LOCAL_MACHINE\Software key. If your program creates or modifies a key value there, it will be automatically redirected to HKEY_CURRENT_USER\Software\Classes\VirtualStore\Machine\Software. As with the filesystem, this is completely transparent to your application.

It is also important to be aware of the potential side-effects of user virtualization. While many applications will be able to run without issue, some will fail unexpectedly. This will typically affect programs which store licensing information in the registry or implement anti-piracy methods like embedding license keys in the executable after installation. Virtualization can also create the appearance of a flaw in your software. For example, if you store global configuration data in the registry under HKEY_LOCAL_MACHINE, any configuration changes that are made will always be per-user because of virtualization. If user “A” makes a change, it will be virtualized to their registry hive and users “B” and “C” will not see those changes. Any changes made by user “B” will not be seen by user “A” or “C” and so on. This can cause users to think that the configuration changes they’re making aren’t persisting correctly, or can cause more serious problems such as the wrong database being opened, files not being created in the correct location and so forth.

Although user virtualization does help lessen the impact of the security changes in Windows, it is not intended to be used with new software. Microsoft has explicitly stated that developers should not depend on virtualization for two specific reasons. First, virtualization is a configurable option. By default it is enabled, but a system administrator can choose to disable it. Second, it is not guaranteed that it will be supported in future versions of Windows. Virtualization exists solely to help developers during a transition period, ensuring that legacy applications will continue to run. It is not a feature developers should count on in the future.

The SocketTools .NET Edition includes the InternetServer class that was designed to simplify the implementation of a TCP/IP server application. With only a few lines of code, you can create the framework for a multi-threaded server that is completely event driven. You only need to create event handlers and then write your server code to respond to those network events.

The SocketTools.InternetServer class makes developing server applications significantly easier; however, there are a few important concepts to keep in mind when using this class in your application.

Although the code that you’ll write will look like typical single-threaded code that responds to events, it’s actually a multi-threaded application, with each client session isolated in its own thread. When network events are raised, they are being raised within the context of the thread that’s generated them. For example, this means that when the OnRead event fires, it’s not firing within the thread that created that instance of the InternetServer class (e.g.: the main UI thread). Any code that you have inside that event handler is executing in the context of the background worker thread that’s managing that specific client session.

UI Updates
Because network events are being raised in the context of another thread, you cannot update user interface controls directly from within InternetServer event handlers. This is important because .NET does not allow one thread to modify a control that was created in another thread (typically the main UI thread). This is an absolute rule, and if you break it, your program is either going to hang or throw an exception. If you want to change any property values or call methods in a control, you need to create a delegate and marshal the call to the UI thread to using the Invoke method. Both the VB.NET and C# examples show how to do this; in the example, it’s used to update a ListBox control. Keep in mind that frequently updating the user interface from within an event handler can potentially have a negative impact on the overall performance of your program. Marshalling calls across threads to those UI controls is an expensive operation, and while you’re doing it, you’re not servicing network events like OnRead. You should keep it to a minimum, only updating the UI when absolutely necessary.

Shared Objects
Another important consideration is that you should never modify shared (global) objects without first synchronizing access to that object. In VB.NET it’s typically done using the SyncLock statement; in C# it’s done using the lock statement. The VB.NET and C# examples show to do this using a shared instance of a Hashtable class which is used to keep track of the number of bytes echoed by the server. While our lower-level API provides thread-safe queuing functions (InetServerEnqueue, InetServerDequeue, etc.) this doesn’t exist in the .NET class, largely because it would be redundant. If you want to use a queue, then you use the .NET Queue class, but the same rule applies; make sure that you synchronize access to the queue. While the InternetServer class does have Lock and Unlock methods, you should never use it for general purpose synchronization in your program. Calling the Lock method will cause every single client thread to block, and so while using Lock and Unlock would seem to be the easiest approach, it’s not a good idea for performance reasons.

Client Handles
The InternetServer class provides two general variations of many methods which are used to exchange data with the clients, ones which requires a handle to the client socket, and ones that do not. It’s not required that you specify a client handle if your code is inside an event handler (or in a function that’s being called by an event handler); the class knows which client raised the event and calls to Read and Write will work with that client (referred to as the “current client” in the documentation). However, if you want to exchange data with a client outside of an event handler, or with a client other than the current client, then you must specify a handle. Also, certain properties only return meaningful results from within an event handler. For example, the ClientAddress property (which returns the IP address of the client) should only be referenced from within an event handler such as OnConnect. The documentation notes when a property or method should only be used inside an event handler.

Finally, while it is possible to exchange data in an event handler with a client other than the one that generated the event, it’s not recommended. This is a case where you should use the Lock method to ensure that you’re the only thread that is attempting to read or write on that socket at the time. Two threads that attempt to read or write data on the same socket has undefined results; there’s no guarantee which thread would “get there first”, and the end result can be really unpredictable behavior by your program. One way to think about this is to think of your server program as a house, with each client connection being a room inside that house. You can do pretty much anything you want inside your own room (from within the event handler code that you write). However, if you want to go into another room and start rearranging the furniture, you need to make sure that every other thread is locked out while you do that. When you’re done and back in your own room, then you unlock the server and continue on.

One of the errors that developers occasionally ask about is the “Handle not owned by the current thread error”; what it actually means and the situations in which it can occur. This doesn’t tend to be an error message that developers using the SocketTools ActiveX controls encounter. It is almost exclusively an issue related to the .NET and Library Editions. The reason this error exists, an explanation of the threading model used and how things have changed involves a bit of a history and the origins of SocketTools.

Historical Overview
The very first release of SocketTools consisted of two versions, a 16-bit version for the Windows 3.1 platform, and a 32-bit version for the Windows 95 platform, which was relatively new at the time. Visual Basic 4.0 had been released, and with it came the new OLE controls which were later renamed to ActiveX. Initially, SocketTools was only available as controls (16-bit VBXs and 32-bit OCXs) and their code was largely shared between the two versions. When the decision was made to release a Library Edition which consisted of standard Windows DLLs, we had to go back to the drawing board to some extent.

There were a fair number of assumptions in the core networking code that worked well when it was in a control targeted for a single language. On the other hand, porting that code to standard DLLs presented a problem because a DLL can be used with virtually any Windows programming language. The solution was to redesign that core code from the ground up, focusing on implementing the DLL interfaces first, and then building the ActiveX controls on top of those APIs. All of the “inside knowledge” the ActiveX controls depended on had to be redesigned (the decision was made early on that we didn’t want to create undocumented functions specifically for the controls.) Rather than creating our own shortcuts, it forced us to use our own code much as any other developer would.

Multi-threading
As a result of this re-development, there were two central issues that we had to address. One was support for Unicode, and the other was multi-threading. Unicode support was a fairly easy decision to make. We already had to support it internally because 32-bit ActiveX controls use Unicode. And while it wasn’t considered to be a significant issue years ago, we knew that it would be in the future. Multi-threading support was a bit more problematic. We knew that it was important in a general sense, however Visual Basic was (for all intents and purposes) a single-threaded language and ActiveX controls use single-threaded apartments. In essence, COM made sure that there would only be one object per thread and that fit nicely with the Windows Sockets API which allows only one outstanding blocking socket operation per thread. With a DLL, we couldn’t make any assumptions about the language it would be used with, how threads would be managed, or if worker threads would be created at all.

We decided on two principal design goals when it came to the SocketTools API. One was to make sure it could be used in both a single-threaded and multi-threaded program without requiring any special coding on the part of the developer. Every function had to be designed to be thread-safe, but this introduced another fundamental problem: sockets are not inherently thread-safe. In other words, when you have two threads reading and writing on the same socket, there’s no guarantee which thread is actually going to read the data, or in what order the data is going to be written. The developer has to use some synchronization mechanism to ensure that thread A is not reading data that thread B expects to read. That tied into the second design goal, which was to make sure the API wouldn’t provide the programmer with just enough rope to hang himself. After all, SocketTools was specifically designed for developers who don’t have a lot of experience with network programming. They just want to be able to add features like downloading files or the ability to send emails, without having to worry about all of the low-level details.

Thread Affinity
This lead to the decision to implement a threading model in the DLLs that was functionally similar to how COM apartment threading works, but with a bit more flexibility. Whenever a handle to a client session is created, it is associated with the thread that created it. The handles that are used with the SocketTools API are really a kind of pseudo-handle that references some internal data structures, along with I/O buffers and the actual socket handle. Whenever the handle is passed to a function, it is dereferenced internally and certain checks are performed depending on the type of function being called. One of those checks is whether the thread that is calling the function is the same as the thread that created the handle. If they don’t match, the error ST_ERROR_NOT_HANDLE_OWNER is returned to the caller.

This check isn’t actually performed on all functions; however, any function that deals with I/O on the socket will check thread ownership. Because it’s possible that the developer would want to have one thread initially create the session, but have another thread do the actual work, a mechanism was added where a thread could assume ownership of a handle created by another thread; this is done using the AttachThread function. In many ways, this provided the best of both worlds. Developers could pass client handles to other threads, but they had to explicitly establish ownership which would prevent inadvertent errors in their code that would prove very difficult to debug.

Free-Threading Model
Over time, we have had some developers express some frustration that handles (or class instances, in the case of the .NET classes) cannot be freely passed between threads. Multi-threaded languages have become the rule rather than the exception, and it’s really only the legacy languages like Visual Basic 6.0 which don’t have native support for threading. With that in mind, for SocketTools we decided to revisit the issue of the thread ownership model that we use. In the end, we have decided that in the interest of making things safer for developers, our implementation was overly restrictive. If the programmer wants to take responsibility for thread synchronization (which would typically have to be done in most cases anyway), then he should be able to without the additional bookkeeping involved in tracking what thread owns a particular client handle at that point in time.

In SocketTools, when you create a connection you will be able to continue to use the same threading model used in previous versions, or you can choose to specify a “free-threading” option that tells the class or library that any thread can use that session handle. It is important to keep in mind that if you use this option, you are responsible for synchronizing access to the session yourself. For example, if two threads call the FtpCommand function using the same handle, if you don’t synchronize them you will have no control over which command is actually sent to the server first. This can lead to logical errors in the program which can be very difficult to find in a large program, and it’s often the case that they can’t be reproduced reliably. With the default threading model, you would catch this during testing because one of those threads would get an error indicating that it’s not the handle’s owner. With the free-threading model, that responsibility falls to you. It’s an advanced option we feel will be of benefit to developers; however we recommend that you continue to use the default threading model whenever possible.