The developerWorks Connections platform will be sunset on December 31, 2019. On January 1, 2020, this blog will no longer be available. More details available on our FAQ.

IBM Crypto Education

Matching: kek

Using NOCV key-encrypting keys to create a different key type with the same clear key value

EChan_pok Tags: krc2 csnbkex kcv kek kyt2 nocv csnbkim kim kex ‎ 2,233 Views

/* Rexx */

/*--------------------------------------------------------------------*/
/* This sample will use Key Export (CSNBKEX) and Key Import (CSNBKIM) */
/* and NOCV key-encrypting keys (aka transport keys) to create        */
/* another key with the same clear key value. This will work with    */
/* any key type supported by Key Import.                              */
/*                                                                    */
/* To generate NOCV key-encrypting keys, see Rexx Sample in the       */
/* IBM Crypto Education community:                                    */
/*    Generate/Create NOCV IMPORTER/EXPORTER key-encrypting key pair */
/*                                                                    */
/* For more information about NOCV key-encrypting keys (KEKs), see    */
/* Chapter 2 of the z/OS ICSF Application Programmer's Guide.         */
/*--------------------------------------------------------------------*/
/* When a key is exported under a NOCV KEK, the control vector is not */
/* applied to the transport key. The key is encrypted under the       */
/* transport key itself, not under the transport key variant.         */
/* For more information on transport key variants and the callable    */
/* services used in this sample, see the z/OS ICSF Application        */
/* Programmer's Guide.                                                */
/*--------------------------------------------------------------------*/

/* This sample assumes the following key-encrypting keys exist */
/* in the CKDS. The EXPORTER and IMPORTER KEKs must have the */
/* same clear key value. */
NOCV_EXPORTER_KEK = left('SAMPLE.NOCV.EXPORTER',64) ;
NOCV_IMPORTER_KEK = left('SAMPLE.NOCV.IMPORTER',64) ;

/* This sample will create an IPINENC key from an existing      */
/* double-length CIPHER key. The key length of both keys must */
/* be the same. The IPINENC key will have the same clear key    */
/* value as the CIPHER key.                                     */
key_label_to_be_exported = left('SAMPLE.CIPHER',64) ;

/* Call Key Test2 to generate a key check value (kcv) for the   */
/* key to be exported. This kcv will be used later to verify    */
/* that both CIPHER and IPINENC keys have the same key value.   */

/* Key Test2 parameters */
rule_array_count = '00000003'x ;
rule_array = 'DES     '||,
             'GENERATE'||, /* generate kcv */
             'ENC-ZERO' ;
key_identifier_length = '00000040'x ;
key_identifier = key_label_to_be_exported ; /* SAMPLE.CIPHER */
verification_pattern_length = '00000008'x ;
verification_pattern = '0000000000000000'x ;
CALL KYT2 ;
CIPHER_kcv = verification_pattern ; /* save kcv */
SAY 'CIPHER KCV:' c2x(CIPHER_kcv) ;

/* KEY EXPORT (CSNBKEX) will unwrap the source key from         */
/* encryption under the DES master key to encryption under the */
/* exporter key-encrypting key. All wrapping/unwrapping of     */
/* secure keys are performed inside the secure boundary of the */
/* crypto coprocessor.                                          */

/* Key Export parameter list */
KEX_rc = 'FFFFFFFF'x ;
KEX_rs = 'FFFFFFFF'x ;
exit_data_length = '00000000'x ;
exit_data = '' ;
key_type = 'CIPHER ' ;
source_key_identifier = key_label_to_be_exported ;
exporter_key_identifier = NOCV_EXPORTER_KEK ;
target_key_identifier = copies('00'x,64) ;

/* call Key Export */
ADDRESS LINKPGM 'CSNBKEX' ,
                'KEX_rc' ,
                'KEX_rs' ,
                'exit_data_length' ,
                'exit_data' ,
                'key_type' ,
                'source_key_identifier' ,
                'exporter_key_identifier' ,
                'target_key_identifier' ;

if KEX_rc /= '00000000'x THEN
DO ;
SAY 'KEX failed: rc =' c2x(KEX_rc) 'rs =' c2x(KEX_rs) ;
EXIT ;
END ;
ELSE
DO ;
SAY 'exported key identifier:' ;
SAY c2x(substr(target_key_identifier, 1,32)) ;
SAY c2x(substr(target_key_identifier,33,32)) ;
END ;

