Please enable JavaScript to view this site.

A-Shell Reference

Updated December 2022

This library, available under Windows as ashnet.dll and under Linux as libashnet.so, contains core logic for several network-related subroutines and functions, including:

HTTPxs
PDFX Email Type 4
CRYPTOxs
FTP2xs
OAUTH2xs

If needed, see the following topics, ASHNET Status Codes and Google Cloud Access Token

Update Notes

 

ASHNET
Edit

A-Shell
Version

Release
Date

Description

197

7.0.1761

2024 July

Update the manifest to resolve an issue where the DLL load would fail due to a manifest-related conflict with some other module. Note that Linux version number was also updated to 197 for consistency, although the manifest issue doesn't apply there, making 196 and 197 essentially identical.

196

7.0.1759

2024 June

ASHNET.DLL / libashnet.so 1.14.196 update, OAUTH2 bug fix: <\003><redirect> clause in refresh'token$ wasn't working.

195

7.0.1759

2024 May

ASHNET.DLL / libashnet.so 1.14.195 update: Add optional parameter add'param to OAUTH2xs.

194

7.0.1757

2024 April

ASHNET.DLL / libashnet.so  1.14.194 update

FTP2xs : fix issue with attempt to create remote directory would return a failure code if the directory already existed.
SFTP: fixed failure when client and server selected ssh-dss algorithm
HTTPxs: fix TLS 1.3 session resumption issue

193

7.0.1757

2024 April

ASHNET.DLL / libashnet.so.1.14.193 update: fixes an internal function linking failure caused by some internal updating of common functions in A-Shell 7.0.1757.3. libashnet.so no longer contains dynamic links back to the ashell executable, so this update will work with older ashell executables but not the other way around. Problem did not affect Windows DLL version.

192

7.0.1757

2024 Mar

ASHNET.DLL 1.14.192 update:

FTP2xs fix for issue with servers that issue an intermediate 150 response indicating a delay for anti-virus scanning.
FTP2xs XFTPF_RENAME no longer invalidates the cached directory contents, eliminating a directory reload for a slight performance improvement.
FTP2xs safeguard added to block an empty string from matching all files in a wildcard delete operation. It now returns an error.
SFTP mitigation of SSH Terrapin Attack by adjusting the availability of of the supported SSH algorithms.

191

7.0.1752

2023 Nov

Updated to support OAUTH2 authentication in PDFX Email Method 4, identified by the "[oauth2]" prefix on the password.

190

 

2023 Aug

Close a memory (handle) leak in HTTP.

189

6.5.1736

2023 Aug

Various library/protocol updates and fixes:

FTP2xs TLS 1.3 session resumption issues with FileZilla fixed
FTP2xs fixed issue with wildcard directly listings on some servers
SFTP max packet size limitation wasn't being respected
HTTPxs default character now UTF-8 as it was supposed to be but previously was ANSI

188

6.5. 1722

2022 Dec

Resolve various issues:

Office365 TLS negotiation
FTP2xs TLS negotiation and wildcard operations.
FTP2xs session reuse error with FileZilla Server v1.3
FTP2xs (SFTP) support added for ecdsa-sha2-nistp521 and -nist384 algorithms
OAUTH2 refinement for Microsoft endpoints to fix browser caching

187

 

2022 Nov

Support OAUTH2 OP_DEBUG flag; create oauth2dbg.log in OAUTH2.

186

 

2022 Oct

Modernize RSA priv/pub key loading; support other formats besides PEM; support mode 3 pw decryption (http); add asutil.

185

 

2022 Oct

Fix uninitialized keybits in crypto; fix broken XHTTPF_SSL_xxx symbols.

184

6.5.1717

2022 June

Various fixes and enhancements to ASHNET, mostly motivated by Google Drive requirements, including functionality to get a Google Cloud Access Token.

183

HTTPxs XHTTPF_FILERESP now supports the option to specify two file specs, separated by a vertical bar, e.g "resp1.txt|resp1.dat". When the second file is specified, if the response body is compatible, HTTP will extract an embedded file from the complete response into the specified file.

