z/OS Security Server RACF Macros and Interfaces
Previous topic | Next topic | Contents | Contact z/OS | Library | PDF


Incorporating the PassTicket generator algorithm into your program

z/OS Security Server RACF Macros and Interfaces
SA23-2288-00

To generate a PassTicket without using the RACF® service, callable services, or Java™ interface, you need to incorporate the RACF PassTicket generator algorithm into your program.

The RACF PassTicket algorithm consists of two parts:
  • The RACF PassTicket generator
  • The RACF PassTicket time-coder

The time-coder is invoked from within the RACF PassTicket generator and returns its results to the generator.

The flowcharts in Figure 1 and Figure 2 and the descriptions that follow show how to implement the RACF PassTicket generator algorithm.

Figure 1. RACF PassTicket generator for secured signonRACF PassTicket generator for secured signon
Figure 2. Algorithm for RACF PassTicket time-coder used for secured signonAlgorithm for RACF PassTicket time-coder used for secured signon
Parent topic: Generating and evaluating a PassTicket

Input data for the algorithm

To successfully use the PassTicket, the target application using RACF to identify and authenticate a user ID needs to have specific information for processing according to the algorithm. As shown in Figure 2, these are:
  • A RACF host user ID
  • The RACF secured signon application key
  • The application name
  • Time and date information
 1 
The RACF user ID:
  • Identifies the user ID on the system on which the target application runs
  • Is represented in EBCDIC
  • Is left-justified and padded with blanks on the right to a length of 8 bytes
 2 
The RACF secured signon application key:
  • Must match the key value used when defining the application to the PTKTDATA class to RACF
  • Contains only the characters 0 through 9 and A through F
 3 
The application name as defined for a particular application. You can use it to associate a secured signon key with a particular host application. See z/OS Security Server RACF Security Administrator's Guide for information about determining application names.
The name:
  • Is represented in EBCDIC
  • Is left-justified and padded with blanks on the right to a length of 8 bytes
 4 
Time and date information and input data from the application that is providing the logon function. This information:
  • Must be a 4-byte binary number
  • Shows how many seconds elapsed since January 1, 1970, at 0000 Greenwich Mean Time (GMT)
Several programming languages support a function for representing time in this way. In C language, for example, you can obtain the time in this way:
  1. Declare the variable ts as long.
  2. Invoke the function time(&ts).
This produces the number of seconds that elapsed since January 1, 1970 at 0000 GMT, expressed as an unsigned long integer.
Note:
  1. It is likely that the computer that authenticates the PassTicket is not the computer that generated it. To provide for differences in their internal clocks, the algorithm allows the generated time to be 10 minutes on either side of the TOD clock of the computer that is evaluating the PassTicket.
  2. For RACF to properly evaluate PassTickets, the TOD clock must be properly set to GMT rather than local time.

How the generator algorithm works

The RACF PassTicket generator algorithm uses the input information to create a PassTicket. By using cryptographic techniques, the algorithm ensures that each PassTicket is unpredictable.

The PassTicket is an 8-character alphanumeric string that can contain the characters A through Z and 0 through 9. The actual PassTicket depends on the input values.

The following steps describe this process (see Figure 1 for a summary):
  1. The RACF user ID  1  is encrypted using the RACF secured signon application key  2  as the encryption key to produce Result-1.
    Note: All encryptions use the US National Institute of Standards and Technology Data Encryption Standard (DES) algorithm. Only the DES algorithm encoding is involved. You cannot perform general encryption and decryption of data with this implementation.
  2. Result-1 from the first encryption is XORed 1 with the application name  3 . The application name must be 8 bytes of EBCDIC characters with trailing blanks. The result (Result-2A) is encrypted using the application key value  2  as the encryption key to produce Result-2.
    Note: If you understand cryptographic techniques, you should recognize the flow (Steps 1 and 2) to be a common cryptographic architecture (CCA) standard message authentication code algorithm.
  3. The left 4 bytes from Result-2 of the second encryption are selected as input to the next step. The rest are discarded.
  4. The resulting 4 bytes (Result-3) are XORed with the time and date information  4 . The time and date is in the form of a 4-byte field that contains the number of seconds that elapsed since January 1, 1970 at 0000 GMT in the form of a binary integer. (See Input data for the algorithm for a complete description.)
  5. The result (Result-4) of that procedure is passed to the time-coder routine. Refer to the diagram in Figure 2 and to How the time-coder algorithm works to understand that process.
  6. The result (Result-5) of the time-coder routine is translated, using a translation table described in The translation table, to an 8-character string called the PassTicket. It is used in the user's host application signon request instead of the user's regular RACF password.