/* KEY IMPORT (CSNBKIM) will unwrap the source key from */
/* encryption under the key-encrypting key to encryption */
/* under the DES master key. */

/* Key Import parameter list */
KIM_rc = 'FFFFFFFF'x ;
KIM_rs = 'FFFFFFFF'x ;
exit_data_length = '00000000'x ;
exit_data = '' ;
key_type = 'IPINENC' ; /* must specify a key type,
                            TOKEN not allowed        */
source_key_identifier   = target_key_identifier ; /* from KEX */
importer_key_identifier = NOCV_IMPORTER_KEK ;
target_key_identifier   = copies('00'x,64) ;

/* call Key Import */
ADDRESS LINKPGM 'CSNBKIM' ,
                'KIM_rc' ,
                'KIM_rs' ,
                'exit_data_length' ,
                'exit_data' ,
                'key_type' ,
                'source_key_identifier' ,
                'importer_key_identifier' ,
                'target_key_identifier' ;

IF KIM_rc /= '00000000'x THEN
DO ;
SAY 'KIM failed: rc =' c2x(KIM_rc) 'rs =' c2x(KIM_rs) ;
EXIT ;
END ;
ELSE
DO ;
SAY 'imported key identifier:' ;
SAY c2x(substr(target_key_identifier, 1,32)) ;
SAY c2x(substr(target_key_identifier,33,32)) ;
END ;

/* The imported key identifier is now encrypted under the */
/* DES master key. Write the imported key token to the CKDS. */

/* Key Record Create2 parameter list */
KRC2_rc = 'FFFFFFFF'x ;
KRC2_rs = 'FFFFFFFF'x ;
exit_data_length = '00000000'x ;
exit_data = '' ;
rule_array_count = '00000000'x ;
rule_array = '' ;
key_label = left('SAMPLE.IPINENC',64) ;
key_token_length = '00000040'x ;
key_token = target_key_identifier ; /* from KIM */

/* call CKDS Key Record Create2 */
ADDRESS LINKPGM 'CSNBKRC2',
                'KRC2_rc' ,
                'KRC2_rs' ,
                'exit_data_length' ,
                'exit_data' ,
                'rule_array_count' ,
                'rule_array' ,
                'key_label' ,
                'key_token_length' ,
                'key_token' ;

IF KRC2_rc /= '00000000'x THEN
DO ;
SAY 'KRC2 failed: rc =' c2x(KRC2_rc) 'rs =' c2x(KRC2_rs) ;
EXIT ;
END ;

/* Call Key Test2 to verify that the kcv of the */
/* CIPHER key matches the kcv of the IPINENC key. */

/* Key Test2 parameters */
rule_array_count = '00000003'x ;
rule_array = 'DES     '||,
             'VERIFY '||, /* verify kcv */
             'ENC-ZERO' ;
key_identifier_length = '00000040'x ;
key_identifier = left('SAMPLE.IPINENC',64) ;
verification_pattern_length = '00000008'x ;
verification_pattern = CIPHER_kcv ;
CALL KYT2 ;
IF KYT2_rc = '00000000'x THEN
SAY 'KCVs MATCH!!!' ;

EXIT ;

/*--------------------------------------------------------*/
/* Use Key Test2 to generate or verify a key check value. */
/*--------------------------------------------------------*/
KYT2:

/* Key Test2 parameters */
KYT2_rc = 'FFFFFFFF'x ;
KYT2_rs = 'FFFFFFFF'x ;
exit_data_length = '00000000'x ;
exit_data = '' ;
key_encrypting_key_identifier_length = '00000000'x ;
key_encrypting_key_identifier = '' ;
reserved_length = '00000000'x ;
reserved = '' ;

/* call Key Test2 */
ADDRESS LINKPGM 'CSNBKYT2',
                'KYT2_rc' ,
                'KYT2_rs' ,
                'exit_data_length' ,
                'exit_data' ,
                'rule_array_count' ,
                'rule_array' ,
                'key_identifier_length' ,
                'key_identifier' ,
                'key_encrypting_key_identifier_length' ,
                'key_encrypting_key_identifier' ,
                'reserved_length' ,
                'reserved' ,
                'verification_pattern_length' ,
                'verification_pattern' ;

