Being an IRMA issuer allows you to issue credentials containing attributes to IRMA app users, which they can then disclose to yourself or to others. Contrary to verifying IRMA attributes from the IRMA app which can be done by anyone running an IRMA server, issuing to IRMA apps cannot be done without involvement the developers of IRMA (the Privacy by Design Foundation and SIDN): registering your organization and the credentials you will be issuing is required. As part of this registration process the identity of your organization is verified, and the contents and structure of the credentials that you will be issuing is finetuned for correctness and consistency with the rest of the IRMA ecosystem. This process includes signing a contract that among others requires you to properly protect your IRMA private key, as well as paying a yearly fee.
This page documents some of the processes involved.
Becoming an issuer
In IRMA, information on all issuers, their credentials and the contained attributes is stored in datastructures called IRMA schemes. The two standard IRMA schemes,
pbdf, meant for demo and production respectively, are maintained by the Privacy by Design Foundation and SIDN. All IRMA apps and servers contain a copy of these two schemes, which they automatically periodically update. A party wishing to become an issuer must therefore be included in these schemes.
Generally, the process of becoming an IRMA issuer looks as follows. These steps are documented in detail in the sections below.
- Collect all relevant information on your issuer, its credentials and the contained attributes, and submit that as a pull request (PR) to the
irma-demoscheme. (We can help creating the PR based on the relevant information, if required.) Once that is merged, it becomes automatically available for your IRMA server and for IRMA apps. Then you can start issuing the new credentials in your application during development and in demos, using the IRMA server. In this phase, you can finetune your credential structure and your issuance application.
- When your credential structure has become finalized and you are ready to move to production, contact us. Once you are verified as the valid issuer of the credentials and the issuer contract has been signed, your issuer information from the
irma-demoscheme can be copied over to the production scheme,
pbdfusing another PR. At this point you will need to generate your IRMA issuer private/public keypair (more on that below), and include the public key in the PR. Once your issuer information is included in the
pbdfscheme, you can start issuing credentials.
Credentials within the
irma-demoscheme are not meant for production application and actual personal data, since attributes within this scheme cannot be trusted: all private keys of all issuers under the
irma-demoscheme are included in it, so that anyone can issue any
irma-democredential containing any attribute values.
irma-demo issuer and credentials
Within the scheme, all issuer and credential information is contained in a folder that schematically looks like the following.
issuer-id ├── Issues │ └── credentialtype-id │ ├── description.xml │ └── logo.png ├── PublicKeys │ ├── 0.xml | └── 1.xml ├── PrivateKeys │ ├── 0.xml │ └── 1.xml ├── description.xml └── logo.png
To get started, it is easiest to use an existing folder of another issuer in
irma-demo as base by duplicating it, and modifying its contents. In order to check correctness of your modifications, you can try to sign the scheme by running
irma scheme sign in your
irma-demo checkout, which will point out common mistakes. For more details about the contents of schemes, see the IRMA schemes page.
Some notes about the
- The contents of the
<Name>tags in the
description.xmlof both the issuer and all of its credential types must start with
Demofor all translations, to distinguish them from production (
pbdf) credentials in the IRMA app.
- Using the IRMA logo as
logo.pngfor the issuer and credential type is fine.
- For the private and public keypair, since no trust is associated to anything within
irma-demo, using those of another issuer in
irma-demois fine (but generating a new keypair is fine too; see below).
Once your modifcations are complete, ensure the scheme is validly signed by running
irma scheme sign in your irma-demo checkout, and submit your changes as a PR. Once the PR is merged, your demo issuer and its credentials become available for issuance to your IRMA server when it updates its copy of the scheme: periodically (hourly by default), or when you restart your server.
You can then use your IRMA server to issue the new credentials to your IRMA app. Alternatively, after the
irma-demo PR is merged, the new credentials can also be issued from their corresponding pages in the attribute index (only in the case of
Using a locally modified
Instead of submitting a PR to the
irma-demo scheme to us, it is also possible to modify a local copy of the
irma-demo scheme, and embed that local copy in the IRMA server and a manually compiled IRMA app, as follows.
- Create your modifications in
- Ensure the scheme is validly signed by running
irma scheme signin your
- When starting your IRMA server, point it to the folder containing your
irma-democheckout and disable scheme updating:
irma server --schemes-path ... --schemes-update 0
- Create a checkout of
irmamobile, the IRMA app source code; replace the
irmamobile/irma_configuration/irma-demowith your modified copy; and compile the IRMA app using the instructions in its README.
If you use the IRMA server from step 3 to issue your credentials, then the IRMA app from step 4 will accept them. Note, however, that the standard App/Play Store versions of the IRMA app will not.
pbdf issuer and credentials
After the development phase of your issuance application is finished and the issuer contract has been signed, your issuer and credentials can be moved to production as follows.
- Copy your issuer and its credentials from
irma-demoto a local checkout of the production scheme,
- Change all occurences of
irma-demowithin your issuer and credentials to
pbdf; ensure the
Demoprefix is everywhere removed; and use actual logos for your issuer and credentials.
- Generate a new 2048 bit IRMA issuer private/public keypair; put the public key within your issuer folder in
PublicKeys/0.xml; and keep your private key private.
- Submit your changes to
pbdfas a PR.
Your PR will then be signed by us, and merged. As with
irma-demo, your issuer and its credentials then become available for issuance to your IRMA server when it updates its copy of the scheme: periodically (hourly by default), or when you restart your server. Your credentials will also automatically appear in the attribute index, but in contrast with
irma-demo credentials, they cannot be issued from there.
Generating IRMA issuer keys
Generating a new IRMA issuer private/public keypair is done with the
irma command line tool:
irma issuer keygen
irma issuer keygen -h for the flags that this command accepts. By default, it will emit the private and public keys in directories called
PublicKeys under your current directory, creating them if they don't exist.
- When generating a new keypair for the
irma-demoscheme, the private key is expected to be included in the PR to the
irma-demorepository, within the
PrivateKeysfolder under your issuer folder. However, when generating a new keypair for the production
pbdfscheme, you must keep your private key private.
- Your past and current public keys are stored within your issuer folder in the
pbdfscheme in the
PublicKeysfolder with increasing filenames:
1.xml, et cetera. The number in the filename is the counter of your public key. When generating a new public key, you can ensure it gets the correct counter in one of the following ways:
- By specifying it explicitly using the
- By running
irma issuer keygenwithin your issuer folder in the scheme; it will then infer the appropriate counter using the public keys already present in the
- Alternatively, after generating the keypair you can open the private and public keys in a text editor and set the
<Counter>tag to the appropriate number.
- By specifying it explicitly using the
- If one of your credentials contains more than 10 attributes, then that amount of attributes increased by 2 (to account for the secret key and metadata attributes) must be passed to the
--numattributesflag, to ensure that the new public key supports the required amount of attributes.
Production IRMA issuer keypairs are valid for a year. Once a keypair expires it cannot be used anymore for issuance, so it is important that it is replaced by a fresh keypair before that time. Once a new public key has been included in the
pbdf scheme, the corresponding private key can be included in your IRMA server configuration. After a restart it will use to the new private key.
Please note that although the old private key cannot be used for new credentials, you MUST still keep this private key private. Someone with access to the private key could otherwise forge credentials with a creation date set to a date in the past when the key was not yet expired.
Submitting a new production public key
The process for getting a new issuer public key included in the production
pbdf scheme is as follows.
- Generate a new keypair as documented above.
- Send the public key to the
pbdfscheme manager, using a PR, email or Slack.
- The scheme manager will contact you out-of-band to verify that the public key arrived intactly, by checking its SHA256 hash.
- If this check succeeds, your new key will be included in the scheme. You can then install the corresponding private key in your issuing IRMA server.