HELPLIB.HLB  —  ENCRYPT Routine
    The encryption routines (APIs) allow you to program encryption
    operations into applications. OpenVMS Version 8.3 Integrity
    servers and Alpha systems support the Advanced Encryption
    Standard (AES) algorithm, which allows any OpenVMS user,
    system manager, security manager, or programmer to secure their
    files, save sets, or application data with AES Encryption. The
    former DES algorithm is also supported for complete backward
    compatibility. This allows updating archived data encrypted with
    DES to the more secure AES encryption algorithm.

                                   NOTE

       To access help subtopics, be sure to enter a unique string.
       For example, ENCRYPT$ENCRYPT_r.

1  –  Introduction

    Encryption provides the following routines, listed by function:

    o  Defining, generating, and deleting keys:

       -  ENCRYPT$DEFINE_KEY

       -  ENCRYPT$GENERATE_KEY

       -  ENCRYPT$DELETE_KEY

    o  Encrypting and decrypting files:

       -  ENCRYPT$ENCRYPT_routine

       -  ENCRYPT$ENCRYPT_FILE

       -  ENCRYPT$DECRYPT_routine

    o  Encrypting and decrypting records:

       -  ENCRYPT$DECRYPT_ONE_RECORD

       -  ENCRYPT$ENCRYPT_ONE_RECORD

    o  Intializing and terminating the context area:

       -  ENCRYPT$INIT

       -  ENCRYPT$FINI

    o  Returning statistics:

       -  ENCRYPT$STATISTICS

2  –  AES Features

    AES encryption, like DES, is a symmetric block cipher. However,
    its algorithm is very different, its key scheduling and number of
    rounds is based on key size (10, 12, or 14 rounds for 128, 192,
    and 256 bit keys), making AES much stronger cryptographically.
    AES features allows any user, system manager, security manager,
    or programmer to secure their files, save-sets, or application
    data with strong AES Encryption. It is integrated with OpenVMS
    Version 8.3 and does not require a separate product license or
    installation.

    Encrypt-AES provides the following features and compatibility:

    o  The former data encryption standard (DES) algorithm is
       maintained for use with existing DES data and their
       applications. All the functions that existed with DES continue
       to provide that same level of DES support.

    o  Encrypt-AES is integrated with BACKUP for encrypting and
       decrypting save sets with AES or DES.

    o  Command-line use of Encrypt-AES is the same as Encrypt-DES,
       with minor changes to qualifiers (see the encryption routines
       below).

    o  Changes to the ENCRYPT$ application programming interface
       (API) are minimal, with only textual parameter or flag changes
       required to use the AES algorithm.

    o  Encrypt-AES supports the AES algorithm with four different
       cipher modes. With each mode, you can specify a secret key in
       three different lengths (128, 192, and 256 bits), for a total
       of 12 different cipher and decipher operations:

       o  Cipher block chaining:

             AESCBC128
             AESCBC192
             AESCBC256

       o  Electronic code book:

             AESECB128
             AESECB192
             AESECB256

       o  Cipher feedback:

             AESCFB128
             AESCFB192
             AESCFB256

       o  Output feedback:

             AESOFB128
             AESOFB192
             AESOFB256

    o  The additional AES algorithm, modes, and key sizes are
       specified in the algorithm parameter to the ENCRYPT$ENCRYPT_
       FILE and the ENCRYPT$INIT routine, or specified in the
       algorithm-name parameter for the ENCRYPT$GENERATE_KEY routine.

    o  AES Key-Length Requirements- The AES key requirements are
       the actual number of bits utilized for each of the AES modes.
       This is actually the minimum number of bytes needed for the
       encryption or decryption operation. The minimum required key
       sizes are as follows:

       -  128 bit mode = 16 byte key

       -  192 bit mode = 24 byte key

       -  256 bit mode = 32 byte key