IF KYT2_rc /= '00000000'x THEN
DO ;
SAY 'KYT2 failed: rc =' c2x(KYT2_rc) 'rs =' c2x(KYT2_rs) ;
EXIT ;
END ;

RETURN ;

Modified on by EChan_pok

Rexx Sample: Generate/Create NOCV IMPORTER/EXPORTER key-encrypting key pair

EChan_pok Tags: kim csnbkyt2 nocv csnbkgn kyt2 krc2 kek ktb kgn csnbkim csnbkrc2 csnbktb ‎ 5,996 Views

/* Rexx */

/*-------------------------------------------------------------------*/
/* Use ICSF callable services to generate an IMPORTER/EXPORTER       */
/* key-encrypting key pair that can be used in NOCV processing.      */
/* DES NOCV key-encrypting keys are used to exchange keys with       */
/* systems that do not recognize CCA control vectors.                */
/*                                                                   */
/* For more information about NOCV key-encrypting keys (KEKs), see   */
/* Chapter 2 of the z/OS ICSF Application Programmer's Guide.        */
/*-------------------------------------------------------------------*/
/* This sample testcase will:                                        */
/* 1. Call Key Token Build (KTB) to build skeleton KEKs with the     */
/*     NOCV flag on.                                                 */
/* 2. Call Key Generate (KGN) to generate an operational/exportable */
/*     OPEX form of the key pair.                                    */
/* 3. Call Key Import (KIM) to unwrap the generated key from         */
/*     encryption under the KEK to encryption under the master key. */
/* 4. Add both operational keys to the CKDS under key labels         */
/*     'SAMPLE.NOCV.IMPORTER' and 'SAMPLE.NOCV.EXPORTER'.            */
/* 5. Call Key Test2 (KYT2) to generate a key check value for both   */
/*     keys to verify that their clear key value matches.            */
/*                                                                   */
/* NOTE: This sample assumes 'SAMPLE.IMPORTER' and 'SAMPLE.EXPORTER' */
/*       are existing key labels of complementary key-encrypting     */
/*       keys in the CKDS.                                           */
/*                                                                   */
/* For more information on the callable services used in this        */
/* sample, see the z/OS ICSF Application Programmer's Guide.         */
/*-------------------------------------------------------------------*/

/*-------------------------------------------------------------------*/
/* Key Token Build                                                   */
/* - Call KTB to build skeleton IMPORTER and EXPORTER key tokens     */
/*   with NOCV flag on.                                              */
/*-------------------------------------------------------------------*/
rule_array_count = '00000002'x
rule_array = 'INTERNAL'||'NOCV-KEK'

key_type = 'IMPORTER'
CALL KTB
skeleton_NOCV_IMPORTER = KTB_key_token /* save skeleton token */

key_type = 'EXPORTER'
CALL KTB
skeleton_NOCV_EXPORTER = KTB_key_token /* save skeleton token */

SAY
/*-------------------------------------------------------------------*/
/* Key Generate                                                      */
/* - Call KGN to generate an IMPORTER/EXPORTER key pair.             */
/*   A random key value will be generated.                           */
/*   Both keys will have the same key value.                         */
/*                                                                   */
/* - generated_key_1 will be an operational NOCV IMPORTER            */
/*     If key_type_1 is TOKEN the control vector supplied in the     */
/*     generated_key_1 parameter is examined to determine the        */
/*     key type. The NOCV flag, if on, will be propagated to the     */
/*     generated key token.                                          */
/* - generated_key_2 will be an exportable EXPORTER                  */
/*     The NOCV flag will NOT be propagated to the generated token. */
/*     The NOCV flag can be turned on later in Key Import.           */
/*-------------------------------------------------------------------*/

