The key management API provides two functions for retrieving a key from the local key storage. The sec_key_mgmt_get_key( ) function returns a specified key version for a specified principal. The meaning of specifying version 0 (zero) in this routine may vary depending on the authentication protocol in effect. (If the protocol is DCE shared-secret, the value 0 for the version identifier means the version that was most recently added to the local storage.) In any case, a principal's login is almost always successful if the principal uses the version 0 key.
When there are valid tickets that are encoded with different key versions, an application may need to retrieve more than one key version. In that case, the application may call sec_key_mgmt_initialize_cursor( ) to set a cursor in the local storage to the first suitable entry corresponding to the named principal and key type, and then call sec_key_mgmt_get_next_key( ) to get all versions of that key in storage. The application may then call sec_key_mgmt_release_cursor( ), which disposes of information associated with the cursor. Neither of the key-retrieval routines can return keys that have been explicitly deleted, or that have been garbage collected after expiring.
The two key-retrieval functions dynamically allocate the memory for the returned key(s). To enable the efficient allocation of memory, an application may call sec_key_mgmt_free_key( ), which frees the memory occupied by the key and returns it to the allocation pool.