182

HTTPxs verbs: to specify a verb other than GET or POST, use the XHTTPF_HDRBODY option to add a header of the format < Verb: xxxxxx > where xxxxx may be any verb recognized by the server (e.g. PATCH, DELETE, etc.) Note that you still need to specify either  XHTTPF_REQPOST or XHTTPF_REQGETX.

181

HTTPxs XHTTPF_HDRBODY now works with XHTTPF_REQUPLOAD. As with all other XHTTPF_HDRBODY cases, put your special headers at the top of the request body (file or string), then a blank line (CRLF), then the body of the request, which in this case would be the list of files to upload.

180

HTTPxs XHTTPF_REQGETRAW now handles binary response bodies.

179

6.5.1717

2022 Aug

Close a memory corruption loophole exposed by uninitialized S,0 parameters.

177

6.5.1709

2021 Dec

Enhancements: (1) FTP2TIMEOUT now affects SFTP as well as FTP2; (2) XFTPF_RMVEXT (&h0200) now works for FTP2xs (SFTP mode only) as it does in FTPDLX.

175, 176

6.5.1703

2021 May

Fixes some issues with FTP2xs. Also includes minor updates to the underlying HTTP and SSL/TLS libraries.

 

 

2019 May, Ashnet 1.12.165

When the XHTTPF_REQGET call fails, it now returns an abbreviated status message in the response parameter instead of the full library debug string. In cases where the call succeeds in connecting to the endpoint, but the endpoint service then rejects the request, the response will be an HTTP header—e.g. "415 Unauthorized." In the case of a complete failure to connect, the response will be empty or "0". The status parameter will give additional information, as will a subsequent call using XHTTPF_GETSTSTXT.
A new opcode flag, XHTTPF_REQGETX (&h01000000) has been defined to implement a more advanced version of the "GET" operation. Currently the main visible difference is that the returned reponse will be more detailed in the case of a successful connection but a failed transaction, due to some kind of logic or validation issue on the server. The HTTP.DEF file contains the updated symbol definition.
You can now include custom headers—using XHTTPF_HDRBODY—with the string request versions of the XHTTPF_REQPOST and XHTTPF_REQGETX operations. Previously this was only possible with XHTTPF_FILEREQ, file based requests. Format the request string the same way you would the file, i.e. with CRLF between each custom header, then a blank line (terminate by CRLF), then, in the case of _REQPOST, the body of the request. GET operations have no request body.

2019 May, Ashnet 1.12.164

Refinement to HTTP to allow custom headers to be added to a GET request (XHTTPF_REQGET). Previously this was only possible with the POST request type (XHTTPF_REQPOST / XHTTPF_REQUPLOAD). To specify custom headers, set the XHTTPF_HDRBODY flag and put the new headers into the request$ parameter, using chr(13) to separate multiple headers, e.g.:

flags = XHTTPF_REQGET or XHTTPF_HDRBODY

request$ = "Referer: http://www.microsabio.com"

request$ += chr(13) + "User-Agent: A-Shell/ashnet-1.2.164"

...

xcall HTTP, 1, status, flags, url$, request$, response$, properties$

 

Note that you must specify at least 7 parameters—i.e., at least thru the properties$ parameter—even if the properties$ parameter is blank. Otherwise a more limited version of the routine will be used, which doesn't support this enhancement.

You can also put the custom headers into a file, as you would with XHTTPF_REQPOST + XHTTPF_FILEREQ + XHTTPF_HDRBODY. With the GET request, anything following the first blank line would be ignored.

Note that to examine/debug your headers, set the XHTTPF_DEBUG flag and then look at the DEBUG.LOG file on return from the XCALL.

2018 October, Ashnet 1.12.163

New subroutine OAUTH2 implements the industry-standard OAUTH2 protocol for authorization via the ASHNET library update 1.12.163.

2018 May, Ashnet 1.11162

Support secure protocols TLS 1.1 and TLS 1.2 in HTTP via the new flags:

