This section contains information about pseudonyms and implementation recommendations for processing pseudonyms.
What is a pseudonym?
The raw value of a pseudonym is an 80 bytes uncompressed EC (Elliptic Curve) Point.
This raw value is derived from an identity (BSN - Dutch Citizens Service Number) combined with pseudonym metadata.
- OIN of the receiving organization
- ReceipentKeySetVersion of the EP Closing Key used at the receiving organization.
- SchemeKeySetVersion of the schemekeys
- Diversifier (Optional: A diversifier applies to a specific role for the identity, e.g. 'Representation')
- Type (Type of identity)
BSNK provides consumers of Encrypted Pseudonyms with keys that are used for the decryption of an Encrypted Pseudonym. (Further reading on keys: DV-key format. See DV-key format)
- EP Closing Key (PCD)
- EP Decryption Key (PDD)
Persisting Pseudonyms within your environment
Take these recommendations into account when persisting pseudonyms in your application environment:
1) The raw value of a pseudonym MUST (and can) not be used alone.
Since the pseudonym's raw value is based on the identity + Pseudonym metadata specified above, you MUST know which related metadata belongs to any stored raw value of a pseudonym. Without the related metadata of the pseudonym, any conversion or auditing will be infeasible.
2) Pay special attention to the EP Closing Key
As stated in the Pseudonym Metadata, the ReceipentKeySetVersion of the EP Closing Key used at the receiving organization has impact on the raw value of the Pseudonym.
When a new set of keys is requested at BSNk Sleutelverstrekking, all keys - including the
EP Closing Key - will have a ReceipentKeySetVersion based on the validFrom-date in the certificate used in the request.
- The new
EP Decryption keycan be safeley used, it has no impact on the decrypted Pseudonym.
A new set of requested BSNk decryption keys always contains a new
EP Closing Key as well.
- Changing the
EP Closing Keywill change the decrypted Pseudonyms (they will match ReceipentKeySetVersion of that EP Closing Key)
- So if you want to start using the new
EP Closing Key: You MUST convert your stored Pseudonyms to match this new
EP Closing Key.
- If not, you can continue using your current
EP Closing Key. It does not need to have the same ReceipentKeySetVersion as the
EP Decryption key. Your users will be identifiable using the same Pseudonym.
- Be sure to keep a backup of the
EP Closing Keythat you use for your persisted Pseudonyms. BSNk Sleutelverstrekking will only supply a new
EP Closing Keyhaving a ReceipentKeySetVersion based on the validFrom date belonging to a valid certificate.
3) Plan for conversions/migrations
Keychanges, like renewal of
EP Closing Key, or organizational dynamics like mergers, that change OIN, have impact on pseudonyms stored in the application.
Therefore, the following pseudonym-management scenario's SHOULD be taken into account:
- Closing Key conversion: Converting stored pseudonyms to be compatible with a new closing key (different ReceipientKeySetVersion)
- OIN migration: Migrating stored pseudonyms to another organization (different OIN and ReceipientKeySetVersion)
Do not use the pseudonym as a primary key to identify a user, because this will increase the impact of the mentioned conversion scenario's.