OSF DCE Application Development Guide--Core Components

OSF DCE Application Development Guide—Core Components
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.
30.2 Changing a Key
The sec_key_mgmt_change_key() function communicates with the registry to change
the principal’s key to a specified string, and also places the new string in the local key
storage. The keydata input argument for this call may be a new key that the application
specifies or a random key returned by the sec_key_mgmt_gen_rand_key() routine. An
application may call sec_key_mgmt_get_next_kvno() to determine the next key
version number that should be assigned to the new key so that it may reference this key
version when retrieving a key.
In some circumstances, a principal may need to change its key in the local key storage
but not immediately update the registry database. For example, a database application
may maintain replicas of a master database that are managed by servers running on
different computers. If these servers all provide exactly the same service, it makes sense
for them to share the same key (meaning that they share the same principal identity).
This way, a user with a ticket to the principal can be directed to whichever server is least
busy.
When the registry database obtains a new key for a principal, the authentication service
can immediately begin issuing tickets to the principal that are encoded under the new
key. However, suppose the master for a single-principal replicated service were to call
sec_key_mgmt_change_key(), and a client presented a ticket encoded with the latest
key to a replica that had not yet learned that key. In this case, the replica would refuse
service, even though the ticket was valid. Therefore, if an application employs
replicated servers that are also instances of a single principal identity, the application
should do the following:
1. Generate a new key by calling sec_key_mgmt_gen_rand_key( ). This routine
simply returns a key to the calling process, without updating the registry or local
storage.
2. Disseminate the new key to all replicas.
3. Cause the replicas to call sec_key_mgmt_set_key( ). This call updates the local
storage to the new key but does not update the registry database entry for the
30−2 Tandem Computers Incorporated 124245