XLFSHAN ICR (6157)

Name

Value

NUMBER

6157

IA #

6157

DATE CREATED

2015/02/05

CUSTODIAL PACKAGE

KERNEL

USAGE

Supported

TYPE

Routine

DBIC APPROVAL STATUS

APPROVED

ROUTINE

XLFSHAN

NAME

XLFSHAN

GENERAL DESCRIPTION

This DBIA describes supported references in the routine
XLFSHAN which provides Kernel APIs for Secure Hash Algorithm (SHA) hashing of
input of various formats.

Federal Information Processing Standards Publication 180-4 (FIPS PUB 180-4)
specifies secure hash algorithms for computing a condensed representation of
electronic data (message). The hash algorithms specified in this Standard are
called secure because, for a given algorithm, it is computationally infeasible
1) to find a message that corresponds to a given message digest, or 2) to find
two different messages that produce the same message digest. Any change to a
message will, with a very high probability, result in a different message
digest.

STATUS

Active

KEYWORDS

KERNEL
LOGIC
MATH
SHA

DURATION

Till Otherwise Agreed

XLFSHAN

COMPONENT/ENTRY POINT

COMPONENT DESCRIPTION

VARIABLES

FILE

This extrinsic function returns the SHA hash for a
specified file entry.  It uses the FileMan API GETS^DIQ to extract the data
from the file. The input parameters match the input parameters for GETS^DIQ.
For complete details see the VA FileMan Developers Guide.

Format:  $$FILE^XLFSHAN(HASHLEN,FILENUM,IENS,[FIELD],[FLAGS])

The value returned is the SHA hash if successful, or "0" if the file could not
be opened/found.

VARIABLES	TYPE	VARIABLES DESCRIPTION
FILENUM	Input	(Required) File or subfile number.
IENS	Input	(Required) Standard IENS indicating internal entry numbers, as documented in the VA FileMan Developers Guide.
FIELD	Input	(Optional) See the GETS^DIQ documentation for possible values. If this is not passed it defaults to "**" which extracts all fields.
FLAGS	Input	(Optional) See the GETS^DIQ documentation for possible values.
HASHLEN	Input	(Required) The hash length in bits: 160 (SHA-1) 224 (SHA-224) 256 (SHA-256) 384 (SHA-384) 512 (SHA-512)

HOSTFILE

This extrinsic function returns the SHA hash of the
specified host file.  It uses $$FTG^%ZISH to load the host file for
processing.

Format:  $$HOSTFILE^XLFSHAN(HASHLEN,PATH,FILENAME)

The value returned is the SHA hash if successful, or "0" if the hostfile could
not be opened/found.

VARIABLES	TYPE	VARIABLES DESCRIPTION
PATH	Input	(Required) Full patch, up to but not including the filename.
FILENAME	Input	(Required) Name of the file.
HASHLEN	Input	(Required) The hash length in bits: 160 (SHA-1) 224 (SHA-224) 256 (SHA-256) 384 (SHA-384) 512 (SHA-512)

ROUTINE

This extrinsic function returns the SHA hash of a
routine.

Format:  $$ROUTINE^XLFSHAN(HASHLEN,ROUTINE)

The value returned is the SHA hash if successful, or "0" if the routine could
not be opened/found.

VARIABLES	TYPE	VARIABLES DESCRIPTION
ROUTINE	Input	(Required) The name of the routine.
HASHLEN	Input	(Required) The hash length in bits: 160 (SHA-1) 224 (SHA-224) 256 (SHA-256) 384 (SHA-384) 512 (SHA-512)

LSHAN

This extrinsic function returns the SHA hash of a
message that is too long to be passed as a single string. The message is
passed in ^TMP($J,MSUB).  The message should be broken into blocks that are
exactly 64 bytes/characters long except for the last one. ^TMP($J,MSG,N) is
the Nth block of the message, where N runs from 1 to NBLOCKS.

Format:  $$LSHAN^XLFSHAN(HASHLEN,MSUB,NBLOCKS)

The value returned is the SHA hash of the message.

VARIABLES

TYPE

VARIABLES DESCRIPTION

MSUB

Input

(Required) The ^TMP($J,MSUB) subscript in which the
message is passed.

NBLOCKS

Input

(Required) The number of blocks in the message.

HASHLEN

Input

(Required) The hash length in bits:
160 (SHA-1)
224 (SHA-224)
256 (SHA-256)
384 (SHA-384)
512 (SHA-512)

