2b. Working with pseudonyms

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.

Pseudonym metadata

• OIN of the receiving organization
• ReceipentKeySetVersion of the EP Closing Key used at the receiving organization.
• SchemeKeySetVersion of the schemekeys
• Schemeversion
• Diversifier (Optional: A diversifier applies to a specific role for the identity, e.g. 'Representation')
• Type (Type of identity)

Pseudonym Decryption

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 key can 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 Key will 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 Key that you use for your persisted Pseudonyms. BSNk Sleutelverstrekking will only supply a new EP Closing Key having 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.

Pseudonym ::= SEQUENCE {
    notationIdentifier     OBJECT IDENTIFIER (id-BSNk-decrypted-pseudonym),
    schemeVersion          INTEGER,
    schemeKeySetVersion    INTEGER,
    recipient              IA5String,
    recipientKeySetVersion INTEGER,
    type                   INTEGER,
    pseudonymValue         IA5String,
    diversifier       [0]  Diversifier OPTIONAL
}

Diversifier ::= SEQUENCE OF DiversifierKeyValuePair
 
DiversifierKeyValuePair ::= SEQUENCE {
    key IA5String,
    value IA5String
}