DSS Key Token Formats

z/OS Cryptographic Services ICSF Application Programmer's Guide

DSS Key Token Formats

z/OS Cryptographic Services ICSF Application Programmer's Guide
SA22-7522-16

DSS Public Key Token

A DSS public key token contains the following sections:

A required token header, starting with the token identifier X'1E'
A required DSS public key section, starting with the section identifier X'03'

Table 352 presents the format of a DSS public key token. All length fields are in binary. All binary fields (exponents, lengths, and so on) are stored with the high-order byte first (left, low-address, S/390 format).

Table 352. DSS Public Key Token
Offset (Dec)	Number of Bytes	Description
Token Header (required)
000	001	Token identifier. X'1E' indicates an external token.
001	001	Version, X'00'.
002	002	Length of the key token structure.
004	004	Ignored. Should be zero.
DSS Public Key Section (required)
000	001	X'03', section identifier, DSS public key.
001	001	X'00', version.
002	002	Section length, 14+ppp+qqq+ggg+yyy.
004	002	Size of p in bits. The size of p must be one of: 512, 576, 640, 704, 768, 832, 896, 960, or 1024.
006	002	Size of the p field in bytes, "ppp".
008	002	Size of the q field in bytes, "qqq".
010	002	Size of the g field in bytes, "ggg".
012	002	Size of the y field in bytes, "yyy".
014	ppp	Prime modulus (large public modulus), p.
014 +ppp	qqq	Prime divisor (small public modulus), q. ¹⁵⁹<q<2¹⁶⁰.
014 +ppp +qqq	ggg	Public key generator, g.
014 +ppp +qqq +ggg	yyy	Public key, y. ^x mod(p); 1<y<p.

DSS Private External Key Token

A DSS private external key token contains the following sections:

A required PKA token header, starting with the token identifier X'1E'
A required DSS private key section, starting with the section identifier X'01'
A required DSS public key section, starting with the section identifier X'03'
An optional private key name section, starting with the section identifier X'10'

Table 353 presents the format of a DSS private external key token. All length fields are in binary. All binary fields (exponents, lengths, and so on) are stored with the high-order byte first (left, low-address, S/390 format). All binary fields (exponents, modulus, and so on) in the private sections of tokens are right-justified and padded with zeros to the left.

Table 353. DSS Private External Key Token
Offset (Dec)	Number of Bytes	Description
Token Header (required)
000	001	Token identifier. X'1E' indicates an external token. The private key is enciphered with a PKA master key.
001	001	Version, X'00'.
002	002	Length of the key token structure.
004	004	Ignored. Should be zero.
DSS Private Key Section and Secured Subsection (required)
000	001	X'01', section identifier, DSS private key.
001	001	X'00', version.
002	002	Length of the DSS private key section, 436, X'01B4'.
004	020	SHA-1 hash value of the private key subsection cleartext, offset 28 to the section end. This hash value is checked after an enciphered private key is deciphered for use.
024	004	Reserved; set to binary zero.
028	001	Key security: X'00' Unencrypted DSS private key subsection identifier. X'81' Encrypted DSS private key subsection identifier.
029	001	Padding, X'00'.
030	020	SHA-1 hash of the key token structure contents that follow the public key section. If no sections follow, this field is set to binary zeros.
050	010	Reserved; set to binary zero.
060	048	Ignored; set to binary zero.
108	128	Public key generator, g. 1<g<p.
236	128	Prime modulus (large public modulus), p. and L (the modulus length) must be a multiple of 64.
364	020	Prime divisor (small public modulus), q. .
384	004	Reserved; set to binary zero.
388	024	Random number, confounder. Note: This field and the next two fields are enciphered for key confidentiality when the key security flag (offset 28) indicates the private key is enciphered.
412	020	Secret DSS key, x; x is random. (See the preceding note.)
432	004	Random number, generated when the secret key is generated. (See the preceding note.)
DSS Public Key Section (required)
000	001	X'03', section identifier, DSS public key.
001	001	X'00', version.
002	002	Section length, 14+yyy.
004	002	Size of p in bits. The size of p must be one of: 512, 576, 640, 704, 768, 832, 896, 960, or 1024.
006	002	Size of the p field in bytes, which is zero for a private token.
008	002	Size of the q field in bytes, which is zero for a private token.
010	002	Size of the g field in bytes, which is zero for a private token.
012	002	Size of the y field in bytes, "yyy".
014	yyy	Public key, y. Note: p, q, and y are defined in the DSS public key token.
Private Key Name (optional)
000	001	X'10', section identifier, private key. name
001	001	X'00', version.
002	002	Section length, X'0044' (68 decimal).
004	064	Private key name (in ASCII), left-justified, padded with space characters (X'20'). An access control system can use the private key name to verify that the calling application is entitled to use the key.