Symbol

Value

Description

XHTTPF_SSL_TLS11

&h01000000

TLS 1.1 (or higher)

XHTTPF_SSL_TLS12

&h02000000

TLS 1.2 (or higher)

 

Fix problems with the ashnet.log file (XHTTPF_DEBUG) not getting written or released under some circumstances.
Remove 100 character limit on header lines included at the top of the request (using XHTTPF_HDRBODY). Maximum length is now unlimited, which is useful when headers include lengthy signatures or digests.
Append a connection failure code to the XHTTPF_GETSTSTXT return string, as well as the ashnet.log file to assist with debugging failed connections. See the Connection Failure Codes for a listing of the codes and meanings.

2016 November, Ashnet 1.8.153, 54

Relink with updated SSL, SFTP and HTTP libraries to incorporate many minor bug fixes and improvements in the underlying libraries over the last 11 months. The DLL is backwards compatible to A-Shell and ATE 6.2.

The properties options introduced in 1.8.153 now apply to the HTTPF_REQGET ("simple get") operation as well as the other operations/modes; previously they were ignored for the simple get. Also, the default timeout parameters (30 seconds on connection, 75 on read) now apply to the HTTPF_REQGET operation even if properties are not explicitly specified. Previously the timeouts were indeterminate, but definitely shorter than the new defaults.

2014 May, Ashnet 1.7.145

Security-related enhancement:

supports public/private key authentication for SFTP via AG_FTP or FTPDLX.
fixes problems with SFTP downloads without explicit local paths.
fixes a bug in CRYPTOxs where the dst parameter was being truncated if needed to allow for an explicit trailing null.
supports new CRYPTOxs function to generate public/private key files.

Note: requires ASHW32.EXE 6.1.1385.0+ and should be updated at same time.

2013 July, Ashnet 1.4.137

Implements support for initial functionality of CRYPTOxs

2013 June, Ashnet 1.4.135

Support new HTTPxs arguments certfile and certpw

Update Notes: 2012 October/November, Ashnet 1.4.132

User agent in headers now shows, for example, "ashnet 1.4.131."
Now accepts port specifications embedded in the URL, i.e. http://www.mydomain.com:10080/mypath. Previously it only accepted the port if it was appended to the end of the URL, but that is a non-standard syntax and results in the port not being included in the "Host: domain{:port}" header of a POST request. The syntax shown above, i.e. {scheme}<domain>{:port}{path} is preferable.
The DEBUG.REQ file (copy of the request) had an extra CR at the end of each line (CRCRLF instead of CRLF). This didn't affect the actual request, but may have confused tech support efforts.
When the XHTTPF_DEBUG flag is set, in addition to creating the DEBUG.REQ file, it also appends a line to ashnet.log indicating the ashnet.dll version, domain, port, SSL flag and return status, e.g.:

HttpRequest v127 to www.mydomain.com port 10080 (SSL) rc=201 HTTP/1.1 201 created

This serves mainly to eliminate doubts during debugging as to where and how the request (DEBUG.REQ) was sent.

In addition, a new log file, DEBUG.LOG, will be created that combines lower level details about the individual steps performed within the operation, but also a transcript of what is sent and received over the wire.

Support custom Content-Type prefixes for uploaded files using XHTTPF_REQUPLOAD
Support separate option to retrieve the HTTP status text using XHTTPF_GETSTSTXT
If the operation fails to connect to the server, a verbose log of the request details is now written to the file DEBUG.LE (e.g. LastError), which might be helpful in debugging.
Added XHTTPF_REQGETRAW: like XHTTPF_REQGET (&h0020) but works around a limitation of XHTTPF_REQGET in which certain characters outside the range supported by Latin1/ANSI (e.g. Russian or Chinese) would just be dropped from the response. Can also be used to retrieve binary data containing embedded nulls (such as a file), although you must then use XHTTPF_FILERESP (&h0200) to write the response to a file.

Subtopics

ASHNET Status Codes

Google Cloud Access Token