| Previous | Contents | Index |
This chapter describes how to access LJK/Security from programs you have written in VMS programming languages.
As used below, names of the form LJK$SECURITY_*_xxx.EXE stand for
both LJK$SECURITY_*_AXP.EXE and
LJK$SECURITY_*_VAX.EXE.
9.1 Master Node Invocation Entrypoints
These entrypoints to the shareable image LJK$SECURITY_SHARE_xxx.EXE are used to invoke LJK/Security from a user program on the master node. Their use on a tributary node is not supported.
By calling these entrypoints, a user program effectively replaces the small program LJK$SECURITY_xxx.EXE which is normally used to process the command LJK/SECURITY.
In order to call these entrypoints, a user program must be linked against the shareable image SYS$LIBRARY:LJK$SECURITY_SHARE or it must invoke the entrypoints within that image by using the VMS function LIB$FIND_IMAGE_SYMBOL.
For successful invocation of anything other than a parsing function, certain privileges are required:
These entrypoints are used to parse LJK/Security commands in
preparation for subsequent execution. If one of them is called without
a subsequent call to the execution entrypoint, it serves to
"test"
the command for legality.
9.1.1.1 LJK$SECURITY_PARSE_DCL entry
This entrypoint takes a single parameter which is a string descriptor
of the command to be parsed. It returns status in R0.
9.1.1.2 LJK$SECURITY_PARSE_CLI entry
This entrypoint takes no parameters, but parses the command which was
used to invoke the program. It returns status in R0.
9.1.1.3 LJK$SECURITY_PARSE_FOREIGN entry
This entrypoint takes no parameters, but parses a foreign command
which was used to invoke the program. It returns status in R0.
9.1.2 Execution Entrypoint
9.1.2.1 LJK$SECURITY_EXECUTE entry
This entrypoint takes no parameters, but relies on values previously
determined from a call to a parsing entrypoint. It returns status in R0.
Note that the call to a parsing routine above may produce results which cause multiple subsequent commands to be parsed within the call to the execution entrypoint. Cases where this happen include:
When provided by the customer, this callback is used by LJK/Security to invoke customer-provided software as part of the assessment process.
9.2.1 Linking of Customer-Provided Software
Customer-provided software should be linked into a shareable image
named LJK$SECURITY_SITE_SHARE_xxx.EXE. The linking should be done on
the oldest version of VMS
on which LJK/Security is to be run. The link should be done without
traceback symbols, so that the shareable image can be called by an
image installed with privilege (LJK$SECURITY_xxx.EXE).
There is no requirement that LJK/Security be on the node where the link is performed. |
The entrypoint LJK$SECURITY_SITE_CHECKSUM should be declared as a universal symbol so that it can be accessed from outside the image. Example link commands are:
$ LINK/NOTRACE/SHAREABLE=LJK$SECURITY_SITE_SHARE_xxx.EXE -
MY_CODE,SYS$INPUT:/OPTION
SYMBOL_VECTOR=(LJK$SECURITY_SITE_CHECKSUM=PROCEDURE)
|
$ LINK/NOTRACE/SHAREABLE=LJK$SECURITY_SITE_SHARE_VAX.EXE -
MY_CODE,SYS$INPUT:/OPTION
UNIVERSAL=LJK$SECURITY_SITE_CHECKSUM
|
9.2.2 Distribution of Customer-Provided Software
If the image LJK$SECURITY_SITE_SHARE_xxx.EXE is stored in the
directory SYS$COMMON:[SYSLIB] on the master node, then
it will be automatically included by LJK/Security in software
distributed to tributary nodes. In the distribution
process, the protection will be changed to at least allow Execute
access to World.
9.2.3 LJK$SECURITY_SITE_CHECKSUM callback
This entrypoint is called successively during the process of
checksumming a file. Before each call, a succeeding segment of the file
is mapped into the address space of the process (although the segment
mapped on the final call may be null) and thus is available to be read
by the site routine.
9.2.3.1 Specialized use of the Limit
The limit for the test DISK, CHECKSUM, SITE is not
actually a limit in the general sense of
LJK/Security, but rather is used to store any Initialization Vector
required by the site checksum routine. The Initialization Vector is
specified as a hexadecimal string whose length is an even number of
0-254 characters, and is delivered to the site checksum routine as the
corresponding binary array whose length is 0-127 bytes.
9.2.3.2 Specialized use of Exemptions
Exemptions for the test DISK, CHECKSUM, SITE contain:
The desired Checksum value is specifed as a hexadecimal string whose
length is an even number of 0-254 characters, and is compared to the
checksum provided by the site checksum routine to the callback routine
(as the corresponding binary array whose length is 0-127 bytes) after
processing the final segment.
9.3 Detailed Entrypoint Descriptions
Parse the LJK/SECURITY command that is passed as a parameter, storing the results for a subsequent call.
status =LJK$SECURITY_PARSE_DCL (command)
VMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
command
VMS usage: char_string type: character string access: read only mechanism: by descriptor
The command which is to be parsed. It must start with the string "LJK/SECURITY " (ending in a space).
This entrypoint takes a single parameter which is a string descriptor of the command to be parsed. It returns status in R0.
Parse the LJK/SECURITY command that was used to invoke the program, storing the results for a subsequent call.
status=LJK$SECURITY_PARSE_CLI
VMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
None.
This entrypoint takes no parameters, but parses the command which was used to invoke the program. It returns status in R0.
Parse the LJK/SECURITY command that was used to invoke the program as a foreign command, storing the results for a subsequent call.
status=LJK$SECURITY_PARSE_FOREIGN
VMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
None.
This entrypoint takes no parameters, but parses a foreign command which was used to invoke the program. It returns status in R0.
Execute the command whose parse results were stored by a previous call.
status=LJK$SECURITY_EXECUTE
VMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
None.
This entrypoint takes no parameters, but relies on values previously determined from a call to a parsing entrypoint. It returns status in R0.Note that the call to a parsing routine above may produce results which cause multiple subsequent commands to be parsed within the call to the execution entrypoint. Cases where this happen include:
Perform a checksum using a customer-implemented algorithm, for instance to use a different algorithm than those supplied with LJK/Security or to use a different implementation of an algorithm also supplied with LJK/Security because that implementation has been approved by some higher authority.
status =LJK$SECURITY_SITE_CHECKSUM (data_address, data_length, initialization_vector, context, callback)
VMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
data_address
VMS usage: vector_byte_unsigned type: byte array access: read only mechanism: by reference
The address of the current segment to be included in the checksum.data_length
VMS usage: longword_unsigned type: unsigned longword access: read only mechanism: by reference
The number of bytes in the current segment to be included in the checksum.initialization_vector
VMS usage: vector_byte_unsigned type: byte array access: read only mechanism: by descriptor
A fixed length string descriptor of the initialization vector supplied as the limit in the LJK/Security policy. By default, policies contain a zero length string.context
VMS usage: longword_unsigned type: unsigned longword access: read-write mechanism: by reference
The address of a longword of unspecified purpose for use by the customer-provided checksum routine. One typical use is to store in this longword the address of a segment of allocated memory used for maintaining algorithm context. On the first call for a particular file, this longword contains zero. On subsequent calls, the contents of this longword (as left by the previous call) are preserved. On return from the last call for a particular file, this longword should again be changed back to zero, indicating that memory has been properly deallocated.callback
VMS usage: entry_mask type: entry mask access: read only mechanism: by reference
The address of the entry mask of a routine to be called after processing the last segment. The presence of this address indicates the last segment. On segments other than the final segment, this address is zero.
This subroutine will be called multiple times for each file to be processed, with the last call specifying a data length of zero. On short files, therefore, only two calls will be made, where the demarcation size between short files and long files is based on the amount of free virtual address space.The call made by a customer checksum routine to the entry specified by the CALLBACK parameter should provide the following parameters:
- CHECKSUM
A string descriptor of the checksum computed by the customer checksum routine. This checksum will be compared against the value of the exemption for the specified file, and a violation will be reported if the two values differ, either in length or content.If entrypoint LJK$SECURITY_SITE_CHECKSUM returns status (R0, as specifed in the VMS calling standard) which is other than success (low order three bits containing other than the value 1), that status will be returned to the master node and reported as a processing failure by LJK/Security.
This chapter describes the differences involved in using magnetic tape or removable disks rather than DECnet for communication between the master node and tributary nodes.
A special case DECnet alternative for those who have TCP/IP
connectivity but are forbidden to run DECnet is described in
Appendix N, Sending LJK/Security Data Directly over TCP/IP.
10.1 Reasons
Although using magnetic tape or removable disks to carry LJK/Security information between the master node and the tributary nodes generally requires more human effort than using DECnet, there are two principal reasons why one might choose removable media instead of DECnet:
Using removable media for transport between a master node and that same node as tributary node does not particularly add to security. The best that can be said for it is that it gives practice in using the removable media for transport! |
There are three types of LJK/Security communication between the master node and the tributary node:
The choice of medium is made independently for each type for each tributary node, so choosing a removable medium in one case does not prevent DECnet from being used in another.To minimize the complication introduced by installation of LJK/Security, the installation on tributary nodes has been kept very simple. The only information which must be supplied by the person installing the software on the tributary node pertains to the UIC code used for storing LJK/Security files. This is intended to ease the task of VMS system managers at tributary nodes who are likely to have other tasks assigned to them with higher priority than security. For Software Installation, the use of removable media provides a very familiar environment for the individual doing the installation (so long as the medium used is the same one used for other software installations).
Using magnetic tape as an example, the LJK/Security on the master node would use the LJK/SECURITY KIT_BUILD command to write a tributary node software kit onto magtape. After the magtape is transported to the tributary node, it is installed like any other piece of software, using the standard VMSINSTAL command procedure:
$ @SYS$UPDATE:VMSINSTAL * ddcu: |
Unlike the transmission types below, a single copy of the LJK/Security
tributary node software is sufficient; it can be
installed on multiple tributary nodes in succession.
10.3 Request Transmission
For request transmission, when the LJK/SECURITY RUN command is issued (or when it comes due following the use of /AFTER or /INTERVAL command) on the master node, LJK/Security will issue a MOUNT request to write each request onto its specified medium. (Be sure to have at least one terminal enabled as an operator terminal for the appropriate medium (disk or tape) using the VMS command REPLY/ENABLE, or transmission of the request will be delayed.
In cases where the MOUNT request specifies one tape drive and the operator prefers to use another tape drive of the same type, LJK/Security will honor the "SUBSTITUTE" argument to the REPLY command. If tape drive MUA2: should be used instead of the requested drive (due to hardware problems, for example) the operator could issue the command:
REPLY/TO=37429 "SUBSTITUTE MUA2" |
After the medium has been transported to the tributary node, any user with the the facility-specific identifier 1 LJK$SECURITY_ROLE_STARTUP or LJK$SECURITY_REMOTE can issue the command:
$ SUBMIT SYS$SYSTEM:LJK$SECURITY/PARAMETER=ddcu: |
1 On systems prior to VAX VMS V6.0 or systems which do not have a Rights Database (RIGHTSLIST.DAT), you must have the SECURITY privilege. |
| Previous | Next | Contents | Index |