DSS Private Internal Key Token

A DSS private internal key token contains the following sections:

A required PKA token header, starting with the token identifier X'1F'
A required DSS private key section, starting with the section identifier X'01'
A required DSS public key section, starting with the section identifier X'03'
An optional private key name section, starting with the section identifier X'10'
A required internal information section, starting with the eyecatcher 'PKTN'

Table 354 presents the format of a DSS private internal token. All length fields are in binary. All binary fields (exponents, lengths, and so on) are stored with the high-order byte first (left, low-address, S/390 format). All binary fields (exponents, modulus, and so on) in the private sections of tokens are right-justified and padded with zeros to the left.

Table 354. DSS Private Internal Key Token
Offset (Dec)	Number of Bytes	Description
Token Header (required)
000	001	Token identifier. X'1F' indicates an internal token. The private key is enciphered with a PKA master key.
001	001	Version, X'00'.
002	002	Length of the key token structure excluding the internal information section.
004	004	Ignored; should be zero.
DSS Private Key Section and Secured Subsection (required)
000	001	X'01', section identifier, DSS private key.
001	001	X'00', version.
002	002	Length of the DSS private key section, 436, X'01B4'.
004	020	SHA-1 hash value of the private key subsection cleartext, offset 28 to the section end. This hash value is checked after an enciphered private key is deciphered for use.
024	004	Reserved; set to binary zero.
028	001	Key security: X'01' DSS private key.
029	001	Format of external key token: X'10' Private key generated on an ICSF host. X'11' External private key was specified in the clear. X'12' External private key was encrypted.
030	020	SHA-1 hash of the key token structure contents that follow the public key section. If no sections follow, this field is set to binary zeros.
050	010	Reserved; set to binary zero.
060	048	The OPK encrypted under a PKA master key (Signature Master Key (SMK)).
108	128	Public key generator, g. 1<g<p.
236	128	Prime modulus (large public modulus), p. ^L-1<p<2^L for 512≤L≤1024, and L (the modulus length) must be a multiple of 64.
364	020	Prime divisor (small public modulus), q. ¹⁵⁹<q<2¹⁶⁰.
384	004	Reserved; set to binary zero.
388	024	Random number, confounder. Note: This field and the two that follow are enciphered under the OPK.
412	020	Secret DSS key, x. x is random. (See the preceding note.)
432	004	Random number, generated when the secret key is generated. (See the preceding note.)
DSS Public Key Section (required)
000	001	X'03', section identifier, DSS public key.
001	001	X'00', version.
002	002	Section length, 14+yyy.
004	002	Size of p in bits. The size of p must be one of: 512, 576, 640, 704, 768, 832, 896, 960, or 1024.
006	002	Size of the p field in bytes, which is zero for a private token.
008	002	Size of the q field in bytes, which is zero for a private token.
010	002	Size of the g field in bytes, which is zero for a private token.
012	002	Size of the y field in bytes, "yyy".
014	yyy	Public key, y. ^x mod(p); Note: p, g, and y are defined in the DSS public key token.
Private Key Name (optional)
000	001	X'10', section identifier, private key name.
001	001	X'00', version.
002	002	Section length, X'0044' (68 decimal).
004	064	Private key name (in ASCII), left-justified, padded with space characters (X'20'). An access control system can use the private key name to verify that the calling application is entitled to use the key.
Internal Information Section (required)
000	004	Eye catcher 'PKTN'.
004	004	PKA token type. Bit Meaning When Set On 0 RSA key. 1 DSS key. 2 Private key. 3 Public key. 4 Private key name section exists.
008	004	Address of token header.
012	002	Length of internal work area.
014	002	Count of number of sections.
016	016	PKA master key hash pattern.
032	016	Reserved.

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