1 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. 2 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 2 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 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. 2 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 3 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 2 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 3 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 HP. 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 2 ENCRYPT$DELETE_KEY Deletes a key definition from a key storage table. Format ENCRYPT$DELETE_KEY key-name, key-flags 3 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 2 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] 3 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. 2 ENCRYPT$ENCRYPT_FILE Encrypts or decrypts data files. Format ENCRYPT$ENCRYPT_FILE input-file, output-file, key-name, algorithm, file-flags [,item-list] 3 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 2 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 3 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 2 ENCRYPT$FINI Disassociates the encryption context and releases it. Format ENCRYPT$FINI context 3 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. 2 ENCRYPT$GENERATE_KEY Generates a random key value. Format ENCRYPT$GENERATE_KEY algorithm-name, key-length [,factor-a] [,factor-b] [,factor-c] [,key buffer] 3 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. 2 ENCRYPT$INIT Initializes the context for the encryption operation. Format ENCRYPT$INIT context, algorithm, key-type, key-name [,p1] 3 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. 2 ENCRYPT$STATISTICS Gains access to the statistics maintained by the Encryption software. Format ENCRYPT$STATISTICS context, code, destination, return-length 3 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.