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 principal. (The key version specified in this routine must not be 0 [zero].) The replicas should notify the master when they have completed setting their local stores to the new key.
4. Cause the master to call sec_key_mgmt_change_key( ) (here again, the key version must not be 0) after all replicas have set the new key locally, thereby updating both the master's local storage and the registry database entry.
Of course, if the master and each replica has its own principal identity, each server may call sec_key_mgmt_change_key( ) without coordinating this activity with any others.