How the time-coder algorithm works

The RACF PassTicket time-coder algorithm uses the result of Step 4 of the generator algorithm. It creates the time-coder information and passes it back to step 6 of that algorithm.

The following steps, which make up Step 5 of the generator algorithm, shown in Figure 2 describe this process:
Step A
Separate the 4-byte time-coder input (Result-4) into two portions, L2B (the left side), and R2B (the right side) to produce Result-A.
Step B
Concatenate R2B (the right 2 bytes from Result-A) with 6 bytes of padding bits to form Result-B. In the resulting 8-byte string, the 2 bytes of R2B occupy the leftmost 2 byte positions.

The padding bits consist of two separate 6 byte strings: PAD1 and PAD2. PAD1 is the left half and PAD2 is the right half of a 12 byte string consisting of the user ID (from Step 1 in How the generator algorithm works) left justified and padded to the right with hexadecimal '55's. For example, if the user ID is "TOM", PAD1 is 'E3D6D4555555' and PAD2 is '555555555555'. If the user ID is "IBMUSER", PAD1 is 'C9C2D4E4D2C5' and PAD2 is 'D95555555555'. PAD1 is used for time coder loop rounds 1, 3, and 5. PAD2 is used for time coder loop rounds 2, 4, and 6.

Step C
Result-B is encrypted using the RACF secured signon application key  2  as the encryption key to produce Result-C.
Step D
The left 2 bytes from the Result-C are isolated and the rest of the value is discarded, producing Result-D.
Step E
Result-D is XORed with L2B (from Result-A) to produce Result-E.
Step F
The values of L2B and R2B are redefined:
  1. L2B is set equal to R2B.
  2. R2B is set equal to Result-E.
Step G
R2B is permuted 2 using the permutation tables in Figure 3, where the table used reflects the number of the round. For example, for the first time through, R2B is permuted using table 1.
Step H
This step counts the number of time-coder rounds that have been completed. If the value is less than 6, the time-coder returns to Step b for another round. If 6 rounds have been completed, processing continues with the next step.
Step I
L2B (left 2 bytes) and R2B (right 2 bytes) are recombined into a 32-bit string. This completes the time-coder processing and produces Result-5. This result is passed back to the generator algorithm as input to Step 6 for translation.

The permutation tables

A permutation table exists for each round of permutations that occurs during the time-coder process.

The six permutation tables work in the following manner:
  • The upper of the two rows of numbers (O=>) represents the output positions, from left to right, of the 16 bits being permuted.
  • The lower of the two rows (I=>) represents the input-bit position.
For example, using Permutation Table 1:
  • Output-bit position 1 consists of the bit (on or off) in input-bit position 10.
  • Output-bit position 2 consists of the bit in input-bit position 2.
Figure 3. Permutation tables for RACF secured signon
                      Permutation Table 1
 O=>  1   2   3   4   5   6   7   8   9  10  11  12  13  14  15  16
 I=> 10   2   12  4   14  6   16  8   9   1  11   3  13   5  15   7
                      Permutation Table 2
 O=>  1   2   3   4   5   6   7   8   9  10  11  12  13  14  15  16
 I=>  1  10   3  12   13  16  7  15   9   2  11   4   5  14   8   6
                      Permutation Table 3
 O=>  1   2   3   4   5   6   7   8   9  10  11  12  13  14  15  16
 I=>  3  10   1  12   13  16  9  15   7   2  14   4   5  11   8   6
                      Permutation Table 4
 O=>  1   2   3   4   5   6   7   8   9  10  11  12  13  14  15  16
 I=> 10   4  12   2   14  8  16   6   9   1  13   3  11   5  15   7
                      Permutation Table 5
 O=>  1   2   3   4   5   6   7   8   9  10  11  12  13  14  15  16
 I=>  4  10  12   1   8  16  14   5   9   2  13   3  11   7  15   6
                      Permutation Table 6
 O=>  1   2   3   4   5   6   7   8   9  10  11  12  13  14  15  16
 I=>  1  16  15  14  13  12  11  10   9   8   7   6   5   4   3   2