/* initialize parameter list */
KGN_rc = 'FFFFFFFF'x
KGN_rs = 'FFFFFFFF'x
exit_data_length = '00000000'x
exit_data        = '' ;
key_form   = 'OPEX'
key_length = 'KEYLN16 '
key_type_1 = 'TOKEN   '
key_type_2 = 'EXPORTER'
kek_identifier_1 = ''
kek_identifier_2 = left('SAMPLE.EXPORTER',64)
generated_key_1 = skeleton_NOCV_IMPORTER /* skeleton NOCV IMPORTER
                                              from KTB               */
generated_key_2 = copies('00'x,64)

/* CALL CSNBKGN */
ADDRESS LINKPGM 'CSNBKGN' ,
                'KGN_rc' ,
                'KGN_rs' ,
                'exit_data_length' ,
                'exit_data' ,
                'key_form' ,
                'key_length' ,
                'key_type_1' ,
                'key_type_2' ,
                'kek_identifier_1' ,
                'kek_identifier_2' ,
                'generated_key_1' ,
                'generated_key_2' ;

SAY 'KGN rc =' c2x(KGN_rc) 'rs =' c2x(KGN_rs)
IF KGN_rc /= '00000000'x THEN
DO
SAY 'KGN failed'
EXIT
END
ELSE
DO
/* generated key 1 */
SAY 'generated key 1:' key_type_1
SAY c2x(substr(generated_key_1, 1,32))
SAY c2x(substr(generated_key_1,33,32))
/* generated key 2 */
SAY
SAY 'generated key 2:' key_type_2
SAY c2x(substr(generated_key_2, 1,32))
SAY c2x(substr(generated_key_2,33,32))
END

SAY
/*-------------------------------------------------------------------*/
/* Key Import                                                        */
/* - Call KIM to unwrap generated_key_2 from encryption under the    */
/*   KEK to encryption under the DES master key.                     */
/* - If key_type is IMPORTER or EXPORTER and a valid KEK with        */
/*   matching key type is passed in the target_key_identifier field, */
/*   the NOCV flag, if on, will be propagated to the imported key    */
/*   token.                                                          */
/*-------------------------------------------------------------------*/

/* initialize parameter list */
KIM_rc = 'FFFFFFFF'x
KIM_rs = 'FFFFFFFF'x
exit_data_length = '00000000'x
exit_data        = '' ;
key_type = key_type_2   /* key_type = EXPORTER from KGN */
source_key_identifier   = generated_key_2
importer_kek_identifier = left('SAMPLE.IMPORTER',64)
target_key_identifier   = skeleton_NOCV_EXPORTER /* skeleton NOCV
                                                   EXPORTER from KTB */
/* CALL CSNBKIM */
ADDRESS LINKPGM 'CSNBKIM' ,
                'KIM_rc' ,
                'KIM_rs' ,
                'exit_data_length' ,
                'exit_data' ,
                'key_type' ,
                'source_key_identifier' ,
                'importer_kek_identifier' ,
                'target_key_identifier' ;

SAY 'KIM rc =' c2x(KIM_rc) 'rs =' c2x(KIM_rs)
IF KIM_rc /= '00000000'x THEN
DO
SAY 'KIM failed'
EXIT
END
ELSE
DO
SAY 'imported target key identifier:'
SAY c2x(substr(target_key_identifier, 1,32))
SAY c2x(substr(target_key_identifier,33,32))
END

SAY
/*-------------------------------------------------------------------*/
/* Write both operational keys to the CKDS. */
/*-------------------------------------------------------------------*/
key_label = left('SAMPLE.NOCV.IMPORTER',64)
key_token_length = '00000040'x
key_token = generated_key_1 /* from KGN */
CALL KRC2

key_label = left('SAMPLE.NOCV.EXPORTER',64)
key_token_length = '00000040'x
key_token = target_key_identifier /* from KIM */
CALL KRC2

/*-------------------------------------------------------------------*/
/* Call Key Test2 to verify that the key check values match. */
/*-------------------------------------------------------------------*/
key_identifier_length = '00000040'x
key_identifier = left('SAMPLE.NOCV.IMPORTER',64) ;
CALL KYT2 ;
SAY 'VP -' c2x(vp)
key_identifier = left('SAMPLE.NOCV.EXPORTER',64) ;
CALL KYT2 ;
SAY 'VP -' c2x(vp)

EXIT

/*-------------------------------------------------------------------*/
/* Key Token Build - CSNBKTB */
/*-------------------------------------------------------------------*/
KTB:

