[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

HP OpenVMS Utility Routines Manual


Previous Contents Index


ENCRYPT$GENERATE_KEY

Generates a random key value.

Format

ENCRYPT$GENERATE_KEY algorithm-name, key-length [,factor-a] [,factor-b] [,factor-c] [,key buffer]


Arguments

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.


Description

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.

Condition Values Returned

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.

ENCRYPT$INIT

Initializes the context for the encryption operation.

Format

ENCRYPT$INIT context, algorithm, key-type, key-name [,p1]


Arguments

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
    AESOFB256

key-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.


Description

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.


Condition Values Returned

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.

ENCRYPT$STATISTICS

Gains access to the statistics maintained by the encryption software.

Format

ENCRYPT$STATISTICS context, code, destination, return-length


Arguments

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.

Description

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.

Condition Values Returned

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.


Chapter 12
File Definition Language (FDL) Routines

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:

  • Specify file characteristics otherwise unavailable from your language.
  • Examine or modify the file characteristics of an existing data file to improve program or system interaction with that file.

12.1 Introduction to FDL Routines

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.

  • The FDL$GENERATE routine produces an FDL specification by interpreting a set of RMS control blocks in an existing data file. It then writes the FDL specification either to an FDL file or to a character string. If your programming language does not provide language statements that access RMS control blocks (for example, HP Fortran), you must use FDL$GENERATE from within the context of a user-open routine to generate an FDL file.
  • The FDL$PARSE routine parses an FDL specification, allocates RMS control blocks, and fills in the relevant fields.
  • The FDL$RELEASE routine deallocates the virtual memory used by the RMS control blocks created by FDL$PARSE.

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 shows how to use the FDL$CREATE routine in a Fortran program.
  • Example 12-2 shows how to use the FDL$PARSE and FDL$RELEASE routines in a C program.
  • 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. The program then uses the FDL$GENERATE routine to create an FDL file using the information in the control blocks.

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 shows how to use the FDL$PARSE and FDL$RELEASE routines in a C program.

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