SHAN

This extrinsic function returns the SHA hash of a
message that can be passed in a single string.

Format:  $$SHAN^XLFSHAN(HASHLEN,MESSAGE)

The value returned is the SHA hash of the message.

VARIABLES	TYPE	VARIABLES DESCRIPTION
MESSAGE	Input	(Required) The message string.
HASHLEN	Input	(Required) The hash length in bits: 160 (SHA-1) 224 (SHA-224) 256 (SHA-256) 384 (SHA-384) 512 (SHA-512)

AND

Bitwise logical AND of two 32 bit integers.

Format:  $$AND^XLFSHAN(X,Y)

The value returned is the bitwise logical AND.

VARIABLES	TYPE	VARIABLES DESCRIPTION
X	Input	(Required) An integer of 32 bits or less.
Y	Input	(Required) An integer of 32 bits or less.

XOR

Bitwise logical XOR of two 32 bit integers.

Format:  $$XOR^XLFSHAN(X,Y)

The value returned is the bitwise logical XOR.

VARIABLES	TYPE	VARIABLES DESCRIPTION
X	Input	(Required) An integer of 32 bits or less.
Y	Input	(Required) An integer of 32 bits or less.

Bitwise logical OR of two 32 bit integers.

Format:  $$OR^XLFSHAN(X,Y)

The value returned is the bitwise logical OR.

VARIABLES	TYPE	VARIABLES DESCRIPTION
X	Input	(Required) An integer of 32 bits or less.
Y	Input	(Required) An integer of 32 bits or less.

GLOBAL

This extrinsic function returns the SHA-256 hash of
the specified global, in contrast with $$FILE which returns the hash for a
particular entry in a global.

Format:  $$GLOBAL^XLFSHAN(HASHLEN,FILENUM,DATAONLY)

Using file #5, this is what a portion of the text for which the hash is
computed looks like:

DATAONLY=0
^DIC(5,110,0)=YUKON TERRITORY^YT^83^^1^0
^DIC(5,110,1,0)=^5.01I^1^1
^DIC(5,110,1,1,0)=YUKON TERRITORY^^260
^DIC(5,110,1,"B","YUKON TERRITORY",1)=
^DIC(5,110,1,"C",260,1)=

DATAONLY=1
YUKON TERRITORY^YT^83^^1^0
^5.01I^1^1
YUKON TERRITORY^^260

The value returned is the SHA hash if successful, or "0" if the global does
not exist.

VARIABLES

TYPE

VARIABLES DESCRIPTION

FILENUM

Input

(Required) File number.

DATAONLY

Input

(Required) Scope of the hash.
0 - the global location of the data is to
be included in the hash computation.
1 - the hash is computed only for the data.

HASHLEN

Input

(Required) The hash length in bits:
160 (SHA-1)
224 (SHA-224)
256 (SHA-256)
384 (SHA-384)
512 (SHA-512)

CPUTIME

This extrinsic function returns two comma-delimited
pieces, "system" CPU time and "user" CPU time (except of VMS where no separate
times are available).

Format: $$CPUTIME^XLFSHAN()

The value returned is time measured as milliseconds of CPU time.

ETIMEMS

Calculates the elapsed time in milliseconds.

Format:  $$ETIMEMS^XLFSHAN(START,END)

Returns the elapsed time in milliseconds.

VARIABLES	TYPE	VARIABLES DESCRIPTION
START	Input	(Required) The starting CPU time, set by calling $$CPUTIME.
END	Input	(Required) The ending CPU time, set by calling $$CPUTIME.

GENAREF

This extrinsic function returns the SHA hash for a
general array or global.

Format:  $$GENAREF^XLFSHAN(HASHLEN,AREF,DATAONLY)

The value returned is the SHA hash of the array or global.

VARIABLES

TYPE

VARIABLES DESCRIPTION

HASHLEN

Input

(Required) The hash length in bits:
160 (SHA-1)
224 (SHA-224)
256 (SHA-256)
384 (SHA-384)
512 (SHA-512)

AREF

Input

(Required) The starting array reference, for example
ABC or ^TMP($J,"XX").

DATAONLY

Input

(Required) Scope of the hash.
0 - the array location of the data is to
be included in the hash computation.
1 - the hash is computed only for the data.

DATE ACTIVATED

2017/12/19