3  –  ENCRYPT$DECRYPT routine

    Decrypts the next record of ciphertext according to the algorithm
    specified in the ENCRYPT$INIT call.

    Format

      ENCRYPT$DECRYPT  context, input, output [,output-length] [,p1]

3.1  –  Arguments

 context

    type:      longword integer (signed)
    access:    write only
    mechanism: by reference
    Context area initialized when ENCRYPT$INIT completes execution.
    The context argument is the address of a longword of unspecified
    interpretation that is used to convey context between encryption
    operations.

 input

    type:      char_string
    access:    read only
    mechanism: by descriptor
    Ciphertext record that ENCRYPT$DECRYPT is to decrypt. The input
    argument is the address of a descriptor pointing to a byte-
    aligned buffer containing the input record to the decryption
    operation.

 output

    type:      char_string
    access:    write only
    mechanism: by descriptor
    Plaintext record that results when ENCRYPT$DECRYPT completes
    execution. The output argument is the address of a descriptor
    pointing to a byte-aligned padding buffer that will contain the
    output record from the decryption operation.

    If the descriptor is dynamic and insufficient space is allocated
    to contain the output record, storage will be allocated from
    dynamic memory. If insufficient space exists to contain the
    output of the operation, then an error status is returned.

    The ENCRYPT$DECRYPT routine adjusts the length of the output
    descriptor, if possible, to reflect the actual length of the
    output string. If the descriptor type is not DSC$K_DTYPE_VS
    (varying string), DSC$K_DTYPE_V (varying), or DSC$K_DTYPE_D
    (dynamic), the routine takes the actual output count from the
    output-length argument.

    The output buffer must be able to accommodate a padded block to
    an increment of the block length. For AES this is 16 bytes and
    for DES, eight bytes.

 output-length

    type:      word integer
    access:    write only
    mechanism: by reference
    Optional argument.

    Number of bytes that ENCRYPT$DECRYPT wrote to the output buffer.
    The output-length argument is the address of a word containing
    the number of bytes written to the output buffer, including any
    bytes of pad characters generated by the selected algorithm to
    meet length requirements of the input buffer, if any. Output
    length does not count padding in the case of a fixed-length
    string.

    Some encryption algorithms have specific requirements for the
    length of the input and output strings. In particular, DESECB
    and DESCBC pad input data with from 1 to 7 bytes to form complete
    64-bit blocks for operation. The values of the pad characters are
    indeterminate.

    When you decrypt fewer than 8 bytes, present the full 8 bytes
    resulting from the ENCRYPT$ENCRYPT to ENCRYPT$DECRYPT. Retain the
    byte count of the input data in order to strip trailing pad bytes
    after a subsequent decryption operation. Note that the AES block
    mode algorithms (AESCBCxxx and AESECBxxx), pad the data to even
    16 byte block boundaries. For AES, one byte encrypts and decrypts
    to 16 bytes, 72 bytes to 80, and so forth. The AES padding
    character is a HEX number of bytes indicating the number of bytes
    padded, for example, the one byte encrypted pad would decrypt to
    15 characters of 0F following the one decrypted byte of data. For
    the 72 bytes of data, eight bytes of padding characters (08 08
    ... 08), would follow the 72 bytes of decrypted data. DESECB and
    DESCBC modes always pad with characters of zeros. The character
    stream modes (AESCFBxxx, AESOFBxxx, DESCFB), do not pad the data,
    so the output-length will match the actual number of data bytes.

 p1

    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 two modes of the DES
    algorithm for which it is applicable (DESECB and DESCFB). (That
    is, the DES IV initialization vector is a quadword reference, to
    an eight byte value.)

    For AES, the optional P1 argument for the AES IV initialization
    vector is a reference to a 16 byte (two quadwords) value.

    If this argument is omitted, 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.

