[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

RE: CTIL Documentation

Sorry about the delay in updating this document; you are correct in assuming
it is out of date.  I would suggest that you follow the actual code in the
provided sm_free3.cpp/h source files.  We will update the document SOON
(lots of items on our task list).
A am adding an excerpt from an e-mail I sent to someone earlier describing
the newer Encrypt/Decyrpt operations that are probably confusing you.
Bob Colestock
<<<<<<<<e-mail excerpt >>>>>>>>
Oops; sorry, I am the author of this new functionality. I never did update
the CTIL document. This will now be done in the next few months. In the mean
time, the actual code demonstrating this functionality (not easy to
understand) is in "sm_Decrypt.cpp". You have probably already checked this
source and found it confusing. I am afraid even documentation will not help
you to understand this functionality.

This complexity is due to the intensly confusing array of choices in the CMS
specification when it comes to encryption operations. The logic you see
using the CTIL calls GREW OUT OF THE ORIGINAL confusing specification with
lots of ASN.1 choices. I have not had a chance to go back and isolate the
different choices (KARI, KTRI, KEK) out into individual CSM_MsgToDecrypt
methods to avoid confusion. As it is, these choices are isolated by "if"
statements, if you read carefully. I am not sure why you need such detailed
CTIL documentation, but if you are attempting to use these functions
directly, good luck. If you are interested in writing a CTIL, simply follow
the details in sm_free3.cpp; there are no complex individual operations
being performed by any individual call.

The actual operations described in the CMS specification are split in order
to hide the actual algorithm details (e.g. initialization vectors and byte
counts, etc.) from the general higher level code. The calls are grouped
according to the CMS encryption mechanism: kari, ktri, kek. (If this does
not make any sense, you will have to carefully read the CMS specification
and understand fully the implications of Key Agreement(kari), Key
Transfer(ktri), and Key Encryption Key(KEK) before delving into these
calls). You can determine the grouping from the "sm_Decrypt.cpp" source.

If you let me know the what specifically you need in the way of information,
I can tailor the documentation to assist (unfortunately this is not a
priority; since all of these details are hidden from most users/developers
it has been neglected, also it is not an easy topic to present). If you
clearly understand the ASN.1 encryption choices, the source should be
somewhat self-explanatory.

There are a number of diagrams explaining these operations (not the actual
calls, yet) on the web site. Most of the diagrams are in the Implementor's

Below is a brief explanation of this functionality:

Starting with Encryption operations (there is a precise diagram of this
operation in the guide document; I can send this to you if you cannot locate

for KeyAgreement (kari) which includes Diffie-hellmann, Fortezza KEA
algorithms, other public/private key encryptions where both the originator's
private key and recipient's public key are necessary to encrypt:

<<<< from sm_encrypt.cpp, CSM_MsgToEncrypt::AddRecipient(...)>>>

if (pInst->AccessTokenInterface()->SMTI_IsKeyAgreement())

<<<< The CTIL indicates that this operation is a KeyAgreement operation>>>>

// SECOND, generate an appropriately sized initialization vector for 

// KeyWrap to be processed in the KeyAgree key generation call.

// NOTE: this may be overridden if the KARI params are present and

// already contain an IV; the KARI IV will be used. If not already

// set, the default KeyWrap Alg will be set.

pTmpIV = pInstKeyWrap->AccessTokenInterface()->SMTI_GenerateKeyWrapIV(

lKekLength, &WrapAlg);

<<<< The "GenerateKeyWrapIV(...)" call will selectively load the WrapAlg
with the appropriate parameters; they may have to be set by the application
based on the actual recipient. The initialization vector length is returned
(usaully dictated by the algorithm itself) to be used in follow on
calculations. The initialization vector is usually a random number, returned
in the "pTmpIV" buffer. >>>>

// THIRD, generate KeyAgreement; may use settings determined from 

// above logic extracted from another RI/RIKEY OR create new 

// values for UKM and Paramate IV.

if (!this->m_bSharedUkms) // FORCE new dynamic gen for ESDH...


<<<< This shared UserKeyMaterial(ukm) is a nightmare; basically the CMS
authors wanted the ability to only send 1 single 1k byte or so random number
(for the encryption algorithms) for multiple recipients instead of the
traditional mechanism where a random number is generated for each user (each
RecipientInfo normally has its own UKM, OID, and encrypted token). This
requires our logic and CTIL to re-use an existing UKM from another recipient
already processed if present, of the same algorithm, and the same parameters
(for DH and KEA). This "ClearDynamicKey()" operation handles the EPHEMERAL
Diffie-Hellmann algorithm, where the encryption is more difficult to break.
This call allows the application to selectively inform the CTIL to clear the
ESDH private key generated on a previous call (basically a reset, see CMS
specification and associated RFCs on ESDH). >>>>


pbufRecipKey, pRecip->m_pbufParams, 

pRecip->m_pUkmBuf, pTmpIV, m_pKeyWrapOID, &bufKeyAgree, lKekLength));

