NetDecryptString(*string pInData, long pDataLength, String pPassword, long pAlgorithm=NET:CALG_AES_256, long pHashAlgorithm=NET:CALG_SHA_256, Long pCipherMode=NET:CRYPT_MODE_CBC, Long pPadding=NET:PKCS5_PADDING,<String pIV>)

Description

This function decrypts a string, using a password, and returns the decrypted string. The original string is unaltered.
The decrypted string size will always be the same as, or less than, the encrypted string size.

Parameters

Parameter	Description
pInData	A pointer to the data to be decrypted. The original data is not altered.
pDataLength	The length of the data to decrypt.
pPassword	The password to use for the decryption. If pHashAlgorith is set to net:CALG_NOHASH then the password must be the correct length for the encryption algorithm. For AES256 this is 32 bytes.
pAlgorithmn	The Algorithm to use. Currently supported algorithms are; NET:CALG_AES_256
pHashAlgorithm	The Hashing Algorithm to use on the Password, before the encryption happens. Hashing a password improves the strength of the password. Algorithms supported by NetMakeHash are supported here.
pCipherMode	The cipher mode to use. Currently supported options are; NET:CRYPT_MODE_CBC
pPadding	The Padding mode to use. Currently supported options are; NET:PKCS5_PADDING
pIV	The Initialization Vector to use. The length of the Init Vector is determined by the algorithm. For AES 256 it's 16 bytes long. Strings that are two long are clipped. Strings that are too short are padded with chr(0). If not passed (or passed as a blank string) then a string of null characters (chr(0)) is used.

Return Value

Returns the decrypted string. If the function fails a blank string is returned.

Examples

str  string(100)
enc  string(112)
dec  string(100)
  code
  str = 'NetTalk is Amazing'
  enc = NetEncryptString(str,len(str),'1234')
  dec = NetDecryptString(enc,len(enc),'1234')

st  StringTheory
  code
  st.SetValue('NetTalk Is Amazing')
  st.SetValue(NetEncryptString(st.GetValuePtr(),st.Length(),'1234'))
  st.SetValue(NetDecryptString(st.GetValuePtr(),st.Length(),'1234'))

See Also

NetEncryptString, NetEncryptStringAES, NetDecryptStringAES

NetDecryptStringAES(String pInData, String pPassword)

Description

Same as calling NetDecryptString, with all optional parameters set to default, and the Algorithm set to NET:CALG_AES_256.

Parameters

Parameter	Description
pInData	The data to decrypt.
pPassword	The password

Return Value

Returns the decrypted string. If the function fails a blank string is returned.

Examples

dec = NetDecryptStringAES(clip(someencrypteddata),'1234')

See Also

NetEncryptString, NetEncryptStringAES, NetDecryptString

NetEncryptString(*string pInData, long pDataLength, String pPassword, long pAlgorithm=NET:CALG_AES_256, long pHashAlgorithm=NET:CALG_SHA_256, Long pCipherMode=NET:CRYPT_MODE_CBC, Long pPadding=NET:PKCS5_PADDING,<String pIV>,<*Long pLength>)

Description