4  –  ENCRYPT$DECRYPT_ONE_RECORD

    Decrypts a small amount of data on a decrypt stream.

                                   NOTE

       To use AES for one record ciphers, you must first create
       an AES key, which is stored in the logical name table
       (encrypted). The key name of an AES key is specified as
       an address of a descriptor that contains the ASCII text for
       the selected AESmmmkkk (mode and key size) algorithm, for
       example, AESCBC256. The input and output buffers (descriptor
       addresses) are also provided.

    Format

      ENCRYPT$DECRYPT_ONE_RECORD  input, output, key-name, algorithm

4.1  –  Arguments

 input

    type:      char_string
    access:    read only
    mechanism: by descriptor
    Ciphertext record to be decrypted. The input argument is the
    address of a string descriptor pointing to a byte-aligned buffer
    containing the input record to be decrypted.

 output

    type:      char_string
    access:    write only
    mechanism: by descriptor
    Plaintext record resulting when ENCRYPT$DECRYPT_ONE_RECORD
    completes execution. The output argument is the address of a
    string descriptor pointing to a byte-aligned buffer that will
    contain the plaintext record.

    If the descriptor is dynamic and insufficient space is allocated
    to contain the output record, storage is allocated from dynamic
    memory. If insufficient space exists to contain the output of the
    operation, an error is returned.

    The ENCRYPT$DECRYPT_ONE_RECORD routine adjusts the length of the
    output descriptor, if possible, to reflect the actual length of
    the output string.

 key-name

    type:      char_string
    access:    read only
    mechanism: by descriptor
    Key used to initialize the decrypt stream. The key-name argument
    is the address of a string descriptor pointing to the name of the
    previously defined user key to be used.

 algorithm

    type:      char_string
    access:    read only
    mechanism: by descriptor
    Algorithm used for the decryption 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. Specify the descriptor type value as one of the
    following:

    o  DSC$K_DTYPE_T (text)

    o  DSC$K_DTYPE_VT (varying text)

    o  DSC$K_DTYPE_Z (unspecified)

    For DES, the following algorithms are valid:

    o  DESCBC (default)

    o  DESECB

    o  DESCFB

    For AES, the following algorithms are valid:

    o  Cipher block chaining:

          AESCBC128 (default)
          AESCBC192
          AESCBC256

    o  Electronic code book:

          AESECB128
          AESECB192
          AESECB256

    o  Cipher feedback:

          AESCFB128
          AESCFB192
          AESCFB256

    o  Output feedback:

          AESOFB128
          AESOFB192
          AESOFB256

5  –  ENCRYPT$DEFINE_KEY

    Places a key definition into the process, group, job, or system
    key storage table.

    Format

      ENCRYPT$DEFINE_KEY  key-name, key-value, key-flags

5.1  –  Arguments

 key-name

    type:      char_string
    access:    read only
    mechanism: by descriptor
    Name of the key defined when ENCRYPT$DEFINE_KEY completes
    execution. The key-name argument is the address of a string
    descriptor pointing to a char_string that is interpreted as the
    name of the key to be defined. A maximum of 243 characters is
    permitted.

                                   NOTE

       Key names beginning with ENCRYPT$ are reserved for VSI.

 key-value

    type:      char_string
    access:    read only
    mechanism: by descriptor
    Key value defined when ENCRYPT$DEFINE_KEY completes execution.
    The key-value argument is the address of a string descriptor
    pointing to a vector of unsigned byte values that are assigned to
    the named key. A maximum of 240 bytes may be assigned.

 key-flags

    type:      longword
    access:    read only
    mechanism: by reference
    Flags that ENCRYPT$DEFINE_KEY uses when defining a key. The key-
    flags argument is the address of a longword containing flags that
    control the key definition process.

    Each flag has a symbolic name. The constants associated with
    these names are defined in the ENCRYPT$EXAMPLES:ENCRYPT_
    STRUCTURES files in various programming languages.

    ENCRYPT$DEFINE_KEY Flags defines the function of each flag.

    Table 9-1 ENCRYPT$DEFINE_KEY Flags

    Flag                   Function

    Symbolic Name          Function

    ENCRYPT$M_KEY_PROCESS  Places definition in process table
    ENCRYPT$M_KEY_GROUP    Places definition in group table
    ENCRYPT$M_KEY_JOB      Places definition in job table
    ENCRYPT$M_KEY_SYSTEM   Places definition in system table
    ENCRYPT$M_KEY_LITERAL  Stores key without compressing
    ENCRYPT$M_KEY_AES      Designates an AES key value

    The following AES mask can be used in addition to (OR with) other
    flags for the key-flags parameter (as a longword by reference).
    An associated AES key value can be used for testing the bit
    within the program. Use the KEY_AES key flag to specify an AES
    key:

    o  ENCRYPT$M_KEY_AES

    o  ENCRYPT$V_KEY_AES

