RemoteIdentityStore
Remote identity keys pinned on first contact (trust on first use, see docs/identity-trust.md). One public identity key per remote DeviceAddress; two devices of the same user have separate entries.
Keys are public, but a pin is security state: it is never removed and never replaced silently. The client pins a key only after the first contact with it succeeded cryptographically, and replaces it only when the application explicitly accepted an identity change (replace).
Each pin carries a VerificationState that belongs to exactly the pinned key: a new pin starts VerificationState.UNVERIFIED, and so does a replaced one. Verification is never carried over to another key.
Functions
The pin of address with its verification state, or null.
Replaces the pin of address with newIdentityKey as VerificationState.UNVERIFIED, but only if expectedIdentityKey is pinned (compare-and-set). Throws IllegalStateException and changes nothing if there is no pin or another key is pinned, and IllegalArgumentException if both keys are equal. Only for an identity change the application explicitly accepted.
Sets the verification state of the pin of address, but only if the pinned key is identityKey. Throws IllegalStateException and changes nothing if there is no pin or another key is pinned.
Pins identityKey for address as VerificationState.UNVERIFIED. Storing the key that is already pinned does nothing (its verification state stays). Throws IllegalStateException if a different key is pinned: a pin is never replaced silently.