CCA Release 2.54
External A key that is either in the clear, or is encrypted (wrapped) by some
key-encrypting key other than the master key. Generally, when a
key is to be transported from place to place, or is to be held for a
significant period of time, it is required to encrypt the key with a
transport key. A key wrapped by a transport key-encrypting key is
designated external.
RSA public-keys are not encrypted values (in PKA96), and when not
accompanied by private-key information, are retained in an external
key-token.
Internal key-tokens can be stored in a file that is maintained by the directory server.
These key tokens are referenced by use of a key label. A key label is an
alphanumeric string that you place in a variable and reference with a verb
parameter.
Verb descriptions specify how you can provide a key using these terms:
Key token The variable must contain a proper key-token structure.
Key label The variable must contain a key label string used to locate a key
record in key storage.
Key identifier The variable must contain either a key token or a key label. The
first byte in the variable defines if the variable contains a key token
or a key label. When the first byte is in the range X'20' through
X'FE', the variable is processed as a key label. There are
additional restrictions on the value of a key label. See “Key-Label
Content” on page 7-2. The first byte in all key-token structures is in
the range of X'01' to X'1F'.X'00' indicates a DES null key-token.
X'FF' as the first byte of a key-related variable passed to the API
raises an error condition.
How the Verbs Are Organized in the Remainder of the Book
Now that you have a basic understanding of the API, you can find these topics in
the remainder of the book:
Chapter 2, “CCA Node-Management and Access-Control” explains how the
cryptographic engine and the rest of the cryptographic node is administered.
There are four topics:
– Access-control administration
– Controlling the cryptographic facility
– Multi-Coprocessor support
– Master-key administration.
Keeping cryptographic keys private or secret can be accomplished by retaining
them in secure hardware. Keeping the keys in secure hardware can be
inconvenient or impossible if there are a large number of keys, or the key has
to be usable with more than one hardware device. In the CCA implementation,
a master key is used to encrypt (wrap) locally used keys. The master key itself
is securely installed within the cryptographic engine and cannot be retrieved as
an entity from the engine.
As you examine the verb descriptions throughout this book, you will see
reference to “Required Commands.” Almost all of the verbs request the
cryptographic engine (the “adapter” or “Coprocessor”) to perform one or more
Chapter 1. Introduction to Programming for the IBM CCA 1-13