6  –  ENCRYPT$DELETE_KEY

    Deletes a key definition from a key storage table.

    Format

      ENCRYPT$DELETE_KEY  key-name, key-flags

6.1  –  Arguments

 key-name

    type:      char_string
    access:    read only
    mechanism: by descriptor
    Name of the key removed from a key storage table when
    ENCRYPT$DELETE_KEY completes execution. The key-name argument is
    the address of a string descriptor pointing to a char_string that
    is interpreted as the name of the key to be deleted. A maximum of
    243 characters is permitted.

 key-flags

    type:      longword
    access:    read only
    mechanism: by reference
    Key table from which ENCRYPT$DELETE_KEY removes a key. The
    key-flags argument is a longword containing flags that control
    the deletion process. The following flags are available:

    ENCRYPT$M_KEY_PROCESS       Deletes a key from process table
    ENCRYPT$M_KEY_GROUP         Deletes a key from group table
    ENCRYPT$M_KEY_JOB           Deletes a key from job table
    ENCRYPT$M_KEY_SYSTEM        Deletes a key from system table
    ENCRYPT$M_KEY_AES           Designates an AES key value

    The following AES mask can be used in addition to (or with) other
    flags for the key-flags parameter (as a longword by reference).
    An associated AES key value can be used for testing the bit
    within the program. Use the KEY_AES key flag to specify an AES
    key:

    o  ENCRYPT$M_KEY_AES

    o  ENCRYPT$V_KEY_AES

7  –  ENCRYPT$ENCRYPT routine

    Transforms the next record of plaintext according to the
    algorithm you specify in the ENCRYPT$INIT call. This routine
    performs either an encryption or decryption operation.

    Format

      ENCRYPT$ENCRYPT  context, input, output [,output-length] [,p1]