<<<< This call actually produces the key result to be used to encrypt the
token; this computation is based on the Originator's private key and the
Recipient's public key, the UKM, inialization vector. All of these details
apply to any KARI algorithm; lengths vary. (See DH specification) >>>>

// FOURTH, Call the Key Wrap encryption method.


&pRecip->m_bufEMEK, &contentEncryptParams, &bufKeyAgree, pTmpIV));

<<<< This call actually encrypts the token data, "bufMEK", with the previous
key agreement buffer, "bufKeyAgree", and stores the encrypted token in
"pRecip->m_bufEMEK". Again the initialization vector is necessary due to the
algorithm described in the CMS specification (it is used in the hash, etc.
bit-manipulations, lots of details). This call performs the CONTENT
ENCRYPTION operation using the Agreed Upon Key calculated previously. >>>>

// Override the parameters for Key Wrap, not necessary according to 

// CMS. (Encrypt always loads IV in parameters for 3DES).

if (pRecip->m_pbufParams) // Previously used for processing.

delete pRecip->m_pbufParams;

ENCODE_BUF(&WrapAlg, pRecip->m_pbufParams);

<<< This final call is part of the protocol for the CMS RecipientInfo
interpretation of KARI RIs (see CMS specification). >>>






Let me know if this is of any help. This is basically what I will write for
all 3 types (kari, ktri, kek) for both encryption and decryption to
demonstrate how to use the CTIL for encryption operations. As you can see,
these are not simple operations; they are not clear unless the reader has a
very clear understanding of the CMS specification, each algorithm type being
defined (e.g. DH, KEA, RSA, 3DES, RC2), and the SFL itself (which admitedly
could be a bit clearer in its implementation). I can provide all of the
references mentioned above as well as the diagrams that help explain the
encryption choices. These diagrams were written as part of an internal
training course, then moved to the GUIDE as a place holder until we could
get to more detailed documentation. They are quite clear on the operations
and the use of logins, etc. from the CTIL.


Bob Colestock

-----Original Message-----
From: David Sowinski [mailto:sowinski@xxxxxxxxxxxxxxx]
Sent: Thursday, July 27, 2000 7:04 PM
To: imc-sfl@xxxxxxx
Subject: CTIL Documentation

I am trying to write a CTIL based on our CDK (Cryptographic Development
Kit.) I am using the CTIL API document (version 1.1 dated 5 August 1999) and
the sample CTILs as reference material. I notice in the example CTILs that
there are numerous SMTI_* member functions declared and implemented. The
CTIL API document, however, does not make any mention of such functions. Is
this because the CTIL API document has not been touched in nearly a year and
requires updating? If this is the case, when can a new version of the CTIL
API document be expected?

David W. Sowinski, M.Sc.              Email: sowinski@xxxxxxxxxxxxxxx
Director of Product R&D               Voice: 847-405-0500 (Deerfield)
Information Security Corporation             708-445-1704 (Oak Park)
1011 Lake Street, Suite 212           Fax:   708-445-9705
Oak Park, IL 60301                    WWW:   http://www.infoseccorp.com