| Previous | Contents | Index |
Generates a random key value.
ENCRYPT$GENERATE_KEY algorithm-name, key-length [,factor-a] [,factor-b] [,factor-c] [,key buffer]
algorithm-name
VMS usage: type: char_string access: read only mechanism: by descriptor
The name of the algorithm that uses the generated key.key-length
VMS usage: type: word unsigned access: read only mechanism: by reference
Unsigned integer indicating the size of the key to be generated. The key-length argument is the address of an unsigned word containing a value that indicates the length of the key.For AES, the key-length argument takes values as increments of AES block size: 16 bytes, 32, bytes, and 48 bytes, and so on.
factor-a, factor-b, factor-c
VMS usage: type: char_string access: read only mechanism: by descriptor
Optional arguments. The factor-a, factor-b, and factor-c arguments are operation-dependent data used as randomizing factors when the routine generates a key value. For example, the factors might include:
- Time an operation started
- Size of a certain stack
- Copy of the last command line
key-buffer
VMS usage: type: char_string access: write mechanism: by descriptor
Buffer into which the generated key is to be placed. The key-buffer argument is the address of a string descriptor referencing the appropriate buffer.If you specify a class D descriptor, dynamic memory is allocated to contain the entire key.
The ENCRYPT$GENERATE_KEY routine generates a random key value. The ENCRYPT$GENERATE_KEY routine returns a 32-bit status code indicating the success or failure of the routine's operation.
SS$_NORMAL Key has been created. ENCRYPT$ xyz An error reported by the Encryption software. The xyz portion identifies the message. SS$_ xyz A return status from a called system service. The xyz portion identifies the return status.
Initializes the context for the encryption operation.
ENCRYPT$INIT context, algorithm, key-type, key-name [,p1]
context
VMS usage: type: longword integer signed access: write only mechanism: by reference
Context area that is initialized. The context argument is the address of a longword of unspecified interpretation that is used to convey context between encryption operations. An uninitialized context longword is defined to be zero and is initialized to nonzero by this routine. The context area itself is allocated from process dynamic memory.algorithm
VMS usage: type: char_string access: read/write mechanism: by descriptor
Algorithm used for the encryption operation. The algorithm argument is the address of a string descriptor pointing to a code for the selected algorithm. The algorithm code is an ASCII string. For descriptor type value, use one of the following:DSC$K_DTYPE_T (text)
DSC$K_DTYPE_VT (varying text)
DSC$K_DTYPE_Z (unspecified)For DES, the following algorithms are valid:
- DESCBC (default)
- DESECB
- DESCFB
For AES, the following algorithms are valid:
- Cipher block chaining:
AESCBC128 (default)
AESCBC192
AESCBC256- Electronic code book:
AESECB128
AESECB192
AESECB256
- Cipher feedback:
AESCFB128
AESCFB192
AESCFB256- Output feedback:
AESOFB128
AESOFB192
AESOFB256key-type
VMS usage: type: longword logical unsigned access: read only mechanism: by reference
Code specifying how ENCRYPT$INIT is to interpret the key-name argument. The key-type argument is the address of an unsigned longword indicating whether key-name is the name of the key or the key value. If you specify:
Key-type as 0 ENCRYPT$INIT interprets key-name as a descriptor pointing to the key name string. Key-type as 1 ENCRYPT$INIT interprets key-name as the descriptor for the value of the key to be used. key-name
VMS usage: type: char_string access: read only mechanism: by descriptor
Key that ENCRYPT$INIT passes to the selected encryption routine. The key-name argument is the address of a character string descriptor containing the name of the key or the address of the actual key value. ENCRYPT$INIT interprets this argument based on the key-type value. Argument options:
The key name Actual key value is retrieved from key storage by the selected encryption routine. A key value It is stored with a temporary name, which is passed to the selected encryption routine. If the key-name argument is used to specify a key value (that is, if key-type has been specified as 1), the key-name string-descriptor type field determines whether the key value is to be treated as a char_string key or as a binary value to be used exactly as specified.
If the descriptor type is DSC$K_DTYPE_T (char_string), DSC$K_DTYPE_VT (varying char_string), or DSC$K_DTYPE_Z (unspecified), the value is treated as a text string to be compressed for DES key values. ASCII compression converts lowercase characters to uppercase; only the characters A--Z, 0--9, dollar sign ($), period (.), and underscore (_) are allowed. Other characters are converted to spaces, and the extra spaces are removed. AES ASCII key values are not subject to ASCII compression, allowing any 8-bit ASCII character.
All other descriptor types are treated as though the key value is to be used exactly as specified.
Note
The key name descriptors of type DSC$K_DTYPE_T, DSC$K_DTYPE_VT, and DSC$K_DTYPE_Z all specify that the key value should be compressed. For OpenVMS Version 8.3, this functionality applies only to DES, not to AES. AES keys are not compressed.p1
VMS usage: type: quadword[1] (DES), quadword[2] (AES) access: read only mechanism: by reference
Optional argument. The p1 argument is the address of a quadword initialization vector used to seed the three modes of the DES algorithm that uses an initialization vector. These modes are DESCBC (default), DESCFB, and DESMAC; that is, the DES IV initialization vector is a quadword reference to an 8-byte value.For AES, the optional p1 argument for the AES IV initialization vector is a reference to a 16-byte (2 quadword) value.
If you omit this argument, the initialization vector used is the residue of the previous use of the specified context block. ENCRYPT$INIT initializes the context block with an initialization vector of zero.
ENCRYPT$INIT initializes the context for the encryption operation. ENCRYPT$INIT creates preinitialized key tables in the context area to speed the encryption or decryption process. Before you can reuse a context with a new algorithm, key, or other values specified with ENCRYPT$INIT, terminate the old context with a call to ENCRYPT$FINI.
Note
Always initialize the context with ENCRYPT$INIT when you change the operation from encryption to decryption or from decryption to encryption.ENCRYPT$INIT returns a 32-bit status code indicating the success or failure of the routine's operation.
SS$_NORMAL Initialization successfully completed. ENCRYPT$ xyz An error reported by the Encryption software. The xyz portion identifies the message. SS$_ xyz A return status from a called system service. The xyz portion identifies the return status.
Gains access to the statistics maintained by the encryption software.
ENCRYPT$STATISTICS context, code, destination, return-length
context
VMS usage: type: longword access: read only mechanism: by reference
Context area initialized by ENCRYPT$INIT. The context argument is the address of a longword initialized by the ENCRYPT$INIT routine.code
VMS usage: type: longword access: read only mechanism: by reference
Code specifying the desired statistic. The code argument is the address of a longword containing the code. The only accepted value is 1, which indicates that ENCRYPT$STATISTICS is to return all statistics to the destination buffer.destination
VMS usage: type: char_string access: write only mechanism: by descriptor
Buffer into which ENCRYPT$STATISTICS places the statistics. The destination argument is the address of a string descriptor describing the buffer. Ensure that the destination buffer is at least 20 bytes long and contains:
- One longword indicating the number of times the primitive has been entered referencing this encryption stream
- One quadword indicating the total bytes processed for this stream
- One quadword indicating the total CPU time, in OpenVMS time format, spent on processing requests for this stream
return-length
VMS usage: type: longword access: write only mechanism: by reference
Number of bytes written to the destination buffer. The return-length argument is the address of a word containing the number of bytes.
To track the progress and performance of an encryption operation, the encryption software maintains statistics in the context area. You can access these statistics with the ENCRYPT$STATISTICS routine. The ENCRYPT$STATISTICS routine returns a 32-bit status code indicating the success or failure of the routine's operation.
SS$_NORMAL Statistics returned. ENCRYPT$ xyz An error reported by the Encryption software. The xyz portion identifies the message. SS$_ xyz A return status from a called system service. The xyz portion identifies the return status.
This chapter describes the File Definition Language (FDL) routines. These routines perform many of the functions of the File Definition Language that define file characteristics. Typically, you use FDL to perform the following operations:
You specify FDL attributes for a data file when you use FDL to create the data file, set the desired file characteristics, and close the file. You can then use the appropriate language statement to reopen the file. Because the data file is closed between the time the FDL attributes are set and the time your program accesses the file, you cannot use FDL to specify run-time attributes (attributes that are ignored or deleted when the associated data file is closed).
The FDL$CREATE routine is the one most likely to be called from a high-level language. It creates a file from an FDL specification and then closes the file. The following HP Fortran program segment creates an empty data file named INCOME93.DAT using the file characteristics specified by the FDL file INCOME.FDL. The STATEMENT variable contains the number of the last FDL statement processed by FDL$CREATE; this argument is useful for debugging an FDL file.
INTEGER STATEMENT
INTEGER STATUS,
2 FDL$CREATE
STATUS = FDL$CREATE ('INCOME.FDL',
2 'INCOME93.DAT',
2 ,,,,
2 STATEMENT,
2 ,,)
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))
.
.
.
|
The following three FDL routines provide a way to specify all the options OpenVMS RMS allows when it executes create, open, or connect operations. They also allow you to specify special processing options required for your applications.
These routines cannot be called from asynchronous system trap (AST) level. In addition, in order to function properly, these routines require ASTs to remain enabled.
An FDL specification can be in either a file or a character string.
When specifying an FDL specification in a character string, use
semicolons to delimit the statements of the FDL specification.
12.2 Using the FDL Routines: Examples
This section provides examples that demonstrate the use of the FDL routines in various programming scenarios.
| Example 12-1 Using FDL$CREATE in a Fortran Program |
|---|
* This program calls the FDL$CREATE routine. It
* creates an indexed output file named NEW_MASTER.DAT
* from the specifications in the FDL file named
* INDEXED.FDL. You can also supply a default filename
* and a result name (that receives the name of the
* created file). The program also returns all the
* statistics.
*
IMPLICIT INTEGER*4 (A - Z)
EXTERNAL LIB$GET_LUN, FDL$CREATE
CHARACTER IN_FILE*11 /'INDEXED.FDL'/,
1 OUT_FILE*14 /'NEW_MASTER.DAT'/,
1 DEF_FILE*11 /'DEFAULT.FDL'/,
1 RES_FILE*50
INTEGER*4 FIDBLK(3) /0,0,0/
I = 1
STATUS = FDL$CREATE (IN_FILE,OUT_FILE,
DEF_FILE,RES_FILE,FIDBLK,,)
IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS))
STATUS=LIB$GET_LUN(LOG_UNIT)
OPEN (UNIT=LOG_UNIT,FILE=RES_FILE,STATUS='OLD')
CLOSE (UNIT=LOG_UNIT, STATUS='KEEP')
WRITE (6,1000) (RES_FILE)
WRITE (6,2000) (FIDBLK (I), I=1,3)
1000 FORMAT (1X,'The result filename is: ',A50)
2000 FORMAT (/1X,'FID-NUM: ',I5/,
1 1X,'FID-SEQ: ',I5/,
1 1X,'FID-RVN: ',I5)
END
|
| Example 12-2 Using FDL$PARSE and FDL$RELEASE in a C Program |
|---|
/* FDLEXAM.C
** This program calls the FDL utility routines FDL$PARSE and
** FDL$RELEASE. First, FDL$PARSE parses the FDL specification
** PART.FDL. Then the data file named in PART.FDL is accessed
** using the primary key. Last, the control blocks allocated
** by FDL$PARSE are released by FDL$RELEASE.
** Note; to try this program use the following command on any
** file with textual data: $ANALYZE/RMS/FDL/OUT=PART.FDL
*/
#include <descrip>
#include <rms>
#define REC_SIZE 80 /* as appropriate for files used */
FDLEXAM ()
{
struct FAB *fab_ptr; /* variable to hold pointer to FAB structure */
struct RAB *rab_ptr; /* variable to hold pointer to RAB structure */
$DESCRIPTOR (fdl_file, "PART.FDL"); /* free choice of name */
char record_buffer[REC_SIZE+1]; /* allow for null terminator */
int stat;
/*
** Read and parse FDL file allocating and initializing RAB and
** and FAB accordingly, returning pointers to the FAB & RAB.
*/
stat = FDL$PARSE ( &fdl_file, &fab_ptr, &rab_ptr );
if (!(stat & 1)) LIB$STOP ( stat );
/*
** Try to open file as described by information in the FAB.
** Signal open errors. Note the usage of STAT, instead of
** FAB_PTR->FAB$L_STS because just in case the FAB is invalid,
** the only status returned is STAT.
*/
stat = SYS$OPEN ( fab_ptr );
if (!(stat & 1)) LIB$STOP ( stat, fab_ptr->fab$l_stv );
stat = SYS$CONNECT ( rab_ptr );
if (!(stat & 1)) LIB$STOP ( stat, rab_ptr->rab$l_stv );
/*
** Opened the file and connect some internal buffers.
** Fill in the record output buffer information which is the only
** missing information in the RAB that was created for us by FDL.
** Print a header recod and perform the initial $GET.
*/
rab_ptr->rab$w_usz = REC_SIZE;
rab_ptr->rab$l_ubf = record_buffer;
printf ("------------------- start of records -------------- \n");
stat = SYS$GET ( rab_ptr );
while (stat & 1) /* As long as the $GET is successful */
{
record_buffer[rab_ptr->rab$w_rsz] = 0; /* Terminate for printf */
printf ("%s\n", record_buffer); /* Current record */
stat = SYS$GET ( rab_ptr ); /* Try to get next one */
}
/*
** At this point in the execution, the status should be EOF indicating
** Successfully read the file to end. If not, signal real error.
*/
if (stat != RMS$_EOF) LIB$STOP ( rab_ptr->rab$l_sts, rab_ptr->rab$l_stv );
printf ("-------------------- end of records --------------- \n");
stat = SYS$CLOSE ( fab_ptr ); /* implicit $DISCONNECT */
if (!(stat & 1)) LIB$STOP ( fab_ptr->fab$l_sts, fab_ptr->fab$l_stv );
/*
** Allow FDL to release the FAB and RAB structures and any other
** structures (XAB) that it allocated on behalf of the program.
** Return with its status as final status (success or failure).
*/
return FDL$RELEASE ( &fab_ptr, &rab_ptr );
}
|
Example 12-3 shows a HP Pascal program that uses the FDL$PARSE routine to fill in the RMS control blocks in a data file, and then uses the FDL$GENERATE routine to create an FDL file.
| Example 12-3 Using FDL$PARSE and FDL$GENERATE in a HP Pascal Program |
|---|
[INHERIT ('SYS$LIBRARY:STARLET')]
PROGRAM FDLexample (input,output,order_master);
(* This program fills in its own FAB, RAB, and *)
(* XABs by calling FDL$PARSE and then generates *)
(* an FDL specification describing them. *)
(* It requires an existing input FDL file *)
(* (TESTING.FDL) for FDL$PARSE to parse. *)
TYPE
(*+ *)
(* FDL CALL INTERFACE CONTROL FLAGS *)
(*- *)
$BIT1 = [BIT(1),UNSAFE] BOOLEAN;
FDL2$TYPE = RECORD CASE INTEGER OF
1: (FDL$_FDLDEF_BITS : [BYTE(1)] RECORD END;
);
2: (FDL$V_SIGNAL : [POS(0)] $BIT1;
(* Signal errors; don't return *)
FDL$V_FDL_STRING : [POS(1)] $BIT1;
(* Main FDL spec is a char string *)
FDL$V_DEFAULT_STRING : [POS(2)] $BIT1;
(* Default FDL spec is a char string *)
FDL$V_FULL_OUTPUT : [POS(3)] $BIT1;
(* Produce a complete FDL spec *)
FDL$V_$CALLBACK : [POS(4)] $BIT1;
(* Used by EDIT/FDL on input (DEC only) *)
)
END;
mail_order = RECORD
order_num : [KEY(0)] INTEGER;
name : PACKED ARRAY[1..20] OF CHAR;
address : PACKED ARRAY[1..20] OF CHAR;
city : PACKED ARRAY[1..19] OF CHAR;
state : PACKED ARRAY[1..2] OF CHAR;
zip_code : [KEY(1)] PACKED ARRAY[1..5]
OF CHAR;
item_num : [KEY(2)] INTEGER;
shipping : REAL;
END;
order_file = [UNSAFE] FILE OF mail_order;
ptr_to_FAB = ^FAB$TYPE;
ptr_to_RAB = ^RAB$TYPE;
byte = 0..255;
VAR
order_master : order_file;
flags : FDL2$TYPE;
order_rec : mail_order;
temp_FAB : ptr_to_FAB;
temp_RAB : ptr_to_RAB;
status : integer;
FUNCTION FDL$PARSE
(%STDESCR FDL_FILE : PACKED ARRAY [L..U:INTEGER]
OF CHAR;
VAR FAB_PTR : PTR_TO_FAB;
VAR RAB_PTR : PTR_TO_RAB) : INTEGER; EXTERN;
FUNCTION FDL$GENERATE
(%REF FLAGS : FDL2$TYPE;
FAB_PTR : PTR_TO_FAB;
RAB_PTR : PTR_TO_RAB;
%STDESCR FDL_FILE_DST : PACKED ARRAY [L..U:INTEGER]
OF CHAR) : INTEGER;
EXTERN;
BEGIN
status := FDL$PARSE ('TESTING',TEMP_FAB,TEMP_RAB);
flags::byte := 0;
status := FDL$GENERATE (flags,
temp_FAB,
temp_RAB,
'SYS$OUTPUT:');
END.
|
| Previous | Next | Contents | Index |