| |
|
| Formats |
| 1. Compute
Hash key |
HSH( string$
[,hashkey$ ][ ,hashtype [,KeyHashedWith]
][,ERR=stmtref] ) |
| 2. Encrypt
data using key |
HSH(
PASSWORD string$ WITH method$
,KEY=hashkey$ [,SIZ=keylen
] [,TBL=initval$ ] [,ERR=stmtref]
) |
| 3. Decrypt
data using key |
HSH(
EXTRACT string$ WITH method$
,KEY=hashkey$ [,SIZ=keylen
] [,TBL=initval$ ] [,ERR=stmtref]
) |
Where:
| string$ |
String
expression whose hash value is to be returned. |
| hashkey$ |
String
expression representing key to use during the
hashing/encryption operation. |
| hashtype |
Optional
numeric value representing the type of hash to
return for the data. An invalid value causes
Error #41 Invalid integer encountered. See Note
below. |
| initval$ |
Optional
initialization value used by some ciphers. |
| KeyHashedWith |
Optional
numeric value used to specify which hashtype
the key is based on hashtype values 0
through 6, 224 (and 256, 384, or 512 when using
PxPlus). Only
available with hashtype 7 (HMAC). The HMAC hash
is a special case. Data that has been hashed with
a hashtype such as MD5 will return an
MD5 hash key. When the original data and the MD5
hash key are hashed together as an HMAC, this new
HMAC hash is called aMessage Authentication Code.
An invalid value
results inan Error #41: Invalid integer
encountered.
|
| keylen |
Is
supplied overrides the length of the key used in
the encryption algorithm. Applicable only for
those algorithms that allow for multiple key
lengths. (Value specified is the number of bytes
in the key) |
| method$ |
String
expression with the name of the encryption
algorithm to use. |
| stmtref |
Program
line number or statement label to which to
transfer control. |
|
| Format
1 |
Compute
Hash Keys |
| |
|
| Returns |
String
value that is a hash key for the data. |
| |
|
| Description |
The
HSH( ) function returns a hash value for
the given string. The hash value returned in a two-byte
string can be used to check the integrity of a character
string. The initial value can be used to calculate the
hash value of an entire string by taking its component
parts. (See the examples below.) The type of hash algortihm that will be
appliced to the data is defined by the hashtype
value provided. If no hashtype is given the
default ProvideX internal 2 byte hash algortihm will be
used. The following table defines the currently supported
hashtype values:
| Hashtype |
Description |
| 0 |
ProvideX 2-byte
hash (default if not specified) |
| 1 |
MD5 |
| 2 |
MD4 |
| 3 |
MD2 |
| 4 |
SHA1 |
| 5 |
MDC2 |
| 6 |
RIPEMD |
| 7 |
HMAC |
| The following are +PxPlus
Exclusive functionality |
| 224 |
SHA224 (28 byte
value) |
| 256 |
SHA256 (32 byte
value |
| 384 |
SHA384 (48 byte
value) |
| 512 |
SHA512 (64 byte
value) |
|
| |
The hashkey$ value is
used as a starting hash value and should be provided when
hashing the data a bit at a time. It is optional if hashtype
is 0, but the value must be 2 characters in length or an
Error #46: Length of string invalid is generated. The
value is Ignored for hashtypes 1 through 6 but
must be supplied if hashtype is 7 (HMAC) -- see example
below.HMAC hashing is special in that it
assumes
|
| |
|
| Examples |
To
get a ProvideX hash of a string:
PRINT hta(hsh("An
internal ProvideX Hash"))
83C9
To get a ProvideX hash of
a string based on a key:
PRINT hta(hsh("A
internal ProvideX Hash based on a
Key","K1",0))
2698
To get an MD5 hash:
PRINT hta(hsh("A
string to be MD5 hashed",1))
C9755C05F3EF1704114446A04F4072DF
To get or check a Message
for Authentication based on HMAC-SHA1:
Data$="This is a
string of data"
SHA1Hash$ = HSH(Data$,4)
MessageAuthenticationKey$ = HSH(Data$, SHA1Hash$,7,4)
IF KeyReceived$<>MessageAuthenticationKey$
THEN MSGBOX
"Message has been tampered with"
|
| Format
2 & 3 |
Encrypt/Decrypt data string |
| |
The
Encryption/Decryption functionality was a +PxPlus
Exclusive for version 7.
Included in V8 or ProvideX
|
| Returns |
Encrypted
(or Decrypted) data string value based on the value in string$,
the encryption method, and key value |
| |
|
| Description |
These
forms of the HSH( ) function can be used
to use any of a number of industry standard encryption
formulas to encode data. The HSH(PASSWORD
...) function will take a string of data
and, using the specified encryption method and key,
return its encrypted value. The HSH(EXTRACT ...)
function can be used to reverse this encryption. Each encryption algorithm (cipher)
has specific rules that must be followed by the
application and the encryption process in terms of the
size and type of key to be provided. Some algorithms
require unique keys for encryption versus decryption
enabling you to encrypt data for another application that
itself might only the decryption key.
The nature of algorithm
chosen is beyond the scope of this document. We suggest
that you refer to documentation specific to the algorithm
chosen or the OpenSSL whose functions we use for further
information.
The method$ value
is used to determine the type of algorithm to apply. The
basic algorithms supported (at time of printing) are:
| Method |
Description (data
derived from www.wikipedia.org information) |
| aes |
Advanced
Encryption Standard (AES), also known as
Rijndael, is a block cipher adopted as an
encryption standard by the US government. |
| bf |
Blowfish
is a keyed, symmetric block cipher, designed in
1993 by Bruce Schneier and included in a large
number of cipher suites and encryption products. |
cast,
cast5 |
CAST
is a block cipher used in a number of products,
notably as the default cipher in some versions of
GPG and PGP. It has also been approved for
Canadian government use by the Communications
Security Establishment. |
des,
des3 |
The Data
Encryption Standard (DES) is a cipher (a
method for encrypting information) selected as an
official Federal Information Processing Standard
(FIPS) for the United States in 1976, and which
has subsequently enjoyed widespread use
internationally. Triple DES (des3)
is a block cipher formed from the Data Encryption
Standard (DES) cipher by using it three times |
| desx |
DES-X is
a variant on the DES (Data Encryption Standard)
block cipher intended to increase the complexity
of a brute force attack using a technique called
key whitening. |
| rc2 |
RC2 is a block
cipher designed by Ron Rivest in 1987. ("RC"
stands for "Ron's Code" or "Rivest
Cipher") |
| rc4 |
RC4 (also known
as ARC4 or ARCFOUR) is the most widely-used
software stream cipher and is used in popular
protocols such as Secure Sockets Layer (SSL) (to
protect Internet traffic) and WEP (to secure
wireless networks). |
Most of the
encyrption algortihms have a wide variety of options in
terms of how they are used thus the actual value in method$
usually needs to specify more than the basic method.
Again details as to the exact nature of each of the
methods is beyond this document.
The following is a table
of known/supported method$ values as of Sept
2006 within the OpenSSL libraries:
| method$
value |
Desciption
of cipher/encyption technique |
| bf-cbc |
Blowfish in CBC
mode |
| bf |
Alias for bf-cbc |
| bf-cfb |
Blowfish in CFB
mode |
| bf-ecb |
Blowfish in ECB
mode |
| bf-ofb |
Blowfish in OFB
mode |
| cast-cbc |
CAST in CBC mode |
| cast |
Alias for
cast-cbc |
| cast5-cbc |
CAST5 in CBC mode |
| cast5-cfb |
CAST5 in CFB mode |
| cast5-ecb |
CAST5 in ECB mode |
| cast5-ofb |
CAST5 in OFB mode |
| des-cbc |
DES in CBC mode |
| des |
Alias for des-cbc |
| des-cfb |
DES in CBC mode |
| des-ofb |
DES in OFB mode |
| des-ecb |
DES in ECB mode |
| des-ede-cbc |
Two key triple
DES EDE in CBC mode |
| des-ede |
Alias for des-ede |
| des-ede-cfb |
Two key triple
DES EDE in CFB mode |
| des-ede-ofb |
Two key triple
DES EDE in OFB mode |
| des-ede3-cbc |
Three key triple
DES EDE in CBC mode |
| des-ede3 |
Alias for
des-ede3-cbc |
| des3 |
Alias for
des-ede3-cbc |
| des-ede3-cfb |
Three key triple
DES EDE CFB mode |
| des-ede3-ofb |
Three key triple
DES EDE in OFB mode |
| desx |
DESX algorithm. |
| idea-cbc |
IDEA algorithm in
CBC mode |
| idea |
same as idea-cbc |
| idea-cfb |
IDEA in CFB mode |
| idea-ecb |
IDEA in ECB mode |
| rc2 |
Alias for rc2-cbc |
| rc2-cfb |
128 bit RC2 in
CBC mode |
| rc2-ecb |
128 bit RC2 in
CBC mode |
| rc2-ofb |
128 bit RC2 in
CBC mode |
| rc2-64-cbc |
64 bit RC2 in CBC
mode |
| rc2-40-cbc |
40 bit RC2 in CBC
mode |
| rc4 |
128 bit RC4 |
| rc4-64 |
64 bit RC4 |
| rc4-40 |
40 bit RC4 |
| rc5-cbc |
RC5 cipher in CBC
mode |
| rc5 |
Alias for rc5-cbc |
| rc5-cfb |
RC5 cipher in CBC
mode |
| rc5-ecb |
RC5 cipher in CBC
mode |
| rc5-ofb |
RC5 cipher in CBC
mode |
It is up to
the application programmer to assure that the key size
and contents are valid for the specifed cipher. Incorrect
key sizes or values may cause the function to fail. To
avoid issues with short keys, the system will always pad
the key supplied with nulls up to the key size specified
by the algorithm.
|
| |
|
|
|
| * Note * |
When
using a hashtype other than 0 (which is alway available)
or any of the Encryption/Decryption functionality, the
system will rely on the OpenSSL libraries to perform
process. Only versions of ProvideX that support OpenSSL
and have OpenSSL installed properly will be able to
access these hashes. In addition the hashtype and
encryption algorithm must exist within the OpenSSL
modules for the functions to work properly. Not all
builds of OpenSSL contain all possible algorithms. If a
specific hashtype is not available, an Error #99: Feature
not supported is reported. |
|
|
| Copyright information |
PxPlus
and ProvideX includes software developed by the OpenSSL
Project (http://www.openssl.org/) and cryptographic
software written by Eric Young (eay@cryptsoft.com) and Tim Hudson (tjh@cryptsoft.com),
|