/* initialize parameter list */
KTB_rc = 'FFFFFFFF'x
KTB_rs = 'FFFFFFFF'x
exit_data_length = '00000000'x
exit_data      = ''
KTB_key_token = copies('00'x,64)
key_value      = copies('00'x,16)
master_key_vn = '00000000'x
key_register_number   = 'ignored'
token_data_1   = 'ignored'
control_vector = copies('00'x,16)
initialization_vector = 'ignored'
pad_character = '00000000'x
crypto_period_start   = 'ignored'
master_key_vp = copies('00'x,8)

/* CALL CSNBKTB */
ADDRESS LINKPGM 'CSNBKTB' ,
                'KTB_rc' ,
                'KTB_rs' ,
                'exit_data_length' ,
                'exit_data' ,
                'KTB_key_token' ,
                'key_type' ,
                'rule_array_count' ,
                'rule_array' ,
                'key_value' ,
                'master_key_vn' ,
                'key_register_number' ,
                'token_data_1' ,
                'control_vector' ,
                'initialization_vector' ,
                'pad_character' ,
                'crypto_period_start' ,
                'master_key_vp' ;

SAY 'KTB rc =' c2x(KTB_rc) 'rs =' c2x(KTB_rs)
IF KTB_rc /= '00000000'x THEN
DO
SAY 'KTB failed'
EXIT
END
ELSE
DO
/* skeleton token */
SAY 'skeleton token:' key_type
SAY c2x(substr(KTB_key_token, 1,32))
SAY c2x(substr(KTB_key_token,33,32))
END ;

RETURN

/*-------------------------------------------------------------------*/
/* CKDS Key Record Create2 - CSNBKRC2 */
/*-------------------------------------------------------------------*/
KRC2:

/* initialize parameter list */
KRC2_rc = 'FFFFFFFF'x
KRC2_rs = 'FFFFFFFF'x
exit_data_length = '00000000'x
exit_data = ''
rule_array_count = '00000000'x
rule_array = '' ;

/* CALL CSNBKRC2 */
ADDRESS LINKPGM 'CSNBKRC2' ,
                'KRC2_rc' ,
                'KRC2_rs' ,
                'exit_data_length' ,
                'exit_data' ,
                'rule_array_count' ,
                'rule_array' ,
                'key_label' ,
                'key_token_length' ,
                'key_token' ;

SAY 'KRC2 rc =' c2x(KRC2_rc) 'rs =' c2x(KRC2_rs)
IF KRC2_rs /= '00000000'x THEN
DO
SAY 'KRC2 failed'
SAY 'KEY LABEL -' key_label
EXIT ;
END

RETURN

/*-------------------------------------------------------------------*/
/* Key Test2 - CSNBKYT2 */
/*-------------------------------------------------------------------*/
KYT2:

/* initialize parameter list */
KYT2_rc = 'FFFFFFFF'x
KYT2_rs = 'FFFFFFFF'x
exit_data_length = '00000000'x
exit_data        = ''
rule_array_count = '00000003'x
rule_array       = 'DES     '||'GENERATE'||'ENC-ZERO'
kek_identifier_length = '00000000'x
kek_identifier        = ''
reserved_length = '00000000'x
reserved = ''
vp_length = '00000008'x
vp        = copies('00'x,8) ;

/* CALL CSNBKYT2 */
ADDRESS LINKPGM 'CSNBKYT2' ,
                'KYT2_rc' ,
                'KYT2_rs' ,
                'exit_data_length' ,
                'exit_data' ,
                'rule_array_count' ,
                'rule_array' ,
                'key_identifier_length' ,
                'key_identifier' ,
                'kek_identifier_length' ,
                'kek_identifier' ,
                'reserved_length' ,
                'reserved' ,
                'vp_length' ,
                'vp' ;

SAY 'KYT2 rc =' c2x(KYT2_rc) 'rs =' c2x(KYT2_rs)
IF KYT2_rs /= '00000000'x THEN
DO
SAY 'KYT2 failed'
SAY 'KEY LABEL -' strip(key_identifier)

EXIT
END

RETURN

Modified on by EChan_pok

Feed for Blog Entries

Blogs