General
Application area: | Word encryption; see "Messages" |
Macro type: | Type S, MF format 3: D/C/M/E/L form; see "S-type macros" |
Macro description
The CRYPT macro is used for one-way encryption of words with a maximum length of
8 bytes. One-way encryption means that it is not possible to decrypt the words that have been encrypted with CRYPT. A 4-byte or 8-byte string is returned as a result of macro execution.
Macro format and description of operands
CRYPT |
INSTRA=<var: pointer> / (<reg: pointer>) ,INSTRL=4 / 8 / <var: int:1> ,OUSTRA=<var: pointer> / (<reg: pointer>) ,CRYALG=*SCA / *SCAVK / *OLD / <var: enum-of _ecrt_s:1> ,CRCL2OP=*YES / *NO / <var: enum-of _cl2op_s:1> ,VKEYA=<var: pointer> / (<reg: pointer>) ,XPAND=*INPAR / *KEYPAR ,MF=D / C / M / E / L [,PARAM = addr / (r)] ,PREFIX=S / p ,MACID=RME / macid |
The operands are described in alphabetical order below.
CRCL2OP=
Encrypts the input word in accordance with the system parameter ENCRYPT.
*YES
Encryption is in accordance with the system parameter ENCRYPT.
*NO
The input word is always encrypted, regardless of the system parameter ENCRYPT.
<var: enum-of _cl2op_s:1>
Name of the field together with the type of encryption.
CRYALG=
Selects the encryption algorithm.
*SCA
The encryption algorithm SCA is used.
*SCAVK
The encryption algorithm SCA is used with the key specified in the key field (VKEYA operand).
*OLD
Specifies the encryption algorithm used previously.
<var: enum-of _ecrt_s:1>
Name of the field with the encryption algorithm.
INSTRA=
Defines the address of a field which contains the word which is to be encrypted (input word). The length of this field is specified in the INSTRL operand. The input word must be a string of type X string or C string and may be a maximum of 8 characters in length.
This operand is mandatory in conjunction with MF=L.
<var: pointer>
Name of the field with the address of the input word; only permitted with MF=M.
(<reg: pointer>)
Register with the address of the input word; only permitted with MF=M.
INSTRL=
Specifies the length of the field that has to be reserved for the encrypted input word. the maximum permitted value for the length is 8. The field in which the input word is now specified may now be either 4 or 8 bytes long
4
4 bytes are reserved for the field length.
8
8 bytes are reserved for the field.
<var: int:1>
Name of the field together with a specification of the field length that has to be reserved.
MF=
For a general description of the MF operand, its operand values and any subsequent operands (e.g. PREFIX, MACID and PARAM), see "S-type macros". The valid MF values are given at the start of the macro description under “Macro type” and are included in the macro format.
A PREFIX can be specified in the C form or D form of the macro and additionally a MACID in the C form (see section “S-type macros”).
OUSTRA=
Defines the address of a field which is to contain the encrypted word (output word). If the input word is <= 4 bytes, a 4-byte long output word is returned. If the length of the input word is between 5 and 8 bytes, an 8-byte long output word is returned.
These operands are mandatory in conjunction with MF=L.
<var: pointer>
Name of the field with the address of the output word; only permitted with MF=M.
(<reg: pointer>)
Register with the address of the output word; only permitted with MF=M.
VKEYA=
Address of the employed variable key which is to be used if the encryption setting CRYALG=*SCAVK is selected.
<var: pointer>
Name of the field with the address of the variable key; only permitted with MF=M.
(<reg: pointer>)
Register with the address of the variable key; only permitted with MF=M.
XPAND=
Controls the expansion scope of the macro.
*INPAR
Preset value: the parameter structure is expanded.
*KEYPAR
Only the data area for the variable key is expanded.
Selecting the variable key
A variable key may be used only in conjunction with the SCA encryption algorithm (CRYALG=*SCA operand). The variable key is 44 bytes long and comprises the following four parts (PREFIX and MACID are assigned their respective default settings):
SRMEVK | DS | 0F | |
SRMECC | DS | F | number of iterations |
SRMEKEE1 | DS | XL16 | key component EE1 |
SRMEKEE2 | DS | XL16 | key component EE2 |
SRMEKEE3 | DS | XL8 | key component EE3 |
SRMEVK# | EQU | *-SRMEVK |
The SCA encryption algorithm is an iterative application of a basic encryption method. To provide sufficient security, the number of iterations (SRMECC field) must be between 128 and 8192. Encryption using 128 iterations requires approximately 15000 operations. The number of operations increases linearly with the number of iterations.
The key components EE1 and EE2 (SRMEKEE1 and SRMEKEE2 fields) represent permutations of the numbers 0 through 15. For a “secure” key, each byte of EE1 and EE2 must contain a number between 0 and 15; each of these numbers must occur once in each of the key components EE1 and EE2.
The key component EE3 (SRMEKEE3 field) can contain any characters and has a length of 8 bytes. However, no two of these bytes may be identical.
The encryption routine does not check whether the above conditions for a “secure” variable key have been met. It is often impossible to avoid using “insecure” keys in one-way encryption. For this reason, the SCA encryption algorithm can also work with “insecure” keys. For reasons of security, however, the use of such keys should be avoided if possible.
Encryption of input words > 8 bytes long
If encryption of words > 8 bytes long is required, it is possible to split the input word into several 8-byte words and encrypt these word segments separately. The encryption of words > 8 bytes long is no more secure than the encryption of words <= 8 bytes long using the algorithms provided by the CRYPT macro.
Layout of the DSECT
The layout of the DSECT is to be found on "CRYPT - Word encryption".
Return information and error flags
Standard header:
+---------------+ | | | | | |c|c|b|b|a|a|a|a| +---------------+
A structured return code relating to the execution of the CRYPT macro is returned: (cc=Subcode2, bb=Subcode1, aaaa=Maincode)
X'cc' | X'bb' | X'aaaa' | Meaning |
X'00' | X'00' | X'0000' | Function executed successfully |
X'01' | X'01' | X'0001' | Function not executed due to operand error: input word not assigned |
X'02' | X'01' | X'0001' | Function not executed due to operand error: output word not assigned |
X'03' | X'01' | X'0001' | Function not executed due to operand error: no assignment for variable key |
X'04' | X'01' | X'0001' | Function not executed due to operand error: invalid specification for |
X'05' | X'01' | X'0001' | Function not executed due to operand error: |
X'06' | X'01' | X'0001' | Function not executed due to operand error: invalid length specification for |
X'08' | X'01' | X'0001' | Function not executed due to operand error: invalid variable key |
X'09' | X'01' | X'0002' | Function not executed due to memory request error: |
X'0A' | X'01' | X'0002' | Function not executed due to memory request error: |
X'0B' | X'01' | X'0002' | Function not executed due to memory request error: |
X'0C' | X'01' | X'0002' | Function not executed due to memory request error: |
X'0D' | X'01' | X'0002' | Function not executed due to memory request error |
X'20' | X'0003' | Function not executed: internal error |
Other return codes which, in accordance with conventions, apply to all macros are given in the table “Standard return codes” (Standard header).
Example
PRINT NOGEN
CRYPT START
BALR 10,0
USING *,10
CRYPT MF=E,PARAM=PARLIST —————————————————————————————————— (1)
1 MFCHK MF=E,PREFIX=S,MACID=RME,PARAM=PARLIST,
1 SVC=16,
1 DMACID=RME,SUPPORT=(D,L,C,M,E)
2 LA 1,PARLIST
2 SVC 16
CLI SRMEMR1,SRMEOK * Error query
BNE ERREXIT
UNPK OUTPUTX(9),OUTPUT(5)
UNPK OUTPUTX+8(9),OUTPUT+4(5)
TR OUTPUTX,CODETAB-C'0'
WROUT CODE,0 * Output
TERM
*
ERREXIT WROUT TEXT,0
TERM
****
CODE DC Y(CODEEND-CODE)
DS CL3
DC C'OUTPUT OF THE ENCRYPTED WORD '
INPUT DC C'SUPERMAN' * Input word *
DC C': '
OUTPUT DS CL8 * Output word
DC C' '
OUTPUTX DS CL16 * Output word hex
CODEEND EQU *
DS C
TEXT DC Y(TEXTEND-TEXT)
DS CL3
DC C'ERROR !!'
TEXTEND EQU *
KEY DS 0F
DC F'250' * Number of iterations
DC X'0203040506070809' * EE1
DC X'0A0B0C0D0E0F0001' EE1 *
DC X'0100030205040706' * EE2
DC X'09080B0A0D0C0F0E' EE2 *
DC X'A1A2A3A4A5A6A7A8' * EE3 *
PARLIST CRYPT MF=L,INSTRL=8,CRYALG=*SCAVK,CRCL2OP=*NO, -
VKEYA=KEY,INSTRA=INPUT,OUSTRA=OUTPUT ———————————————— (1)
ORG PARLIST
CRYPT MF=C ———————————————————————————————————————————————— (2) 1 * 1 SRMEPA DS 0F BEGIN of PARAMETERAREA 1 FHDR MF=(C,SRME),EQUATES=NO STANDARD HEADER 2 DS 0A 2 SRMEFHE DS 0XL8 0 GENERAL PARAMETER AREA HEADER 2 * 2 SRMEIFID DS 0A 0 INTERFACE IDENTIFIER 2 SRMEFCTU DS AL2 0 FUNCTION UNIT NUMBER 2 * BIT 15 HEADER FLAG BIT, 2 * MUST BE RESET UNTIL FURTHER NOTICE 2 * BIT 14-12 UNUSED, MUST BE RESET 2 * BIT 11-0 REAL FUNCTION UNIT NUMBER 2 SRMEFCT DS AL1 2 FUNCTION NUMBER 2 SRMEFCTV DS AL1 3 FUNCTION INTERFACE VERSION NUMBER 2 * 2 SRMERET DS 0A 4 GENERAL RETURN CODE 2 SRMESRET DS 0AL2 4 SUB RETURN CODE 2 SRMESR2 DS AL1 4 SUB RETURN CODE 2 2 SRMESR1 DS AL1 5 SUB RETURN CODE 1 2 SRMEMRET DS 0AL2 6 MAIN RETURN CODE 2 SRMEMR2 DS AL1 6 MAIN RETURN CODE 2 2 SRMEMR1 DS AL1 7 MAIN RETURN CODE 1 2 SRMEFHL EQU 8 8 GENERAL OPERAND LIST HEADER LENGTH 2 * 1 * RETURN CODE EQUATES FOR MAIN-CODE 1 1 SRMEOK EQU X'00' NOERROR 1 SRMEIOP EQU X'01' INVALID OPERAND 1 SRMEIAR EQU X'02' INVALID AREA 1 SRMEINE EQU X'03' INTERNAL ERROR 1 * 1 SRMEIN DS F INPUT STRING ADDRESS 1 SRMEOUT DS F OUTPUT STRING ADDRESS 1 SRMELEN DS X INPUT STRING LENGTH 1 SRMEECR DS X SELECT ENCRYPTION ROUTINE 1 * 1 * EQUATES FOR ENCRYPTION ROUTINE SELECT 1 SRMEECRS EQU X'01' SCA ENCRYPTION ROUTINE 1 SRMEECRO EQU X'02' OLD ENCRYPTION ROUTINE 1 SRMEECRV EQU X'03' SCA ENCR. ROUT. (V. KEY) 1 * 1 SRMEC2O DS X SEL. CLASS 2 OPTION YES/NO 1 * EQUATES FOR CLASS 2 OPTION 1 SRMEC2OY EQU X'01' CLASS 2 OPTION YES 1 SRMEC2ON EQU X'02' CLASS 2 OPTION NO 1 * 1 SRMEPOE DS X PROGRESS OF EXECUTION 1 * RETURN FOR PROGRESS OF EXECUTION
1 SRMEUV EQU X'01' UNCRYPTED
1 SRMESCA EQU X'02' SCA ENCRYPTED
1 SRMEOLD EQU X'03' OLD ENCRYPTED
1 SRMESVK EQU X'04' SCA ENCRYPTED (V. KEY)
1 *
1 SRMESVK@ DS F ADR. VARIABLE KEY
1 SRME# EQU *-SRMEPA LENGTH OF PARAMETERAREA
*
CODETAB DC C'0123456789ABCDEF'
END CRYPT
Runtime log:
/start-assembh % BLS0500 PROGRAM 'ASSEMBH', VERSION '<ver>' OF '<date>' LOADED % ASS6010 <ver> OF BS2000 ASSEMBH READY %//compile source=*library-element(lib.srpmencp,crypt), - %// compiler-action=module-generation(module-format=llm), - %// module-library=lib.srpmencp, - %// listing=parameters(output=*library-element(lib.srpmencp,crypt)) % ASS6011 ASSEMBLY TIME: 360 MSEC % ASS6018 0 FLAGS, 0 PRIVILEGED FLAGS, 0 MNOTES % ASS6019 HIGHEST ERROR-WEIGHT: NO ERRORS % ASS6006 LISTING GENERATOR TIME: 65 MSEC %//end % ASS6012 END OF ASSEMBH /start-executable-program library=lib.srpmencp,element-or-symbol=crypt % BLS0523 ELEMENT 'CRYPT', VERSION '@', TYPE 'L' FROM LIBRARY ':2OSC:$EVA.LIB .SRPMENCP' IN PROCESS % BLS0524 LLM 'CRYPT', VERSION ' ' OF '<date> <time>' LOADED OUTPUT OF THE ENCRYPTED WORD SUPERMAN: |ÑzÄkè~] 4F69A9639254FFBD ————— (3)
(1) | A word with a length of 8 bytes is to be encrypted with the CRYPT macro using the SCA algorithm, irrespective of the class 2 option. A variable key is to be used. The input word is read from the |
(2) | Layout of the DSECT. |
(3) | The
|