7.1  –  Arguments

 context

    type:      longword integer (signed)
    access:    write only
    mechanism: by reference
    Context area initialized when ENCRYPT$INIT completes execution.
    The context argument is the address of a longword of unspecified
    interpretation that is used to convey context between encryption
    operations.

 input

    type:      char_string
    access:    read only
    mechanism: by descriptor
    Plaintext record to encrypt. The input argument is the address
    of a descriptor pointing to a byte-aligned buffer containing the
    input record to the encryption operation.

 output

    type:      char_string
    access:    write only by descriptor
    mechanism:
    Ciphertext record that results when ENCRYPT$ENCRYPT completes
    execution. The output argument is the address of a descriptor
    pointing to a byte-aligned buffer that will contain the output
    record from the encryption operation.

    If the descriptor is dynamic and insufficient space is allocated
    to contain the output record, storage is allocated from dynamic
    memory.

    ENCRYPT$ENCRYPT adjusts the length of the output descriptor,
    if possible, to reflect the actual length of the output string.
    If the descriptor type is not DSC$K_DTYPE_VS (varying string),
    DSC$K_DTYPE_V (varying), or DSC$K_DTYPE_D (dynamic), the routine
    takes the actual output count from the output-length argument.

    The output buffer must be able to accommodate a padded block to
    an increment of the block length. For AES this is 16 bytes and
    for DES, 8 bytes.

 output-length

    type:      word integer
    access:    write only
    mechanism: by reference
    Optional argument. Number of bytes that ENCRYPT$ENCRYPT wrote to
    the output buffer. The output-length argument is the address of a
    word containing the number of bytes written to the output buffer.

    Some encryption algorithms have specific requirements for the
    length of the input and output strings. In particular, DESECB
    and DESCBC pad input data with from 1 to 7 bytes to form complete
    64-bit blocks for operation. The values of the pad characters are
    indeterminate.

    When you decrypt fewer than 8 bytes, preserve and present to
    ENCRYPT$DECRYPT the full 8 bytes resulting from ENCRYPT$ENCRYPT.
    Retain the byte count of the input data in order to strip
    trailing pad bytes after a subsequent decryption operation.

    Note that the AES block mode algorithms (AESCBCxxx and AESECBxxx)
    pad the data to even 16 byte block boundaries. For AES, one byte
    encrypts and decrypts to 16 bytes, 72 bytes to 80, and so forth.
    The AES padding character is a HEX number of bytes indicating the
    number of bytes padded. For example, the one-byte encrypted pad
    would decrypt to 15 characters of 0F following the one encrypted
    byte of data. For the 72 bytes of data, eight bytes of padding
    characters (08 08 ... 08), would follow the 72 bytes of encrypted
    data. DESECB and DESCBC modes always pad with characters of
    zeros. The character stream modes (AESCFBxxx, AESOFBxxx, DESCFB).
    In order that the output-length will match the actual number of
    data bytes, do not pad the data.

 p1

    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 (DESECB,
    DESCFB, and DESMAC) of the DES algorithm for which it is
    applicable. The DES IV initialization vector is a quadword
    reference, to an eight byte value.

    For AES, the optional P1 argument for the AES IV initialization
    vector is a reference to a 16 byte (two quadwords) 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.

8  –  ENCRYPT$ENCRYPT_FILE

    Encrypts or decrypts data files.

    Format

      ENCRYPT$ENCRYPT_FILE  input-file, output-file, key-name,

                            algorithm, file-flags [,item-list]

