Draft 0.1 P. Rogaway Limit distribution until matures IBM June 1, 1994 Generic Cryptographic Service Application Program Interface Abstract This Generic Cryptographic Service Application Program Interface (GCS-API) provides callers with a uniform means to access an arbitrary library of cryptographic transforms. Security-aware callers may request specific transforms, while security-unaware callers need not do so. This specification may be complemented by the following additional materials: - Language-specific bindings - A registry of mechanisms and mechanism-types - Definitions of token formats and other low-level details Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Goals and Non-Goals . . . . . . . . . . . . . . . . . . . . . 2 1.2. Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . 3 1.2.1. Transforms . . . . . . . . . . . . . . . . . . . . . . . . 4 1.2.2. Cryptographic Contexts . . . . . . . . . . . . . . . . . . 5 1.2.3. Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.2.4. Quality of Service . . . . . . . . . . . . . . . . . . . . 6 1.2.5. Defaults and Security Awareness . . . . . . . . . . . . . 6 1.2.6. Naming . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2. Interface Descriptions . . . . . . . . . . . . . . . . . . . . 7 2.1. Key Management Services . . . . . . . . . . . . . . . . . . . 7 2.1.1. GCS_Init_key . . . . . . . . . . . . . . . . . . . . . . . 7 2.1.2. GCS_Inquire_key . . . . . . . . . . . . . . . . . . . . . 10 2.1.3. GCS_Annotate_key . . . . . . . . . . . . . . . . . . . . . 11 2.1.4. GCS_Retrieve_key . . . . . . . . . . . . . . . . . . . . . 12 2.1.5. GCS_Install_key . . . . . . . . . . . . . . . . . . . . . 13 2.1.6. GCS_Stringify_key . . . . . . . . . . . . . . . . . . . . 15 2.1.7. GCS_Restore_key . . . . . . . . . . . . . . . . . . . . . 16 2.2. Context Management Services . . . . . . . . . . . . . . . . . 17 2.2.1. GCS_Init_context . . . . . . . . . . . . . . . . . . . . . 17 2.2.2. GCS_Inquire_context . . . . . . . . . . . . . . . . . . . 18 2.2.3. GCS_Stringify_context . . . . . . . . . . . . . . . . . . 19 2.2.4. GCS_Restore_context . . . . . . . . . . . . . . . . . . . 20 2.3. Cryptographic Transformation Services . . . . . . . . . . . . 21 2.3.1. GCS_Transform . . . . . . . . . . . . . . . . . . . . . . 21 Rogaway [Page 1] Draft 0.1 Generic Cryptographic Interface June 1, 1994 2.4. Support Calls . . . . . . . . . . . . . . . . . . . . . . . . 23 2.4.1. GCS_Indicate_transforms . . . . . . . . . . . . . . . . . 23 2.4.2. GCS_Describe_transform . . . . . . . . . . . . . . . . . . 24 2.4.3. GCS_Display_status . . . . . . . . . . . . . . . . . . . . 24 2.4.4. GCS_Display_oid_info . . . . . . . . . . . . . . . . . . . 25 2.4.5. GCS_Release_key . . . . . . . . . . . . . . . . . . . . . 26 2.4.6. GCS_Release_context . . . . . . . . . . . . . . . . . . . 26 2.4.7. GCS_Release_buffer . . . . . . . . . . . . . . . . . . . . 26 2.4.8. GCS_Release_oid_set . . . . . . . . . . . . . . . . . . . 26 2.4.9. GCS_Release_qos_info . . . . . . . . . . . . . . . . . . . 26 2.4.10. GCS_Release_att_set . . . . . . . . . . . . . . . . . . . 27 3. Unresolved Issues . . . . . . . . . . . . . . . . . . . . . . . 27 4. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . 28 5. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28 6. Author's Address . . . . . . . . . . . . . . . . . . . . . . . 28 Appendix A: Mechanism-Independent Token Format . . . . . . . . . . 29 Appendix B: Initial Population of Mechanism-Types . . . . . . . . 29 1. Introduction The cryptographic services required in modern computer systems have usually been implemented repeatedly and disparately across the system's architecture. In general, there has been no agreed-upon encapsulation for a layer of cryptographic services. This lack has been one factor leading many computer systems to have redundant cryptographic implementations, a surfeit of poorly-performing ones, and a general under-utilization of needed cryptographic services. It is the purpose of this Generic Cryptographic Service Application Program Interface (GCS-API) to provide a simple and abstract interface for gaining access to virtually any cryptographic transformation. In this way a system's underlying cryptographic primitives can be collected up into a single logical repository which is accessed in a simple and standardized manner. 1.1. Goals It is impossible to know what cryptographic mechanisms will be important to whom, even a few years from now. Many important primitives may not even "look" cryptographic (e.g., universal hashing or polynomial interpolation). To be truly generic, a cryptographic interface must therefore refrain not only from specifying particular mechanisms, but even from attempting to exhaustively enumerate what these mechanisms are supposed to do. We therefore seek to provide an open-ended way to encapsulate an arbitrary set of cryptographic mechanisms, each of arbitrary Rogaway [Page 2] Draft 0.1 Generic Cryptographic Interface June 1, 1994 functionality. The envisaged API must be mechanism-neutral: it should neither favor nor excludes any particular mechanism. In a given implementation, the (unspecified) set of supported transformations should be able to evolve without any need for change to the API. The GCS-API must be simple and intuitive. It should be possible for a security-aware programmer to get at any mechanisms which is supported but, at the same time, a security-unaware programmer should be able to easily access cryptographic functionality without knowing mechanism details. Operations are to act on abstract data types. It must be possible to safely implement these abstract types in environments which do not directly provide opaque data types. The proposed API should be architecturally consistent with the GSS- API [2], and it should, furthermore, be useful as a means of implementing mechanisms supported under the GSS-API. The use of GCS-API should not entail significant inefficiency over the caller requesting the underlying mechanism directly. This should be true even in the case of mechanisms requiring some particular style of key setup, as well as mechanisms whose efficient implementation requires the dynamic generation of (key-dependent) executable code. It must be possible to support statefull GCS-API mechanisms (for example, stream ciphers). It must be possible to use a multiplicity of (possibly statefull) mechanisms simultaneously. No attempt is made to endow GCS-API with verbs to manage the underlying cryptographic mechanisms themselves. In particular, how mechanisms get installed, enabled, disabled and de-installed is treated as out-of-scope. Such operations are best added should GCS- API be elaborated into a "framework," with GCS-API as the interface out of the top-end, and a lower-layer Service Provider Interface (SPI) provided at the bottom-end. Into the SPI would particular mechanisms be plugged. Following the lead of GSS-API, we here specify only the the top-end interface. 1.2. Basic Concepts The GCS-API provides access to a cryptographic subsystem comprising a set of cryptographic mechanisms, runtime data structures and logic, and hardware/software for storage of keys and state. We begin by describing the mechanisms. Rogaway [Page 3] Draft 0.1 Generic Cryptographic Interface June 1, 1994 1.2.1. Transforms We will interchangeably use the words "mechanisms" and "transforms" for the maps exported via the GCS-API. Transforms are (possibly probabilistic) functions which may side-effect associated state. Formally, a transform is a probabilistic map from an integer code, an "old state", and zero or more (input) strings, to a "new state" and zero or more (output) strings. Many transforms leave the state unchanged. In this case they are called "stateless"; others are called "statefull." Many transforms generate a fixed output for a given input; such transforms are called "deterministic." Transforms may be low-level primitives (e.g., the DES algorithm itself) or higher-level constructs (e.g., DES in CBC-mode using a random initialization vector, together with a DES-CBC-MAC.) But it is intended that each transform be a conceptually-specific mapping. In particular, different modes of operation should generally be supported as different transforms. A transform may be specialized in a limited way by giving the transform an integer "code." Use of this is code is generally frowned upon. It is recommended that high-level maps perform mechanism-specific key separation. The state of a transform is often used to store a key. Statefull transforms will often use the state to store a sequence number, say, or information such as how many bytes have been acted on by the transform so far. A tranform's state may contain further details, like the time at which the use of the transform on this key will "expire." Once a transform is specialized to a particular in-coming state it is called a "keyed-transform." In the GCS-API, all cryptographic transforms are effected as keyed-transforms. In the GCS-API, all keyed transforms are carried out using a single verb, GCS_Transform. Calling this computes the underlying map and possibly mutates the associated state. In general, GCS transforms are not intended to perform communication outside of the boundary of a given cryptographic module. As such, cryptographic operations which typically require communication (including key distribution) are imagined to be implemented over the GCS-API, using supported transforms. Some key-management operations supported by the GCS-API may perform communication (to retrieve or establish a principal's key), but these operations are not considered GCS-transforms. To allow callers to access mechanisms in a reasonably "generic" fashion, each transform must have an associated "transform type." A transform type is given by an Object Identifier (OID). Associated to each transform type is a "signature" which specifies the number of input strings and output strings for each transform of this transform Rogaway [Page 4] Draft 0.1 Generic Cryptographic Interface June 1, 1994 type. All transforms of a given transform type must have the same signature. 1.2.2. Cryptographic Contexts To use a transform, one creates a "context" by naming the desired transform (or by requesting a default; see 1.2.5) and then filling in the transform's initial state. These actions result in a handle to a keyed-transform. A cryptographic context is an instance of a keyed- transform. The state of the context is modified only as a side effect of performing the transform on its handle. In the unlikely event that a mechanism wishes to support a notion of explicitly changing the transform's state without performing the transform, this operation can be implemented by a "dummy" call to the transform. 1.2.3. Keys While the state of a transform may be arbitrary, it will often be the case that a key as an essential part. Keys are abstract entities to the GCS caller, actions on which we now sketch. One can create a key for a given mechanism by calling GCS_Init_key. It is the caller's choice either to fill in the initial initial value of the key or to allow the the Cryptographic Module itself to provide the key with an initial value (e.g., by generating it at random). The key created by GCS_Init_key is returned in the form of a key- handle which references the key. The key handle can be passed in to help initialize a context. Keys can be retrieved using GCS_Retrieve_key, which returns a key- handle whose key is associated to the named principal. The reverse operation, GCS_Install_key, serves to bind a key to a named principal. Keys can be created by "restoring" a byte string, via GCS_Restore_key. The operation returns a handle to the newly-created key. This byte string should have been created earlier by a corresponding call to GCS_Stringify_key, which returns a string based on the contents of the key associated with the provided handle. Once one has a key handle, one can annotate the associated key as having some particular set of "attributes." This is done by a call to GCS_Annotate_key. Each key-attribute (an OID) has an associated value (an integer). Any such list of (attribute, value)-pairs can be supported. Control vectors, as in the IBM Common Cryptographic Architecture, are a special case. It is the responsibility of each Rogaway [Page 5] Draft 0.1 Generic Cryptographic Interface June 1, 1994 transform to enforce the presence or absence of annotations which are deemed necessary. 1.2.4. Quality of Service As we have mentioned, each transform must specify its transform type. In turn, each transform type has associated to it a set of attributes, the purpose of which is to describe the possible "properties" for transforms of this type. As an example, whether or not an encryption scheme is malleable is a property of an asymmetric encryption; the adversary's probability of producing a forged message is a property of a message authentication code. The mechanism-attributes described here should not be confused with key-attributes, described in Section 1.2.3. In a given implementation, each transform f of a certain mechanism type T has associated to it an (implementation-defined) set of tuples of the form (attribute, value). The attributes for f must be drawn from the set of attributes associated to T. It is not required that an implementation specify an (attribute, value) pair for every attribute allowed for mechanisms of type T. Each attribute is an Object Identifier (OID). Each value is an integer. Among the attributes which should be specified for a mechanism are ones describing the "quality of confidence" (QOC) that is deemed appropriate to place in the transform. It is recommended that quality-of-confidence values be integers drawn from a small range. All together, a given transform's transform-type and the set of (attribute, value)-pairs for the mechanisms defines the "quality of service" (QOS) for the mechanism. Callers can shop for a mechanism which support a given QOS by fishing through the list of (attribute, value)-pairs among mechanisms of the desired mechanism-type. This allows the choosing of a mechanisms in a reasonably generic fashion. 1.2.5. Defaults and Security Awareness Callers of GCS-API can be classified as "security unaware" (U) and "security aware" (A). There are several "types" of the former (U0, U1, U2). We now describe callers in order of increasing specificity in their knowledge of supported GCS mechanisms. The "type-unaware caller" (U0) uses a default FORWARD mechanism to protect a string and a default BACKWARD mechanism to recover it. Thus a GCS implementation must name a default FORWARD and BACKWARD transform. The signature of each of these must be: one string input Rogaway [Page 6] Draft 0.1 Generic Cryptographic Interface June 1, 1994 of arbitrary length, and one string output (of possibly greater length). The mechanism should accept keys of arbitrary length and content. It is required of any GCS-compliant implementation that for any key which is used to initialize both a context for the FORWARD mechanism and a context for the BACKWARD mechanism, if the BACKWARD mechanism is applied to the result of the FORWARD mechanism applied to a string x, then the result is the very same string x. An "attribute-unaware caller" (U1) knows the type of the mechanism he is after, and he knows the signature for mechanism of this type. The caller requests a mechanism by naming its mechanism type. What he gets back is a context which uses an implementation-defined default mechanism for that type. Thus, in addition to naming the default FORWARD and BACKWARD mechanism, a GCS implementation must name a default mechanism for each supported mechanism type. An "implementation-unaware caller" (U2) knows the exact quality of service he is after, but does not know the specific mechanism(s) which provide this QOS. Such a caller chooses among mechanisms by examining the QOS information which the GCS runtime provides for any supported mechanism. Once the caller has chosen a mechanism based on the QOS information provided, the caller looks, as far as GCS is concerned, exactly as though he were a mechanism-aware caller (i.e., the caller simply names the mechanism he has chosen when he initialize a context). A "security-aware" caller (A) knows the specific mechanism he wants, including its signature and any needed mechanism-specific details. 1.2.6. Naming The GCS-API avoids prescription of naming structures, treating the names transferred across the GCS-interface as opaque octet strings. The same naming consideration apply exactly as with GSS-API [2], so we omit further discussion. 2. Interface Description This section describes the GCS-API's service interface, dividing the calls into four groups. The calls of each group are indicated in Table 1. 2.1. Key Management Services These GCS-API calls provide the ability to manipulate cryptographic Rogaway [Page 7] Draft 0.1 Generic Cryptographic Interface June 1, 1994 keys. Included in this is the ability to create a key appropriate to a given mechanism and to provide the key with a specific value (GCS_Init_key). Also provided is a way to get mechanism-specific information about a key (GCS_Inquire_key) and the ability to associate key-specific information with a key (GCS_Annotate_key). Finally, we provide a means to look up a key for a given principal (GCS_Install_key) and a way to (permanently) associate a key with a named principal (GCS_Install_key). All of these operations are applicable to both symmetric and asymmetric keys, and many of the operations are applicable even when the "key" is not a true key at all (e.g., customizing the initial values for the registers in an SHA-like hash function). 2.1.1. GCS_Init_key Inputs: o mechanism OBJECT IDENTIFIER, -various defaults; see below o key_value OCTET STRING, -NULL to have automatically generated o key_length INTEGER -0=default length Outputs: o major_status INTEGER, o minor_status INTEGER, o output_key_handle OCTET STRING, Return major_status codes: o GCS_COMPLETE indicates that key has been created and a valid handle to it has been returned. o GCS_BAD_MECH indicates that the requested mechanism is not supported. o GCS_INSUFFICIENT_PRIVILEGE indicates that the caller lacked the authority to create a key for the indicated mechanisms. o GCS_BAD_KEY_VALUE indicates that the specified value of the key is not valid for the specified mechanism, or that it does not agree with the requested key length. o GCS_FAILURE indicates an unspecified failure to annotate the key. Rogaway [Page 8] Draft 0.1 Generic Cryptographic Interface June 1, 1994 Table 1: GCS-API Calls KEY MANAGEMENT GCS_Init_key Create and initialize a key GCS_Inquire_key Return information about a key GCS_Annotate_key Annotate a key with desired information GCS_Retrieve_key Look up and return a named principal's key GCS_Install_key Install a key for the named principal GCS_Stringify_key Pack a key into an exportable octet string GCS_Restore_key Unpack the above octet string and make key CONTEXT MANAGEMENT GCS_Init_context Create crypto context and fill in initial state GCS_Inquire_context Return information about cryptographic context GCS_Stringify_context Pack a context into an exportable octet string GCS_Restore_context Unpack the above octet string and make context PERFORMING TRANSFORMS GCS_Transform Perform a transform and side-effect the state SUPPORT CALLS GCS_Indicate_transforms Returns list of mechanisms matching the query GCS_Describe_transform Returns QOS-information about a transform GCS_Display_status Translate status codes to printable form GCS_Display_oid_info Translates xform/xform type to printable form GCS_Release_key Free storage of an unneeded key GCS_Release_context Free storage of an unneeded context GCS_Release_buffer Free storage of a printable string GCS_Release_oid_set Free storage of an OID set GCS_Release_qos_info Free storage of a QOS descriptor GCS_Release_att_set Free storage of an key-attributes descriptor Rogaway [Page 9] Draft 0.1 Generic Cryptographic Interface June 1, 1994 Description: GCS_Init_key() is used to create a cryptographic key appropriate to a given mechanism. The caller specifies the desired mechanism (but see below), a value for the key (but see below), and an integer length. A key is then created whose value is determined as a mechanism- specific (possibly probabilistic) function of the key_value and key_length. While it is anticipated that key_length will usually represent the key length, other mechanism-specific uses are permitted. A caller may specify FORWARD for the mechanism, in which case a locally-defined default FORWARD mechanism is used. A caller may specify BACKWARD for the mechanism, in which case a locally-defined default BACKWARD mechanism is used. A caller may specify the OID of a mechanism type rather than of a mechanism itself, in which case a locally-defined default mechanism of that type is the mechanism which is used. A key_value of NULL is used to avoid specifying a specific key; in this case, the cryptographic subsystem should select a random key of the requested type and length, or else take other, mechanism- appropriate behavior. A length parameter of 0 should be used to indicate a default length value for the given mechanism. GCS_Init_key returns a handle to the newly-created key structure. It returns mechanism-specific status information in the form of the integer minor_status. Additional information of interest to the caller may be available by way of the mechanism having initialized some set of (key-attribute, key-attribute-values) pairs. These pairs can be retrieved using GCS_Inquire_key. The GCS_Init_key call is made by both security-aware and security- unaware callers. Security-unaware callers use default values. 2.1.2. GCS_Inquire_key Input: o key_handle OCTET STRING, Outputs: o major_status INTEGER, o minor_status INTEGER, Rogaway [Page 10] Draft 0.1 Generic Cryptographic Interface June 1, 1994 o key_attributes_set SET OF AttributeValuePairs Return major_status codes: o GCS_COMPLETE indicates that key_attributes_set has been filled up with the requested information. o GCS_BAD_KEY indicates that the provided key_handle does not reference a valid key. o GCS_FAILURE indicates an unspecified failure to retrieve the key's attributes. Description: GCS_Inquire_key() is used to obtain the set of (key-attribute, key- attribute-value) pairs for a given key. The AttributeValuePairs are a SET each element of which consists of an OBJECT IDENTIFIER and an INTEGER. It is intended that key_attributes be used to hold a "type" or "usage characteristic" of a key, while the corresponding value gives the value of that type or the specific characteristic. This call is made only by security-aware callers. 2.1.3. GCS_Annotate_key Inputs: o key_handle OCTET STRING, o key_attribute OBJECT IDENTIFIER, o key_attribute_value INTEGER Outputs: o major_status INTEGER, o minor_status INTEGER Return major_status codes: o GCS_COMPLETE indicates that the requested key_attribute_value is now associated to the given key_attribute. o GCS_BAD_KEY indicates that the provided key_handle does not reference a valid key. Rogaway [Page 11] Draft 0.1 Generic Cryptographic Interface June 1, 1994 o GCS_BAD_KEY_ATTRIBUTE indicates that the provided key attribute is invalid. o GCS_BAD_KEY_ATTRIBUTE_VALUE indicates that the requested attribute value in invalid. o GCS_INSUFFICIENT_PRIVILEGE indicates that the caller lacked the authority to make the requested change to the key attribute. o GCS_FAILURE indicates an unspecified failure to annotate the key. Description: The GCS_Annotate_key() call is used to modify the value of a given key-attribute. The caller names the attribute he wants to modify and the value he wants to give it. To modify several attributes of a given key, make multiple calls to GCS_Annotate_key(). This call is made only by security-aware callers. 2.1.4. GCS_Retrieve_key Inputs: o principal_name INTERNAL NAME, -NULL for locally-determined default o which_key INTEGER, -to indicate public key, private key, etc. o certify INTEGER - 0=be certain of key binding; -1=if unnecessary Outputs: o major_status INTEGER, o minor_status INTEGER, o key_handle OCTET STRING Return major_status codes: o GCS_COMPLETE indicates that the requested information has been found and returned in the structure referenced by the key_handle. o GCS_UNKNOWN_PRINCIPAL indicates that there is no entity of the specified name for which a key of the specified type is known. o GCS_BAD_ARGUMENT indicates that the principal_name is syntactically incorrect or which_key is unknown or the certify value Rogaway [Page 12] Draft 0.1 Generic Cryptographic Interface June 1, 1994 is unknown. o GCS_CANT_CERTIFY indicates that the principal has a registered key, but that the key binding does not meet the specified certification requirements. o GCS_INSUFFICIENT_PRIVILEGE indicates the key could not be retrieved because the caller lacks the authority to obtain the requested key. o GCS_FAILURE indicates some failure not further specified. Description: The GCS_Get_key() call is used to request a key for the given principal. A principal may have several keys, and indeed several different types of keys. Which one of these keys is requested depends on the parameter which_key. By convention, a value of which_key=1 should be used to request the "default" private key of the named principal. A value of which_key=2 is used to request a "default" public key for the named principal. A value of which_key=0 should result in implementation-specific default behavior. More elaborate key types may be specified, with other values having interpretations which are implementation-dependent. The value of certify is used to inform the cryptographic module as to the amount of assurance that the caller expects to have that the returned key really is bound to the named principal. A value of 0 indicates that the caller wants "complete assurance" that the returned key belongs to the named principal, and a value of -1 indicates that the caller does not seek any such assurance. Other values have interpretations which are implementation-dependent. If a principal name is not explicitly given, the local system is expected to determine a reasonable default, probably by examining the local security context for the caller. This call is made by both security-aware and security-unaware callers. Security-unaware callers use only values of 0, 1 or 2 for which_key. 2.1.5. GCS_Install_key Inputs: o principal_name INTERNAL NAME, -NULL for locally-determined default Rogaway [Page 13] Draft 0.1 Generic Cryptographic Interface June 1, 1994 o which_key INTEGER, -to indicate public key, private key, etc. o key_handle OCTET STRING Outputs: o major_status INTEGER, o minor_status INTEGER Return major_status codes: o GCS_COMPLETE indicates that the key has been successfully installed into the system, associated with the given principal's name. o GCS_BAD_ARGUMENT indicates that the principal_name is syntactically incorrect or type_of_key is unknown or the certify value is unknown or the key_handle does not point to a valid key or the key on the key_handle is incompatible with the type of key which_key specifies. o GCS_INSUFFICIENT_PRIVILEGE indicates the key could not be bound to the principal because the caller lacks the authority to do this operation. o GCS_FAILURE indicates some failure not further specified. Description: The GCS_Install_key() call is used to bind a principal name to a key. Depending on the value of which_key, this "key" may be a public key, a private key, a set of keys, etc.. It is permissible (and recommended) that the key type shall be determined by key attributes, in which case the caller should use a value of which_key=0. This operations is intended to side-effect the system in a way visible across invocations of GCS. In particular, a call to GCS_Install_key followed by a subsequent invocation of GCS_Retrieve_key should obtain a key functionally equivalent to that which was previously installed, unless some out-of-band action caused the key to change in between. This call is made by both security-aware and security-unaware callers. Security-unaware callers use only a value of 0 for which_key. Rogaway [Page 14] Draft 0.1 Generic Cryptographic Interface June 1, 1994 2.1.6. GCS_Stringify_key Inputs: o key_handle OCTET STRING, o how_to_stringify INTEGER -0 for default, 1 for printable, ... Outputs: o major_status INTEGER, o minor_status INTEGER, o string_form_of_key OCTET STRING Return major_status codes: o GCS_COMPLETE indicates that the request has been successfully carried out, and the value of string_form_of_key can be used to resurrect the key referenced on the key_handle. o GCS_BAD_KEY indicates that the provided key_handle does not reference a valid key o GCS_INSUFFICIENT_PRIVILEGE indicates that the caller lacks the privilege to perform the requested operation. o GCS_FAILURE indicates a general failure unspecified at the level of the GCS-API. Description: This call takes the key referenced by key_handle and performs necessary operations to "pack" it into an exportable representation. This representation does not necessarily have to include a complete description of the key; for example, the operation could side-effect system state and return only a pointer to a key which is cached within protected hardware. The caller is expected to save the string_form_of_key but not to modify it. It is required that, under normal operational circumstances, if this string is subsequently provided to GCS_Restore_key, an operationally equivalent key shall be produced to that initially on the handle. In general, key attributes which are "sensible" to save should be saved along with the key. Some key attributes may not be appropriate to save. It is the decision of the implementor to decide which key attributes should be saved in the stringified key. Rogaway [Page 15] Draft 0.1 Generic Cryptographic Interface June 1, 1994 In contrast to the key_handle, the stringified form of the key is not opaque to the caller. He may write it into a file, for example, or print it on the screen. We provide for more than one possible form of the string to be produced. The caller can make such a determination using the how_to_stringify parameter. A value of 0 indicates default behavior. A value of 1 guarantees that the returned string will be in a printable character set. Other values are implementation-specific. This call is made by both security-aware and security-unaware callers. Security-unaware callers use only 0 or 1 for how_to_stringify. 2.1.7. GCS_Restore_key Inputs: o stringified_key OCTET STRING Outputs: o major_status INTEGER, o minor_status INTEGER, o output_key_handle OCTET STRING Return major_status codes: o GCS_COMPLETE indicates that the stringified_key has been turned into the corresponding internal key and can now be referenced off the returned output_key_handle. o GCS_BAD_ARGUMENT indicates that the stringified key is corrupted or otherwise does not indicate a well-formed key. o GCS_FAILURE indicates a general failure unspecified at the level of the GCS-API. Description: The GCS_Restore_key() call is the logical inverse of the GCS_Stringify_key() call. The string which is provided to GCS_Restore_key is turned into a key and then a handle to that key is returned to the caller. This mapping may depend on long-lived system state. Key attributes are presumably specified in the stringified Rogaway [Page 16] Draft 0.1 Generic Cryptographic Interface June 1, 1994 key, but additional key attributes may be determined at the time of the GCS_Restore_key() call. The "form" of the key, which was an explicit parameter to GCS_Stringify_key(), is now absent, since it is assumed that the encoding of the stringified key can include such details. This call is made by both security-aware and security-unaware callers. 2.2. Context Management Services These GCS-API calls create, modify or inquire about the status of a cryptographic context. They can also be used to turn a cryptographic context into a string, or to reverse this operation. 2.2.1. GCS_Init_context Inputs: o mech_type OBJECT IDENTIFIER, -0 for default o input_key_handle OCTET STRING, -for initial state; NULL for default o non_key_state OCTET STRING -for further state; NULL for default Outputs: o major_status INTEGER, o minor_status INTEGER, o context_handle OCTET STRING Return major_status codes: o GCS_COMPLETE indicates that the cryptographic context has been set up as requested, and can now be referenced off of the returned context_handle. o GCS_BAD_MECH indicates that the mechanism type is not supported. o GCS_BAD_ARGS indicates that the key or the non_key_state is syntactically incorrect to initialize the context o GCS_INSUFFICIENT_PRIVILEGE indicates that the caller lacks the Rogaway [Page 17] Draft 0.1 Generic Cryptographic Interface June 1, 1994 authority to receive a handle to a mechanism of the given type. o GCS_FAILURE indicates an unspecified failure at the level of GCS to create the cryptographic context. Description: The GCS_Init_context() call is used to create a new cryptographic context. The initial state of that context is provided by the key pointed to by the input-key_handle, and by the value of the non_key_state. The interpretation of the non_key_state is mechanism-dependent. If NULL values are provided for either or both of these parameters, then an appropriate mechanism-specific default will be used used. A variety of implementation-defaults can be implicitly requested with appropriate values of the mech_type parameter. A caller may provide FORWARD for the mechanism, in which case the locally-defined default FORWARD mechanism is used. A caller may specify BACKWARD for the mechanism, in which case the locally-defined default BACKWARD mechanism is used. A caller may specify the OID of a mechanism type rather than of a mechanism itself, in which case a locally-defined default mechanism of that type is the mechanism which is used. GCS_Init_context() returns a handle to a newly-created context. This handle must be used to obtain transformations. A minimal sequence of calls to carry out useful transformations is therefore GCS_Init_context() followed by a call to GCS_Transform() using the newly returned handle. This call is made by security-aware and security-unaware callers both. Callers which do not know the mechanism which they want either obtain that information from service-level calls; or they use the distinguished OID for the default FORWARD or BACKWARD mechanisms; or they use the OID of a mechanism-type, rather than the OID of a specific mechanism. 2.2.2. GCS_Inquire_context Inputs: o context_handle OCTET STRING, o request INTEGER Outputs: Rogaway [Page 18] Draft 0.1 Generic Cryptographic Interface June 1, 1994 o major_status INTEGER, o minor_status INTEGER, o state_info ANY Return major_status codes: o GCS_COMPLETE indicates that the request was valid and the answer to the inquiry can be found in the string state_info. o GCS_BAD_ARGUMENT is returned if the context_handle does not specify a valid context, or if the request-value is unrecognized. o GCS_FAILURE indicates some failure not further specified. Description: The GCS_Inquire_context() call is used by the caller to inquire about the state associated to a context. The request value is used to indicate what aspect of the state the caller is interested in. Typical inquiries might be the amount of time for which the context can continue to be used; the amount of text which has been cryptographically acted on under this handle; the value of an internal sequence number; and so forth. Since the returned data is mechanism-specific, this call is used by security-aware callers only. 2.2.3. GCS_Stringify_context Inputs: o context_handle OCTET STRING, o how_to_stringify INTEGER -0 for default, 1 for printable, ... Outputs: o major_status INTEGER, o minor_status INTEGER, o string_form_of_context OCTET STRING Return major_status codes: o GCS_COMPLETE indicates that the context has been successfully rendered into the string string_form_of_context, as requested. Rogaway [Page 19] Draft 0.1 Generic Cryptographic Interface June 1, 1994 o GCS_BAD_CONTEXT indicates that the provided context_handle does not encode a proper context o GCS_INSUFFICIENT_PRIVILEGE indicates that the caller lacks the privilege to perform the requested operation. o GCS_FAILURE indicates a general failure unspecified at the level of the GCS-API. Description: The GCS_Stringify_context() call takes the context referenced by context_handle and performs necessary operations to "pack" it into an exportable representation. It is not necessary that the operation explicitly save all aspects of the context; for example, the operation could side-effect system state and return only a pointer to the cached state. The caller is expected to save the string_form_of_context but not to modify it. It is required that if this string is subsequently provided to GCS_Restore_key, an operationally equivalent key shall be produced (under normal operational circumstances). In contrast to the context_handle, the stringified form of the context is not opaque to the caller. He may write it into a file, for example, or print it on the screen. We provide the possibility that more than one form of the context may be produced. The caller can make a determination for the form that is desired using the how_to_stringify parameter. A value of 0 indicates default behavior. A value of 1 guarantees that the returned string will be in a printable character set. Other values are implementation-specific but should generally be avoided. This call is made by both security-aware and security-unaware callers. Security-unaware callers use only 0 or 1 for how_to_stringify. 2.2.4. GCS_Restore_context Inputs: o stringified_context OCTET STRING Outputs: o major_status INTEGER, Rogaway [Page 20] Draft 0.1 Generic Cryptographic Interface June 1, 1994 o minor_status INTEGER, o output_context_handle OCTET STRING Return major_status codes: o GCS_COMPLETE indicates that the context represented by the stringified_context parameter has been created and a handle to this context has been returned as output_context_handle. o GCS_BAD_ARGUMENT indicates that the stringified key is corrupted or otherwise does not indicate a well-formed key. o GCS_FAILURE indicates a general failure unspecified at the level of the GCS-API. Description: The GCS_Restore_context() call is the logical inverse of the GCS_Stringify_context() call. The string which is provided to GCS_Restore_context() is turned into a context in an implementation- specific way, and then a handle to that context is returned to the caller. The "form" of the context, which was an explicit parameter to GCS_Stringify_context(), is now absent, since it is assumed that the encoding of the stringified key can include such details. This call is made by both security-aware and security-unaware callers. 2.3. Cryptographic Transformation Services It is an important characteristic of the GCS-API that all transformations are done using a single verb, GCS_Transform. Different transformations, and indeed different types of transformations, pass in different contexts to GCS_Transform. 2.3.1. GCS_Transform Inputs: o input_context_handle OCTET STRING, o code INTEGER, -0 for default o inputs SEQUENCE OF OCTET STRING Rogaway [Page 21] Draft 0.1 Generic Cryptographic Interface June 1, 1994 Outputs: o major_status INTEGER, o minor_status INTEGER, o outputs SEQUENCE OF OCTET STRING Return major_status codes: o GCS_COMPLETE indicates that the transform was carried out without incident and the caller should refer to outputs to see the result of the computation. o GCS_BAD_ARGS indicates that there is no such context, that there are the wrong number of arguments among the inputs, that the specified code is invalid for this transform, etc.. o GCS_BAD_DATA indicates that the mechanism has restrictions (e.g., on the length of certain inputs) which are violated by the attempted call. o GCS_REJECTED_BY_TRANSFORM indicates that the input failed a mechanism-specific test which was carried out in doing the transform. o GCS_FAILURE indicates an unspecified failure at the level of GCS to create the cryptographic context. Description: The GCS_Transform() call is the business-end of the GCS-API. It maps the specified sequence of strings to an output set of strings, as determined by the mechanism of the indicated context, the current state of the context, the value of "code," and possibly some number of internally-generated (pseudo)random bits. The transform which is performed can be specialized in a limited way using the argument "code." An over-zealous use of code is frowned- upon, and any non-zero use implies the caller is security-aware. The code is used to control certain low-level details of the mechanism which were deemed to be of insufficient importance to be considered a distinct mechanism. GCS_Transform() returns mechanism-specific results in one of three ways. First, there is the list of strings which is the result of performing the transform. Second, there is the minor_status value, which all GCS verbs may use in mechanism-specific or implementation- specific ways. Third (and unlike all other verbs) a mechanism under Rogaway [Page 22] Draft 0.1 Generic Cryptographic Interface June 1, 1994 GCS_Transform() can make the major_return code itself indicate a failure. An an example, if the the transform was supposed to verify a message authentication code (MAC) and this verification failed, it would be appropriate to use GCS_REJECTED_BY_TRANSFORM as the major_status return value. 2.4. Support Calls These calls perform services to help the security-aware caller to choose the mechanism he wants, to help the programmer in determining what return codes may mean, and to perform clean up of data structures which were allocated through the GCS-API. 2.4.1. GCS_Indicate_transforms Inputs: o mech_type OBJECT IDENTIFIER -NULL for all installed mechanisms Outputs: o major_status INTEGER, o minor_status INTEGER, o mech_set SET OF OBJECT IDENTIFIERS Return major_status codes: o GCS_COMPLETE indicates that the set of available mechanisms has been placed in mech_set. o GCS_BAD_ARGUMENT indicates that mech_type is not NULL and does not name a mechanism type known to the implementation. o GCS_FAILURE indicates that the requested operation could not be performed for reasons unspecified at the GCS-API level. Description: This GCS_Indicate_transform() call allows callers to determine the set of all transforms installed on the system (when mech_type is NULL), or to determine the set of all transforms of a given transform type. This is intended for security-aware callers, who want to request a non-default mechanism but do not know exactly what that mechanism may be. Rogaway [Page 23] Draft 0.1 Generic Cryptographic Interface June 1, 1994 2.4.2. GCS_Describe_transform Inputs: o mech_type OBJECT IDENTIFIER Outputs: o major_status INTEGER, o minor_status INTEGER, o qos_info SET OF AttributeValuePairs Return major_status codes: o GCS_COMPLETE indicates that the set of (attribute, value)-pairs has been place in qos_info. o GCS_BAD_ARGUMENT indicates that mech_type is not NULL and does not name a mechanism type known to the implementation. o GCS_FAILURE indicates that the requested operation could not be performed for reasons unspecified at the GCS-API level. Description: The GCS_Describe_transform() call takes a mechanism and returns the set of (value, attribute)-pairs which (together with the mechanism type) describe the transform's quality of service. The call is for the benefit of security-aware callers who know the quality of service they are after, but do not know or do not want to explicitly name the specific mechanism which will provide this. Such callers are expected to fish through this list of mechanisms returned by GCS_Indicate_mechs and to choose one which provides the desired quality of service, as indicated by GCS_Describe_transform. A separate GCS_Describe_transform() call is made for each mechanism the caller is interested in. 2.4.3. GCS_Display_status Inputs: o status_value INTEGER, -major_status/minor_status return value o status_type INTEGER, -1 if major_status, 2 if minor_status Rogaway [Page 24] Draft 0.1 Generic Cryptographic Interface June 1, 1994 o mech_type OBJECT IDENTIFIER -mech_type for minor_status x-lation Outputs: o major_status INTEGER, o minor_status INTEGER, o status_string_set OCTET STRINGS Return major_status codes: o GCS_COMPLETE indicates that a valid printable status representation (possibly representing more than one status event encoded in the status value) is available in the returned status_string_set. o GSS_BAD_MECH indicates that translation in accordance with an unsupported mech_type was requested, so translation could not be performed. o GSS_BAD_ARG indicates that the status_value was invalid, or that the input status_type carried a value other than 1 or 2, so translation could not be performed. o GSS_FAILURE indicates that the requested operation could not be performed, for reasons unspecified at the GCS-API level. Description: The GCS_Display_status() call provides a means for callers to translate major and minor status codes to a printable string representation. 2.4.4. GCS_Display_oid_info Inputs: o gcs_oid OBJECT IDENTIFIER Outputs: o major_status INTEGER, o minor_status INTEGER, o description OCTET STRING Rogaway [Page 25] Draft 0.1 Generic Cryptographic Interface June 1, 1994 Return major_status codes: o GCS_COMPLETE indicates that a description of the provided GCS-API OID has been place in description. o GCS_BAD_ARGUMENT indicates that there is no description matching the gcs_oid which was specified. o GCS_FAILURE indicates that the requested operation could not be performed for reasons unspecified at the GCS-API level. Description: The GCS_Display_oid_info() call takes the OID of a mechanism or a mechanism type or a key attribute or a mechanism attribute and it returns a description of that object in the form of a string. The syntax of the returned string is a local matter. Recommended information to include about a transform is the transform type and a description of all attributes and values for the transform. Recommended information to include about a transform type is a description of the type. 2.4.5. GCS_Release_key This and the following calls are quite mundane. They will be specified at a later time. 2.4.6. GCS_Release_context This section to be done later. 2.4.7. GCS_Release_buffer This section to be done later. 2.4.8. GCS_Release_oid_set This section to be done later. 2.4.9. GCS_Release_qos_info This section to be done later. Rogaway [Page 26] Draft 0.1 Generic Cryptographic Interface June 1, 1994 2.4.10. GCS_Release_att_set This section to be done later. 3. Unresolved Issues This document is a preliminary draft. It is being distributed in this early form to interested parties because of the upcoming X/Open meeting; because of my leaving IBM and my being unavailable for the rest of the summer; and because I am interested in getting early feedback. Several areas of this specification need additional thought, while other parts of the document are simply unspecified. Particular questions and areas of concern are enumerated below. 1. What is the relationship of key attributes to transforms? Currently, keys may or may not have attributes, and it is the business of each mechanism to enforce or not enforce attributes. This is conceptually unpleasant because key attributes seem as though they should be more orthogonal to mechanisms and not necessarily enforced by mechanisms. The approach also seems a bit to anarchistic. Bob Blakley has suggested mandating a distinguished key attribute of "Permitted Mechanisms." The value of this attribute would be the the set of permitted mechanisms and mechanism types for the key. Enforcement of this attribute would be by GCS, not by the mechanism. Note that this would further suggest that the value of a key attribute should not be limited to an integer. 2. Transforms are viewed as maps from strings to strings. It is possible to generalize this (e.g., allow a map from an integer to a string). But is it desirable to generalize in this manner? 3. Apart from the distinguished FORWARD and BACKWARD maps of a GCS implementation, there is no particular relationship between a mechanism and its inverse. Both have distinct OIDs and are treated separately as far as the GCS is concerned. Is this right? 4. I have faked anything remotely connected with ASN.1, because my only source of information on this, the defining ISO document, made no sense to me. Someone who understands this stuff is going to have to help me with all of the types and with Appendix A as well. 5. I am concerned that without Appendix B, much of this document may be too abstract for many people to understand the point. Yet a stab at Appendix B might take many days and much debate. 6. What is the relationship between the spec and the (unwritten) Appendix B? Perhaps a certain set of mechanism types and their Rogaway [Page 27] Draft 0.1 Generic Cryptographic Interface June 1, 1994 signatures should be standardized alongside the GCS-API (i.e., Appendix B would be more than informational). 7. As I have defined it, the signature of a mechanism includes only its type and the number of its input and output strings. Where is key initialization, "other" initial state, and key attributes -- all of which seem like they have some connection with the signature. This is murky. 4. Acknowledgments The author is heavily indebted to John Linn's GSS-API specification [2], which provided not only the model for this work, but a good deal of its organization and even a bit of incidental text. We will only hope that John interprets this flagrant plagiarism as a form of flattery and not as a form of intellectual dishonestly! Many thanks are also due to Bob Blakley, for his good taste as well as specific insights which he brings. Discussions with Don Johnson, and earlier ones with Mike Matyas and John Wilkins, helped to clarify several aspects of the nature of good and generic cryptographic API. 5. References [1] FIPS Pub XXX, "Standard for Cryptographic Service Calls (Draft)," NIST. April 27, 1994. [2] RFC 1508, J. Linn, "Generic Security Service Application Program Interface." September 1993. [3] RFC 1509, J. Wray, "Generic Security Service API : C-bindings." September 1993. [4] X/Open Guide, "Distributed Security Framework, Draft 3." April 18, 1994. 6. Author's Address Address until June 6, 1994: Phillip Rogaway IBM 11400 Burnet Road Austin, TX 78758 Phone: (512) 838-8244 Rogaway [Page 28] Draft 0.1 Generic Cryptographic Interface June 1, 1994 EMail: rogaway@austin.ibm.com From June 7, 1994 until August 24, 1994, contact: Bob Blakley IBM 11400 Burnet Road Austin, TX 78758 Phone: (512) 838-8133 EMail: blakley@vnet.ibm.com After September 25, 1994: Phillip Rogaway Department of Computer Science University of California, Davis Davis, CA 95616 Phone: (916) 752-7004 EMail: rogaway@cs.ucdavis.edu Appendix A: Mechanism-Independent Token Format This section to be completed at a later time. Appendix B: Initial Population of Mechanism-Types This section to be completed at a later time. Rogaway [Page 29]