The translation table

The translation table consists of 36 slots. The first 26 slots are occupied by the letters of the alphabet: A–Z. The last ten slots are occupied by the numerics: 0–9.

Figure 4. Translation table for RACF secured signon
0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X  Y  Z
26 27 28 29 30 31 32 33 34 35
0  1  2  3  4  5  6  7  8  9

The translation process

The time-coder output produced by the process described in Figure 2 is translated into 8 alphanumeric characters in the following manner:
  1. Bits 31, 32, 1, 2, 3, and 4 are translated to PassTicket character position 1, which is the leftmost position in the 8-byte alphanumeric PassTicket field.
    To produce this character:
    • The binary number, represented by the six bits, is divided by decimal 36.
    • The remainder is used as an index into the translation table.

    For example, a remainder of 0 translates to a PassTicket character of A and a remainder of 20 translates to a PassTicket character of U.

  2. The process is repeated with the rest of the bit string:
    • Bits 3 through 8 are translated to PassTicket character position 2.
    • Bits 7 through 12 are translated to PassTicket character position 3.
    • Bits 11 through 16 are translated to PassTicket character position 4.
    • Bits 15 through 20 are translated to PassTicket character position 5.
    • Bits 19 through 24 are translated to PassTicket character position 6.
    • Bits 23 through 28 are translated to PassTicket character position 7.
    • Bits 27 through 32 are translated to PassTicket character position 8.

Example

In this example, the result of the time-coder step is X'07247F79'. Using that value, a PassTicket is generated as follows: 
Byte                 1        2        3        4
------------------------------------------------------
Hexadecimal value    07       24       7F       79
------------------------------------------------------
Binary            00000111 00100100 01111111 01111001
------------------------------------------------------
Bit Position      00000000 01111111 11122222 22222333
                  12345678 90123456 78901234 56789012
------------------------------------------------------
 PassTicket                                      Translates
  Character                                       to
  Position   Binary    Integer       Remainder   Character
------------------------------------------------------
        1    010000      16  x 1/36 => 16         Q
        2    000111       7  x 1/36 =>  7         H
        3    110010      50  x 1/36 => 14         O
        4    100100      36  x 1/36 =>  0         A
        5    000111       7  x 1/36 =>  7         H
        6    111111      63  x 1/36 => 27         1
        7    110111      55  x 1/36 => 19         T
        8    111001      57  x 1/36 => 21         V
------------------------------------------------------
  1. Bits 31, 32, 1, 2, 3, and 4 (6 bits total) are translated to produce the PassTicket character in position 1.

    The six bits (binary '010000' or decimal 16) are divided by decimal 36.

  2. The remainder (decimal 16) becomes the index into the translation table. The result is character 'Q'.
  3. Repeat the process for the rest of the bits.
    • Bits 3 through 8 are translated to PassTicket character 'H'.
    • Bits 7 through 12 are translated to PassTicket character 'O'.
    • Bits 11 through 16 are translated to PassTicket character 'A'.
    • Bits 15 through 20 are translated to PassTicket character 'H'.
    • Bits 19 through 24 are translated to PassTicket character '1'.
    • Bits 23 through 28 are translated to PassTicket character 'T'.
    • Bits 27 through 32 are translated to PassTicket character 'V'.

The resulting PassTicket returned as output is QHOAH1TV.

1 XOR is a Boolean function that processes two-bit strings of the same length, producing a third string of the same length as the output. In the output string, a bit is ON if the corresponding bit is ON for one of the input bit strings, but not both.
2 To permute is to transform or change the order of members of a group.

Go to the previous page Go to the next page

Notices | Terms of use | Support | Contact z/OS | zFavorites



Copyright IBM Corporation 1990, 2014