This function encrypts a string, using a password, and returns the encrypted string. The original string is not altered. Note that storing encrypted data in CSTRINGs is not allowed because encrypted strings can contain the null (chr(0) character, which truncates data in CSTRINGs.

The encrypted string size will always be the same as, or larger than, the plain string size. The size growth will depend on the algorithm used. For AES this will be at the next multiple of 16 bytes.

Parameters

Parameter	Description
pInData	A pointer to the data to be encrypted. The original data is not altered.
pDataLength	The length of the data to encrypt.
pPassword	The password to use for the encryption. This field is not clipped. If pHashAlgorith is set to net:CALG_NOHASH then the password must be the correct length for the encryption algorithm. For AES256 this is 32 bytes.
pAlgorithmn	The Algorithm to use. Currently supported algorithms are; NET:CALG_AES_256
pHashAlgorithm	The Hashing Algorithm to use on the Password, before the encryption happens. Hashing a password improves the strength of the password. Algorithms supported by NetMakeHash are supported here.
pCipherMode	The cipher mode to use. Currently supported options are; NET:CRYPT_MODE_CBC
pPadding	The Padding mode to use. Currently supported options are; NET:PKCS5_PADDING
pIV	The Initialization Vector to use. The length of the Init Vector is determined by the algorithm. For AES 256 it's 16 bytes long. Strings that are two long are clipped. Strings that are too short are padded with chr(0). If not passed (or passed as a blank string) then a string of null characters (chr(0)) is used.
pLength	Contains the length of the binary data being passed back. The encrypted string size will always be the same as, or larger than, the plain string size. Since the exact size needs to be known (as a string of the exact size has to be passed to NetDecryptString or NetDecryptStringAES)

Return Value

Returns the encrypted string. If the function fails a blank string is returned.

Notes

Strategies for managing the encrypted string length

When encrypting a string the length of the encrypted value may be longer than the original string (up to another blocksize-1 longer). when decrypting the string the exact correct length of encrypted data should be passed to the decrypting function. Unfortunately Clarion does not have a native string type that can contain both binary data, and has a determined length. Using a CSTRING is not possible (cannot contain binary data) and using CLIP on a STRING is not correct since the binary encrypted data could end in a space.

Using StringTheory

In code this can be handled using a StringTheory object;

str.SetValue(NetEncryptStringAES('some text to keep a secret', 'password'))

This can then be base64 encoded before being written to the disk

str.base64encode(st:nowrap)
cus:secret = str.GetValue()

Reversing this is straightforward;

str.SetValue(clip(cus:secret)) ! can clip, because base64 encoded.
str.base64decode()
str.SetValue(NetDecryptStringAES(str.GetValue(),'password')

One advantage of this approach is that the data is stored in the database as ASCII text, not binary, and will also travel well when exported to CSV, JSON, XML and so on. The primary disadvantage of this approach is that base64 uses up a bit more string space (25% more).

Using a Length Field

An alternative approach makes use of a Length field which works in conjunction with the String field.

cus:secret = NetEncryptStringAES('some text to keep a secret', 'password',cus:SecretLen)

Decrypt as

dec = NetDecryptStringAES(Sub(cus:secret,1,cus:SecretLen),'password'

If this approach is used then the database field type MUST be capable of holding binary data.

Using CLIP

dec = NetDecryptStringAES(clip(cus:secret),'password')

Ordinarily this approach would fail if the encrypted secret ended with one or more spaces. However, from NetTalk 12.02 this code will work but only for NetDecryptStringAES, not for NetDescryptString.


Examples

str  string(100)
enc  string(112)
  code
  str = 'NetTalk is Amazing'
  enc = NetEncryptString(str,len(str),'1234')

st  StringTheory
  code
  st.SetValue('NetTalk Is Amazing')
  enc = NetEncryptString(st.GetValuePtr(),st.Length(),'1234')

See Also

NetEncryptStringAES, NetDecryptString, NetDecryptStringAES

NetEncryptStringAES(String pInData, String pPassword, <*Long pLength>)

Description

Same as calling NetEncryptString, with all optional parameters set to default, and the Algorithm set to NET:CALG_AES_256.

Parameters

Parameter	Description
pInData	The data to encrypt.
pPassword	The password

Return Value

Returns the encrypted string. If the function fails a blank string is returned.

Examples

enc = NetEncryptStringAES('NetTalk is Amazing','1234')

See Also

NetEncryptString, NetDecryptString, NetDecryptStringAES

NetGetIPInfo (*Net:IpInfoQType pQueue, long pShortList)

Description

Every computer has multiple IP addresses. This function populates a queue with information about each of the addresses currently assigned to this computer. This function best answers the question "What is the IP address of this machine on the LAN?"

Note that if your computer connects to a server on the WAN (like the internet) and goes through a NAT Router to get there, then that machine will see the IP address of the NAT router, and not any of the addresses in this queue. If you want to know what your IP address is as seen by external servers, then use a WebClient class to access a service like https://api.ipify.org .

Parameters

Parameter	Description
pQueue	A queue to contain the results of the call. The queue is of type Net:IpInfoQType. This type is declared in \clarion\accessory\libsrc\win\netall.inc Net:IpInfoQType   Queue, Type IPAddressCstr       cstring (NET:IPStringSize+1) SubnetMaskCstr      cstring (NET:IPStringSize+1) BroadCastCstr       cstring (NET:IPStringSize+1) Gateway1CStr        cstring (NET:IPStringSize+1) Gateway2CStr        cstring (NET:IPStringSize+1) Gateway3CStr        cstring (NET:IPStringSize+1) Gateway4CStr        cstring (NET:IPStringSize+1) Gateway5CStr        cstring (NET:IPStringSize+1) DHCPServerCStr      cstring (NET:IPStringSize+1) PrimaryWinsCstr     cstring (NET:IPStringSize+1) SecondaryWinsCStr   cstring (NET:IPStringSize+1) DCHPenabled         long WinsEnabled         long LeaseObtained       long LeaseExpires        long AdapterDescription  cstring (128+4) AdapterName         cstring (256+4) AdapterType         long AdapterIndex        long IPindex             long MACAddress          string(20) Family              Long                   End
pShortList	Deprecated: Set it to False. If this property is true then only IP, SubnetMast and BroadCast addresses are filled into the queue.

Return Value

Returns 0 if the function is successful, non zero otherwise.

Examples

qIP          QUEUE(Net:IpInfoQType),PRE()
             END
  Code
  NetGetIPInfo (qIP, 0) ! Get Full List

See also

NetOptions

NetMakeHash (*string pInData, long pLength, long pHashType)
NetMakeHash (string pInData, long pHashType=net:CALG_SHA_256)

Description

Calculates the HASH value of a string.

Parameters

Parameter	Description
pInData	The string to Hash.
pLength	The length of the incoming string.
pHashType	One of the following; net:CALG_NOHASH net:CALG_MD2 net:CALG_MD4 net:CALG_MD5 net:CALG_SHA1 net:CALG_SHA_256 net:CALG_SHA_384 net:CALG_SHA_512

Return Value

Returns the hash of the string as a binary string value. If you need to convert this to Base64 or HexEncoding then use StringTheory to do that.

Examples

Hash a value in a simple string

str  String(10)
hash  String(1024)
  code
  str = 'abcde'
  hash = NetMakeHash(str,5,net:CALG_SHA_256)

Hash a value in a StringTheory object

str   StringTheory
  code
  str.SetValue('abcde')
  str.SetValue(NetMakeHash(str.GetValuePtr(),str.Length(),net:CALG_SHA_256))
  str.ToHex(st:UPPER)


See also

NetMakeHMAC

NetMakeHMAC (*String pInData, Long pLength, String pSecret, Long pHashType)

Description

Calculates the HMAC value of a string and secret pair.

Parameters

Parameter	Description
pInData	The string to Hash.
pLength	The length of the incoming string.
pSecret	The secret value used in the HMAC. This value will be clipped so cannot end with a space character.
pHashType	One of the following; net:CALG_MD5 net:CALG_SHA1 net:CALG_SHA_256 net:CALG_SHA_384 net:CALG_SHA_512

Return Value

Returns the HMAC of the string and secret as a binary string value. If you need to convert this to Base64 or HexEncoding then use StringTheory to do that.

Examples

HMAC a value in a simple string

str     String(10)
secret  string(10)
hmac    String(1024)
  code
  str = 'abcde'
  secret = '1234'
  hmac = NetMakeHMAC(str,5,secret,net:CALG_SHA_256)

HMAC a value in a StringTheory object

str     StringTheory
secret  string(10)
  code
  str.SetValue('abcde')
  secret = '1234'
  str.SetValue(NetMakeHMAC(str.GetValuePtr(),str.Length(),secret,net:CALG_SHA_256))
  str.ToHex(st:UPPER)


See also

NetMakeHash

NetOptions (long flag, *string pData)

Description

NetOptions is a general purpose function which lets you read, and write, various internal NetTalk settings.

Parameters

Parameter	Description
flag	One of the equates listed in the table below
pData	The value to set (when using SET equates) or the result from the function if using GET equates.

Equates

The where column below indicates where the call should be made.
After (You can only call this after the parent call in the Init() method),
Before (You can only call this before the parent call in the Init() method) or
Either (You can call this anytime you like)

Equate	Description	Where
NET:COUNTOUTGOINGPACKETS	Used by NetSimple objects to determine the number of outgoing packets that are still in the DLL. Used in the GetInfo() method.	After
NET:DNSLOOKUP	Does a DNS lookup on the string that you pass to it. The result is placed in the string. This is a blocking call. In other words processing is suspended while the DNS lookup occurs.	After
NET:SETENCRYPTIONKEY	Can be used to set a unique encryption key string for your applications. String passed should be of type string (24). Preferably set this early in the loading cycle before packets are sent or received.	Before
NET:GETDGINSTANCE	Gets the datagram instance of your NetAuto instance (starts at 0)	After
NET:GETDGPORT	Gets the datagram port number (see also NET:GETSPORT)	Either
NET:SETDGPORT	Sets the datagram port number (see also NET:SETSPORT)	Before
NET:GETDLLTHREAD	Gets the thread number of the NetTalk Callback Window, which is in the DLL. If the window is not open then this returns 0.	Either
NET:GETDLLVERSION	Gets the version out of the DLL being used. If you compile in local mode this will be the version of the .lib file that you compiled with, otherwise it will report the DLL version (standalone build).	After
NET:GETDNSLIST	Gets a comma separated list of the DNS Servers in specified in the Networking TCP/IP properties.	After
NET:GETHOSTNAME	Gets the hostname of the machine you are using	Either
NET:GETHOSTIPLIST	Gets a list of IP addresses for this machine.	Either
NET:GETIAMASERVICE	Tells NetTalk this process is a Service, and that it should not close down when the current Session Logs Off	Either
NET:GETINACTIVESERVICETIMER	(Advanced option). Gets the time to wait between polls to inactive servers. (in hs) - This only affects the NetAuto objects.	Either
NET:SETINACTIVESERVICETIMER	(Advanced option). Sets the time to wait between polls to inactive servers. (in hs) - This only affects the NetAuto objects.	Before
NET:GETMAXINSTANCES	Gets the maximum number of NetAuto instances that you can run on one machine.	Either
NET:SETMAXINSTANCES	Sets the maximum number of NetAuto instances that you can run on one machine.	Before
NET:GETNETDESCRIPTION	Gets the NetName Description of the current instance. This is the user friendly version of the netname e.g. 'Fred Bloggs at CapeSoft'	After
NET:SETNETDESCRIPTION	Sets the NetName Description of the current instance. This is the user friendly version of the netname e.g. 'Fred Bloggs at CapeSoft'	Before
NET:SETNETDESCRIPTION_ALWAYS	Sets the NetName description of the current instance. This is the user friendly version of the netname e.g. 'Fred Bloggs at CapeSoft'. This option also stores it in the registry for the next time as well.	Before
NET:GETNETID	Gets the NetID structure for the current instance. Net:AutoIDType is defined in \clarion\accessory\libsrc\win\netall.inc	After
NET:SETNETNAME	Sets the NetName of your NetAuto Instance	Before
NET:GETNETNAME	Gets the NetName of you NetAuto Instance. You can also call the NetAutoGetNetName() function.	After
NET:SETNETAUTOLISTENINGPORTIP	Allows you to bind the NetAuto Objects Listening Ports to a specific IP address. This can be useful if you are running multiple network cards, but would only be used in rare situations	Before
NET:SETRECOVERYOPTIONS	Sets the NetAuto objects Error Recovery parameters. Demonstrated in the netdemo application. Use the NET:AutoRecoveryOptionsType group.	Either
NET:GETRESEND_CloseConnectionBeforeResend	(Advanced option only). Indicates if the NetAuto objects' connection will be closed before any error correction resending takes place	Either
NET:SETRESEND_CloseConnectionBeforeResend	(Advanced option only). Sets if the NetAuto objects' connection must be closed before any error correction resending takes place.	Either
NET:GETRESEND_OnlySendIfHostActive	(Advanced option only). Indicates if the NetAuto objects' error correction resending takes place only if the Host is active in the Servers queue (ie that there is DG communication between server and client)	Either
NET:SETRESEND_OnlySendIfHostActive	(Advanced option only). Sets the NetAuto objects' error correction resending to take place only if the Host is active in the Servers queue (ie that there is DG communication between server and client)	Either
NET:GETSINSTANCE	Gets the streamed socket instance of your NetAuto instance (starts at 0)	After
NET:GETSPORT	Gets the streamed port number (see also NET:GETDGPORT)	Either
NET:SETSPORT	Sets the streamed port number (see also NET:SETDGPORT)	Before
NET:GETSTATS	Get Statistics on how many records are in queues and memory used	After
NET:SETUSEONE255BROADCAST	Tells the NetAuto Broadcast system to use one 255.255.255.255 broadcast instead of one broadcast per subnet. (Not recommended unless you know what you are doing).	Either
NET:GETOUTWAITING	Gets the size of data (in bytes) currently waiting in the qAutoOutgoingPacketsData	After

Return Value

The value returns nothing, although the contents of the pData parameter may be changed

Examples

1. Change the base DG port for your system

val   string(20)
 
  val = 27000
  NetOptions(NET:SETDGPORT,val)

2. Change the maximum number of instances of your program (or programs sharing the same Base DG Port) on the same machine.

val   string(20)
 
  val = 10
  NetOptions(NET:NET:SETMAXINSTANCES,val)


3. Use the Stats functionality to tell you how many outgoing NetSimple and NetAuto packets are waiting in the DLL.

SimpleOutData_Size long ! How many outgoing NetSimple packets in DLL
OutgoingPacketsData_Size long ! How many outgoing NetAuto packets in DLL

ourNETStats Group(NET:StatsType).
ourNETSTatsStr String (size(NET:StatsType)),over(ourNETStats)

GetStats Routine
  NetOptions (NET:GETSTATS, ourNetStatsStr) ! Call the DLL and ask for the stats
  SimpleOutData_Size = ourNetStats.qSimpleOutData_Size
  OutgoingPacketsData_Size = ourNetStats.qOutgoingPacketsData_Size

For a complete description of the Net:StatsType group look in \clarion\accessory\libsrc\win\netall.inc.


See also

NetPing (String pIP, long pTTL)

Description

Sends a PING to the destination address. Note this is a blocking, syncronous call. The result is returned immediately. Ping only checks to see if the server at the address will respond to a Ping command. It does not check if a port on the machine is open or not. Note that a Ping can fail even if the server is available as many servers are set up to reject Ping packets and not respond to them.

Therefore a successful Ping tells you (only) that a machine exists - it does not tell you if a port is open.
Also a failed Ping does not mean the server is unavailable, only that it has not replied to the Ping.

Parameters

Parameter	Description
pIP	The IP address to ping.
pTTL	Timeout (in milliseconds. 1000=1 second)

Return Value

Returns either 0 for success or ERROR:PingUnSuccessful if it fails.

Examples

result = NetPing('www.google.com',3000)