8.1  –  Arguments

 input-file

    type:      char_string
    access:    read only
    mechanism: by descriptor
    Name of the input file that ENCRYPT$ENCRYPT_FILE is to process.
    The input-file argument is the address of a string descriptor
    pointing to the file specification string for the input file.

    Wildcard characters are valid. To specify multiple input files,
    you must use wildcard characters.

 output-file

    type:      char_string
    access:    read only
    mechanism: by descriptor
    Name of the output file that ENCRYPT$ENCRYPT_FILE is to generate.
    The output-file argument is the address of a string descriptor
    pointing to the file specification for the output file to be
    processed.

    You can use wildcard characters. To specify the same names for
    the output and input files, use a null character as the output-
    file argument.

 key-name

    type:      char_string
    access:    read only
    mechanism: by descriptor
    Name of the key used when ENCRYPT$ENCRYPT_FILE processes files.
    The key-name argument is the address of a string descriptor
    pointing to the name of the key to be used in initializing the
    encrypt or decrypt stream used for each file processed.

 algorithm

    type:      char_string
    access:    read only
    mechanism: by descriptor
    Name of the algorithm that ENCRYPT$ENCRYPT_FILE uses to
    initialize the process stream. The algorithm argument is the
    address of a string descriptor pointing to the name of the
    algorithm.

    For DES, the following algorithms are valid:

    o  DESCBC (default)

    o  DESECB

    o  DESCFB

    For AES, the following algorithms are valid:

    o  Cipher block chaining:

          AESCBC128 (default)
          AESCBC192
          AESCBC256

    o  Electronic code book:

          AESECB128
          AESECB192
          AESECB256

    o  Cipher feedback:

          AESCFB128
          AESCFB192
          AESCFB256

    o  Output feedback:

          AESOFB128
          AESOFB192
          AESOFB256

 file-flags

    type:      longword
    access:    read only
    mechanism: by reference
    Flags that specify how ENCRYPT$ENCRYPT_FILE performs the file
    operation. The file-flags argument is the address of a longword
    containing a mask of flags. ENCRYPT$ENCRYPT_FILE Flags shows the
    function of each flag.

    Table 9-2 ENCRYPT$ENCRYPT_FILE Flags

    Flag                   Function

    ENCRYPT$M_FILE_        Compresses file data before encryption.
    COMPRESS
    ENCRYPT$M_FILE_        Flag set: encrypts the file.
    ENCRYPT
                           Flag clear: decrypts the file.
    ENCRYPT$M_FILE_DELETE  Deletes the input file when the operation
                           completes.
    ENCRYPT$M_FILE_ERASE   Erases the file with the security data
                           pattern before deleting it.
    ENCRYPT$M_FILE_KEY_    Flag set: Treats the key value as a
    VALUE                  literal value and does not compress it.

                           Flag clear: Treats the key value as a
                           text string that can be compressed.

                           If the KEY_NAME parameter is present,
                           this flag is ignored.
    ENCRYPT$M_FILE_AES     Flag set: indicates encrypting a file with
                           an AES key and algorithm

    There is an additional FILE_AES flag mask (and value) that is
    used with the ENCRYPT$ENCRYPT_FILE routine when encrypting
    files using an AES algorithm. The ENCRYPT$ENCRYPT_FILE_FLAGS
    are used to control file operations such as cipher direction,
    file compression and so on. The FILE_AES flag controls file AES
    initialization and cipher operation.

 item-list

    type:      item_list_3
    access:    read only
    mechanism: by descriptor
    The optional item-list argument is used to override the data
    algorithm parameter. This argument substitutes one algorithm for
    another that is similar in function but that may be different
    in its name. In other words, it overrides the name of the
    algorithm that is found in the random key record with the name
    of the algorithm you provided in the override descriptor. This
    process provides a way to open files that were encrypted with an
    algorithm name that may be different than the algorithm name in
    the decrypt environment.

 ENCRYPT$K_DATA_ALGORITHM

    type:      3 longwords
    access:    read only
    mechanism: by descriptor
    Algorithm to be used to encrypt the file. This argument specifies
    the address and length of the name string of the algorithm.

    The following algorithms are valid:

    o  DESCBC (default)

    o  DESECB

    o  DESCFB

    For AES, the following algorithms are valid:

    o  Cipher block chaining:

          AESCBC128 (default)
          AESCBC192
          AESCBC256

    o  Electronic code book:

          AESECB128
          AESECB192
          AESECB256

    o  Cipher feedback:

          AESCFB128
          AESCFB192
          AESCFB256

    o  Output feedback:

          AESOFB128
          AESOFB192
          AESOFB256

9  –  ENCRYPT$ENCRYPT_ONE_RECORD

    Encrypts a small amount of data in an encrypt stream.

                                   NOTE

       To use AES for one record ciphers, you must first create
       an AES key, which is stored in the logical name table
       (encrypted). The key name of an AES key is specified as
       an address of a descriptor that contains the ASCII text for
       the selected AESmmmkkk (mode and key size) algorithm, for
       example, AESCBC256. The input and output buffers (descriptor
       addresses) are also provided.

    Format

      ENCRYPT$ENCRYPT_ONE_RECORD  input, output, key-name, algorithm

9.1  –  Arguments

 input

    type:      char_string
    access:    read only
    mechanism: by descriptor
    Plaintext record to be encrypted. The input argument is the
    address of a string descriptor pointing to a byte-aligned buffer
    containing the input record to be encrypted.

 output

    type:      char_string
    access:    write only
    mechanism: by descriptor
    Ciphertext record resulting when the routine completes execution.
    The output argument is the address of a string descriptor
    pointing to a byte-aligned buffer that will contain the
    ciphertext record.

    If the descriptor is dynamic, and insufficient space is allocated
    to contain the output record, storage is allocated from dynamic
    memory. If insufficient space exists to contain the output of the
    operation, an error is returned.

    The ENCRYPT$ENCRYPT_ONE_RECORD routine adjusts the length of the
    output descriptor, if possible, to reflect the actual length of
    the output string.

 key-name

    type:      char_string
    access:    read only
    mechanism: by descriptor
    Key used to initialize the encrypt stream. The key-name argument
    is the address of a string descriptor pointing to the name of the
    previously defined user key to be used.

 algorithm

    type:      char_string
    access:    read only
    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:

    o  DSC$K_DTYPE_T (text)

    o  DSC$K_DTYPE_VT (varying text)

    o  DSC$K_DTYPE_Z (unspecified)

    For DES, the following algorithms are valid:

    o  DESCBC (default)

    o  DESECB

    o  DESCFB

    For AES, the following algorithms are valid:

    o  Cipher block chaining:

          AESCBC128 (default)
          AESCBC192
          AESCBC256

    o  Electronic code book:

          AESECB128
          AESECB192
          AESECB256

    o  Cipher feedback:

          AESCFB128
          AESCFB192
          AESCFB256

    o  Output feedback:

          AESOFB128
          AESOFB192
          AESOFB256

10  –  ENCRYPT$FINI

    Disassociates the encryption context and releases it.

    Format

      ENCRYPT$FINI  context

10.1  –  Arguments

 context

    type:      longword integer (signed)
    access:    read/write
    mechanism: by reference
    Context area terminated when ENCRYPT$FINI completes execution.
    The context argument is the address of a longword initialized by
    the ENCRYPT$INIT routine.

11  –  ENCRYPT$GENERATE_KEY

    Generates a random key value.

    Format

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

                            [,factor-b] [,factor-c] [,key buffer]

11.1  –  Arguments

 algorithm-name

    type:      char_string
    access:    read only
    mechanism: by descriptor
    The name of the algorithm that will use the generated key.

 key-length

    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

    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 be:

    o  Time an operation started

    o  Size of a certain stack

    o  Copy of the last command line

 key-buffer

    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.

12  –  ENCRYPT$INIT

    Initializes the context for the encryption operation.

    Format

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

12.1  –  Arguments

 context

    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

    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:

    o  DESCBC (default)

    o  DESECB

    o  DESCFB

    For AES, the following algorithms are valid:

    o  Cipher block chaining:

          AESCBC128 (default)
          AESCBC192
          AESCBC256

    o  Electronic code book:

          AESECB128
          AESECB192
          AESECB256

    o  Cipher feedback:

          AESCFB128
          AESCFB192
          AESCFB256

    o  Output feedback:

          AESOFB128
          AESOFB192
          AESOFB256

 key-type

    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

    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 value of key-type. If this argument is:

    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 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 A-Z, 0-9, $, . (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 V8.3, this functionality applies
       only to DES, not AES. AES keys are not compressed.

 p1

    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 eight byte
    value.

    For AES, the optional P1 argument for the AES IV initialization
    vector is a reference to a 16 byte (two quadwords) 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.

13  –  ENCRYPT$STATISTICS

    Gains access to the statistics maintained by the Encryption
    software.

    Format

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

13.1  –  Arguments

 context

    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

    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

    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:

    o  One longword indicating the number of times the primitive has
       been entered referencing this encryption stream

    o  One quadword indicating the total bytes processed for this
       stream

    o  One quadword indicating the total CPU time, in OpenVMS time
       format, spent on processing requests for this stream

 return-length

    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.
Close Help