diff --git a/README.md b/README.md index fea0aa6..2714e24 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,25 @@ # Yivi technical documentation -This is the source of the Yivi technical documentation website. [Build and edit instructions](website). \ No newline at end of file +This is the source of the Yivi technical documentation website. + +## Local development +To start a local docusaurus server simply run the following commands. +```bash +cd yivi-docs +``` +```bash +npm i +``` +```bash +npm run start +``` + +To start a local docker container with the right settings simply run: + +```bash +docker compose up +``` + +## Release +To release a new version run the Github action located [here](https://github.com/privacybydesign/irma-documentation/actions/workflows/delivery.yml). This will push a new Docker build to Github packages: +https://github.com/privacybydesign/irma-documentation/pkgs/container/irma-documentation \ No newline at end of file diff --git a/yivi-docs/blog/2024-11-29-nov-update/index.md b/yivi-docs/blog/2024-11-29-nov-update/index.md new file mode 100644 index 0000000..29be263 --- /dev/null +++ b/yivi-docs/blog/2024-11-29-nov-update/index.md @@ -0,0 +1,54 @@ +--- +slug: vision, roadmap, progress +title: November update +authors: [dibranmulder] +tags: [yivi, roadmap] +--- + +He all, I thought it would be nice to update you on our progress. Our dedicated team started the development and operations of Yivi effectively on the 1st of November. The existing code base (70+ repositories) is quite large, and the learning curve is rather steep, however I think we are making great progress. We touched a lot of components already and are making great progress. + +As told during the Yivi meetup we have a roadmap ahead of us containing 3 epics, namely: Cloud Migration, Development and eIDAS2.0. I will update our progress on each of them. + + + +## Cloud Migration +As said our priority is taking care of all infrastructure and tooling required to serve the Yivi ecosystem. We are aiming for a seamless migration of multiple core components such as several issuers (mobile, email,saml, idin), yiviconnect.nl, the key share server and my yivi. Most of these components are hosted by SIDN on VM’s managed by them. Our plan is to host it all on Scaleway, a European cloud provider, offering locations in Amsterdam, Paris and Warsaw. Our tech of choice is Kubernetes. Choosing Kubernetes benefits the broader ecosystem, because containerized hosting will be our default going forward. You might have seen that several demos and issuers are now containerized. + +To highlight our progress, here is a list of services running on our staging environment—a newly established platform where we test our services. +- https://schemes.staging.yivi.app +- https://is.staging.yivi.app +- https://my.staging.yivi.app/ +- https://keyshare.staging.yivi.app +- https://emailissuer.staging.yivi.app/ +- https://sms-issuer.staging.yivi.app/en/ +- https://docs.staging.yivi.app +- https://connect.staging.yivi.app/saml-bridge +- https://demos.staging.yivi.app +- https://angrygames.staging.yivi.app +- https://atumd.staging.yivi.app +- https://docs.staging.yivi.app + +For security reasons, we do not open-source the code used to create the infrastructure. + +## Development +The next priority is to take care of the user experience of Yivi. We think having the best UX is one of the ways in which Yivi distinguishes itself from other ID-wallets. Our mobile engineer Wouter took some time to eliminate technical debt, including upgrading to the latest Xcode and Flutter versions and upgrading several dependencies. Also, the integration tests broke with the upgrade, so we had to fix them. + +The first UI improvements are already merged, we will stack them up and aim to release them before Christmas. We already took ownership of the App and Play Store accounts, but the release process and any particularities have not been discussed yet. We will update you when there’s a new App to test. Make sure to open an issue on the irmamobile repository when you experience bugs in the mobile app. + +Next to the mobile development we started fixing some bugs in the irmago library. Getting familiar with this rather complex piece of code is quite challenging but progress is made. Luckily, we have the extensive knowledge of Ivar and Sietse available so that helps a lot! + +## eIDAS 2.0 +We acknowledge that Yivi should be part of the European Digital Identity Framework. Becoming an EUDI-wallet is one of our long-term goals, however, how to become one is very much still a moving target. Fortunately, we have several connections and advisors keeping us up to date in that field. + +We have begun examining the technical implications of adopting cryptography and protocols other than Idemix and IRMA. While it's too early to share specific details, rest assured that it's on our radar. + +## Community +We started reaching out to the existing contacts of Yivi, you might have noticed it. We had dozens of talks and introductions, and we valued them very much. It’s very nice to see the enthusiasm about Yivi in the ecosystem. Also, we have several commercial parties showing interest in Yivi, we can’t share anything yet, but we will when the time is ready. + +Several parties contacted us regarding the Development, Consultancy and Support for an Age Verification Solution – European Tender. We evaluated the tender but sadly participating in the tender on such a short term was rather impossible. In the future we will need a consortium of organizations to participate in such a tender. We already had quite a lot of expertise available via several organizations, but we clearly missed BID management capacity and law and regulations expertise. If your organization has these expertise’s we would like to connect so that we can explore a collaboration in the future. + +Thank you all for being a part of the Yivi community. Feel free to contact us with any questions or remarks. This concludes the November update, I will try to update you every month, and for now happy holidays! + +Kind regards, also on behalf of the yivi team + +Dibran, Sara, Wouter, Martijn, Jasper, Leon, Ivar, Sietse. diff --git a/yivi-docs/docs/api-irma-server.md b/yivi-docs/docs/api-irma-server.md index 384e214..3f696f1 100644 --- a/yivi-docs/docs/api-irma-server.md +++ b/yivi-docs/docs/api-irma-server.md @@ -130,7 +130,7 @@ Get the [session result](https://godoc.org/github.com/privacybydesign/irmago/ser The response may contain the following fields: * `token`: Requestor token * `status`: Current [session status](#get-session-requestortoken-status) -* `type`: [Session type](what-is-irma.md#session-types): one of `"disclosing"`, `"signing"`, or `"issuing"` +* `type`: [Session type](what-is-yivi.md#session-types): one of `"disclosing"`, `"signing"`, or `"issuing"` * `proofStatus`: One of the package level [irma.ProofStatus](https://godoc.org/github.com/privacybydesign/irmago#pkg-constants) constants, indicating the cryptographic validity of the attributes and proofs of knowledge: * `"VALID"`: proofs are valid * `"INVALID"`: proofs are invalid diff --git a/yivi-docs/docs/chained-sessions.md b/yivi-docs/docs/chained-sessions.md index 531ef80..e4edbcb 100644 --- a/yivi-docs/docs/chained-sessions.md +++ b/yivi-docs/docs/chained-sessions.md @@ -1,13 +1,13 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - --- title: Chained sessions --- -Since version 6.1.0 of the [Yivi app](yivi-app.md) and 0.8.0 of the [IRMA server](irma-server.md), multiple [IRMA sessions](what-is-irma.md#session-types) may be chained together by the requestor into a single flow. After the Yivi app user has started the first session (for example, by scanning a QR code), she then passes through multiple session screens, as shown here. In this example, the requestor uses a disclosure session to retrieve the user's name and then immediately afterwards issues that into a new credential. +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +Since version 6.1.0 of the [Yivi app](yivi-app.md) and 0.8.0 of the [IRMA server](irma-server.md), multiple [IRMA sessions](what-is-yivi.md#session-types) may be chained together by the requestor into a single flow. After the Yivi app user has started the first session (for example, by scanning a QR code), she then passes through multiple session screens, as shown here. In this example, the requestor uses a disclosure session to retrieve the user's name and then immediately afterwards issues that into a new credential. -
+
- -pre-condiscon - -```json -{ - "type": "disclosing", - "content": [{ - "label": "Address", - "attributes": [ - "irma-demo.nijmegen.address.street", - "irma-demo.idin.idin.address" - ] - }, + + + pre-condiscon + + + ```json { - "label": "City", - "attributes": [ - "irma-demo.nijmegen.address.city", - "irma-demo.idin.idin.city" - ] - }] -} -``` - + "type": "disclosing", + "content": [{ + "label": "Address", + "attributes": [ + "irma-demo.nijmegen.address.street", + "irma-demo.idin.idin.address" + ] + }, + { + "label": "City", + "attributes": [ + "irma-demo.nijmegen.address.city", + "irma-demo.idin.idin.city" + ] + }] + } + ``` + + "Condiscon", standing for conjunction of disjunctions *of conjunctions* of attributes adds one extra level to this in the session request format: now verifiers can request multiple attribute *sets* from the user, offering the user multiple choices for some or all of the sets: - - -condiscon - + + ```json { "@context": "https://irma.app/ld/request/disclosure/v2", @@ -65,7 +68,8 @@ An [IRMA disclosure session](what-is-irma.md#session-types) is started by a veri ] } ``` - + + ```golang request := irma.NewDisclosureRequest() request.Disclose = irma.AttributeConDisCon{ @@ -85,18 +89,23 @@ request.Disclose = irma.AttributeConDisCon{ }, } ``` - + + + condiscon + + In this disclosure request, the user is asked for her (demo) BSN, and for her `street`, `houseNumber` and `city` attribute from the `irma-demo.nijmegen.address` credential type. For the latter three the user has one other option which is not currently shown in the screenshot (but it is present in the session request). In the session request above (see the second tab) we call the three JSON lists that contain strings *inner conjunctions* (distinguishing them from the *outer conjunctions*, that contain not attribute but disjunctions). Asking for multiple attributes within such an inner conjunctions of a session request is subject to the following rules: -- When attributes coming from multiple credential types occur in an inner conjunction, at most one of them may be a non-[singleton](overview.md#singletons). +- When attributes coming from multiple credential types occur in an inner conjunction, at most one of them may be a non-[singleton](technical-overview.md#singletons). - If some of the attributes occuring in the inner conjunction come from the same credential type, then the attributes that the user sends must come from the same credential instance: it is not allowed to mix attributes coming from distinct instances of that credential type. (The Yivi app automatically only offers candidate sets as choices to the user that satisfy this property.) For example, consider the following condiscon session request: - - + + + ```json { "@context": "https://irma.app/ld/request/disclosure/v2", @@ -110,7 +119,8 @@ For example, consider the following condiscon session request: ] } ``` - + + ```golang request := irma.NewDisclosureRequest() request.Disclose = irma.AttributeConDisCon{ @@ -122,7 +132,8 @@ request.Disclose = irma.AttributeConDisCon{ }, } ``` - + + Supposing that the user has two instances of `pbdf.pbdf.diploma` whose `degree` and `institute` attributes are `(degree 1, institute 1)` and `(degree 2, institute 2)`, this means that the user can choose only either `(degree 1, institute 1)` or `(degree 2, institute 2)`, and not `(degree 1, institute 2)` or `(degree 2, institute 1)`. (If desired it would be possible to give the user those options by asking for the two attributes in two *outer* conjunctions instead of within an *inner* conjunction.) @@ -133,9 +144,10 @@ When combining multiple credential types within a disjunction these restrictions As before, the verifier can indicate in the session request that it requires specific values for one or more of the requested attributes. In addition, the new condiscon versions of the Yivi app and server include the following new features. - **Optional disjunctions**: Now that inner conjunctions can be of any length (instead of just 1 as it previously was), verifiers can mark a disjunction as *optional* by specifying an empty inner conjunction `[]` as one of its candidates, indicating that by disclosing nothing this disjunction is satisfied: - - - ```json + + + +```json { "@context": "https://irma.app/ld/request/disclosure/v2", "disclose": [ @@ -146,18 +158,21 @@ As before, the verifier can indicate in the session request that it requires spe ] } ``` - - ```golang - request := irma.NewDisclosureRequest() - request.Disclose = irma.AttributeConDisCon{ - irma.AttributeDisCon{ - irma.AttributeCon{}, - irma.AttributeCon{irma.NewAttributeRequest("pbdf.pbdf.diploma.degree")}, - }, - } - ``` - - This can be useful when certain attributes would be useful but not required, so that their absence does not abort the IRMA session. + + +```golang +request := irma.NewDisclosureRequest() +request.Disclose = irma.AttributeConDisCon{ + irma.AttributeDisCon{ + irma.AttributeCon{}, + irma.AttributeCon{irma.NewAttributeRequest("pbdf.pbdf.diploma.degree")}, + }, +} +``` + + + +This can be useful when certain attributes would be useful but not required, so that their absence does not abort the IRMA session. - **Null attributes**: Attributes that were skipped by the issuer during issuance, assigning them the `null` value, can now be requested and disclosed normally. The verifier receives the JSON value `null` instead of a (string) attribute value. (Previously such null attributes would have caused the Yivi app to abort the session, considering them "absent" and thus the request unsatisfiable. This made it impractical to request an optional attribute along with other attributes.) - **Disjunction labels** are now optional. They often only repeated the requested credential or attribute names (mainly because they were required); this is now discouraged. Instead, labels should only be used to explain something to the user that would otherwise not be obvious (e.g, to request the user to send a work email address instead of a personal one). @@ -181,4 +196,3 @@ For attribute-based signatures, the condiscon version of the IRMA software bring This is fixed in the condiscon versions of IRMA by committing to the attribute structure (i.e. disclosed vs. non-disclosed attributes) during generation and verification of the attribute-based signature in a new way, that is automatically compatible with future attribute additions to the credential type. Previously generated IRMA attribute-based signatures remain valid (as long as no new attributes are added to their credential types). However, the new Yivi app always uses the fixed signature generation algorithm which the pre-condiscon version of the IRMA server does not support. For that reasons, if you use attribute-based signatures your IRMA server(s) will need to be updated before the new Yivi app is released (probably some weeks from now). - diff --git a/yivi-docs/docs/email.md b/yivi-docs/docs/email.md index 1d5ad85..edeaefd 100644 --- a/yivi-docs/docs/email.md +++ b/yivi-docs/docs/email.md @@ -4,7 +4,7 @@ title: Email address IRMA has a decentral architecture: anyone can start an [`irma server`](irma-server.md) and verify attributes, communicating directly with Yivi apps. This is an important and distinguishing feature contributing to IRMA's privacy features and trustworthiness, but also means that we as authors of the software have no natural update channel with which we can update all IRMA servers running within the ecosystem. We have to prevent that this leads to a fractured IRMA ecosystem with incompatible apps and servers, which would lead to bad user experience and hurt adoption. -Inspired by the approach of Let's Encrypt, each of the [IRMA server](what-is-irma.md#irma-servers) software components can be configured with an email address. If specified, the email address is uploaded to the [Privacy by Design Foundation](https://privacybydesign.foundation/) and subscribed to receive updates about changes in the IRMA software or ecosystem. You will be notified of changes such as major updates of the IRMA server, and breaking changes in any part of the IRMA infrastructure that would require you to update your IRMA server or otherwise take action in order to stay compatible with the rest of the IRMA ecosystem. +Inspired by the approach of Let's Encrypt, each of the [IRMA server](what-is-yivi.md#irma-servers) software components can be configured with an email address. If specified, the email address is uploaded to the [Privacy by Design Foundation](https://privacybydesign.foundation/) and subscribed to receive updates about changes in the IRMA software or ecosystem. You will be notified of changes such as major updates of the IRMA server, and breaking changes in any part of the IRMA infrastructure that would require you to update your IRMA server or otherwise take action in order to stay compatible with the rest of the IRMA ecosystem. ***We strongly recommend anyone running any IRMA server in production to specify an email address.*** diff --git a/yivi-docs/docs/irma-backend.md b/yivi-docs/docs/irma-backend.md index ff3659d..c0e78ca 100644 --- a/yivi-docs/docs/irma-backend.md +++ b/yivi-docs/docs/irma-backend.md @@ -4,7 +4,7 @@ title: IRMA backend packages [`irma-backend-packages`](https://github.com/privacybydesign/irma-backend-packages/) is a collection of libraries in multiple programming languages assuming the role -of the [IRMA server](what-is-irma.md#irma-servers) in the IRMA protocol, allowing you to integrate IRMA in the backend +of the [IRMA server](what-is-yivi.md#irma-servers) in the IRMA protocol, allowing you to integrate IRMA in the backend of your application. In particular, these libraries allow you to do the following: * Starting IRMA sessions using a session request or a JWT at the IRMA server diff --git a/yivi-docs/docs/irma-cli.md b/yivi-docs/docs/irma-cli.md index 252cd08..ef7af05 100644 --- a/yivi-docs/docs/irma-cli.md +++ b/yivi-docs/docs/irma-cli.md @@ -1,5 +1,5 @@ --- -title: irma command line tool +title: irma cli --- `irma` is an IRMA Swiss knife in the form of a command line executable, supporting the following subcommands: diff --git a/yivi-docs/docs/irma-protocol.md b/yivi-docs/docs/irma-protocol.md index add5609..22426e5 100644 --- a/yivi-docs/docs/irma-protocol.md +++ b/yivi-docs/docs/irma-protocol.md @@ -2,6 +2,9 @@ title: IRMA protocol --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + During an IRMA session, the IRMA protocol is used by the [IRMA server](irma-server.md) and [Yivi app](yivi-app.md) to issue or verify attributes. The Yivi app sends and receives various data by invoking a number of HTTP endpoints of the IRMA server, making the session progress through a number of stages. This page documents those endpoints, the data being handled, and the states the session goes through. ## Introduction @@ -40,22 +43,24 @@ The following sequence diagrams showing an IRMA session in the happy flow, witho Generate these using `java -jar path-to-plantuml.jar -tsvg *.puml` in docs/assets. E.g. if the PlantUML extension is installed in VSCode: `java -jar ~/.vscode/extensions/jebbs.plantuml-2.15.1/plantuml.jar -tsvg *.puml` --> - - -![Pairing disabled](/img/session-no-pairing.svg) - -![Pairing enabled](/img/session-pairing.svg) - + + + ![Pairing enabled](/img/session-pairing.svg) + + + ![Pairing disabled](/img/session-no-pairing.svg) + + ### Further reading -This page is concerned only with the IRMA protocol. For more technical information on IRMA in general, as well as explanations and definitions of some of the terms mentioned in this page, see the [technical overview](overview.md). +This page is concerned only with the IRMA protocol. For more technical information on IRMA in general, as well as explanations and definitions of some of the terms mentioned in this page, see the [technical overview](technical-overview.md). -This page does not deal with the cryptographic contents of the messages being passed nor how they achieve [IRMA's security properties](overview.md#irma-security-properties), only with how and when they are passed. IRMA being an implementation of the Idemix attribute-based credential scheme, details on the cryptographic contents and mechanisms of the messages may be found in the [Idemix specification](https://dominoweb.draco.res.ibm.com/reports/rz3730_revised.pdf) and in the [paper introducing Idemix](https://cs.brown.edu/people/alysyans/papers/camlys02b.pdf) by Camenisch and Lysyanskaya. +This page does not deal with the cryptographic contents of the messages being passed nor how they achieve [IRMA's security properties](technical-overview.md#irma-security-properties), only with how and when they are passed. IRMA being an implementation of the Idemix attribute-based credential scheme, details on the cryptographic contents and mechanisms of the messages may be found in the [Idemix specification](https://dominoweb.draco.res.ibm.com/reports/rz3730_revised.pdf) and in the [paper introducing Idemix](https://cs.brown.edu/people/alysyans/papers/camlys02b.pdf) by Camenisch and Lysyanskaya. ## Session creation -The [requestor](overview.md#participants) creates a session by sending a [session request](session-requests.md) for one of the three supported [session types](what-is-irma.md#session-types) to the [`POST /session`](api-irma-server.md#post-session) endpoint of the `irma server`, or by invoking the [`StartSession()`](https://pkg.go.dev/github.com/privacybydesign/irmago/server/irmaserver#Server.StartSession) function of the `irmaserver` Go library. If the IRMA server accepts the session (i.e., the session request is valid and the requestor is authorized to start sessions), the session is created and its state is set to [`INITIALIZED`](https://pkg.go.dev/github.com/privacybydesign/irmago#ServerStatusInitialized). This means that the IRMA server is waiting for the first HTTP request of the Yivi app, documented below. +The [requestor](technical-overview.md#participants) creates a session by sending a [session request](session-requests.md) for one of the three supported [session types](what-is-yivi.md#session-types) to the [`POST /session`](api-irma-server.md#post-session) endpoint of the `irma server`, or by invoking the [`StartSession()`](https://pkg.go.dev/github.com/privacybydesign/irmago/server/irmaserver#Server.StartSession) function of the `irmaserver` Go library. If the IRMA server accepts the session (i.e., the session request is valid and the requestor is authorized to start sessions), the session is created and its state is set to [`INITIALIZED`](https://pkg.go.dev/github.com/privacybydesign/irmago#ServerStatusInitialized). This means that the IRMA server is waiting for the first HTTP request of the Yivi app, documented below. When the requestor creates the session, the IRMA server responds with a [session package](api-irma-server.md#post-session). For example: @@ -92,45 +97,47 @@ X-Irma-Maxprotocolversion: 2.8 The server responds with an [`irma.ClientSessionRequest` instance](https://pkg.go.dev/github.com/privacybydesign/irmago#ClientSessionRequest), containing the protocol version that it chooses (the highest protocol version supported by both itself and by the app), the pairing code if device pairing is enabled, or the session request if not. For example: - - -```json -{ - "@context": "https://irma.app/ld/request/client/v1", - "protocolVersion": "2.8", - "options": { - "@context": "https://irma.app/ld/options/v1", - "pairingMethod": "pin", - "pairingCode": "1761" - } -} -``` - -```json -{ - "@context": "https://irma.app/ld/request/client/v1", - "protocolVersion": "2.8", - "options": { - "@context": "https://irma.app/ld/options/v1", - "pairingMethod": "none" - }, - "request": { - "@context": "https://irma.app/ld/request/disclosure/v2", - "context": "AQ==", - "nonce": "Il2FiK8uCIApjzkWeRouSQ==", - "protocolVersion": "2.8", - "devMode": true, - "disclose": [ - [ - [ - "pbdf.pbdf.irmatube.type" + + + ```json + { + "@context": "https://irma.app/ld/request/client/v1", + "protocolVersion": "2.8", + "options": { + "@context": "https://irma.app/ld/options/v1", + "pairingMethod": "pin", + "pairingCode": "1761" + } + } + ``` + + + ```json + { + "@context": "https://irma.app/ld/request/client/v1", + "protocolVersion": "2.8", + "options": { + "@context": "https://irma.app/ld/options/v1", + "pairingMethod": "none" + }, + "request": { + "@context": "https://irma.app/ld/request/disclosure/v2", + "context": "AQ==", + "nonce": "Il2FiK8uCIApjzkWeRouSQ==", + "protocolVersion": "2.8", + "devMode": true, + "disclose": [ + [ + [ + "pbdf.pbdf.irmatube.type" + ] + ] ] - ] - ] - } -} -``` - + } + } + ``` + + If device pairing is disabled, then the session state is set to [`CONNECTED`](https://pkg.go.dev/github.com/privacybydesign/irmago#ServerStatusConnected). Otherwise the session state is set to [`PAIRING`](https://pkg.go.dev/github.com/privacybydesign/irmago#ServerStatusPairing). In that case the Yivi app shows the `pairingCode` in the response above in its GUI, and instructs the user to type that into the frontend. It uses [`/irma/session/{clientToken}/statusevents`](api-irma-server.md#get-irma-session-clienttoken-statusevents) or polls to [`/irma/session/{clientToken}/status`](api-irma-server.md#get-irma-session-clienttoken-status) to keep track of the session status. After the user enters the pairing code into the frontend, the frontend invokes the [`POST /irma/session/{clientToken}/frontend/pairingcompleted` endpoint](api-irma-server.md#post-irma-session-clienttoken-frontend-pairingcompleted), triggering the IRMA server to switch the session status to `CONNECTED`. When that happens the Yivi app notices through a server-sent event or through its polling, after which it invokes the below endpoint to retrieve the session request. @@ -227,7 +234,7 @@ i.Rsh(i, 1) fmt.Println(string(i.Bytes())) ``` -Note that attribute `1` is the [metadata attribute](overview.md#the-metadata-attribute), containing among others the credential type and the expiry date of the credential in a custom encoding. This attribute is always disclosed. The above snippet will not output anything sensible for metadata attributes, but instead the [`irma` command line tool](irma-cli.md) can be used as follows. +Note that attribute `1` is the [metadata attribute](technical-overview.md#the-metadata-attribute), containing among others the credential type and the expiry date of the credential in a custom encoding. This attribute is always disclosed. The above snippet will not output anything sensible for metadata attributes, but instead the [`irma` command line tool](irma-cli.md) can be used as follows. ```text $ irma meta "AwAKhwAaAAXZZxdMn4TvQ6F/mVxWb6a7" @@ -315,7 +322,7 @@ The app POSTs an [`irma.IssueCommitmentMessage` instance](https://pkg.go.dev/git } ``` -The `combinedProofs` array contains, for each credential being issued within the session (one in this example), a [zero-knowledge proof](zkp.md) of the Yivi app's secret key (which will become [the first attribute](overview.md#the-secret-key-attribute) of the credential(s) being issued). In addition, in case of [combined disclosure-issuance sessions](session-requests.md#issuance-requests) this array will also contain [`gabi.ProofD`](https://pkg.go.dev/github.com/privacybydesign/gabi#ProofD) instances, like the `proofs` array in [disclosure sessions](irma-protocol.md#disclosure-post-irma-session-clienttoken-proofs). +The `combinedProofs` array contains, for each credential being issued within the session (one in this example), a [zero-knowledge proof](zkp.md) of the Yivi app's secret key (which will become [the first attribute](technical-overview.md#the-secret-key-attribute) of the credential(s) being issued). In addition, in case of [combined disclosure-issuance sessions](session-requests.md#issuance-requests) this array will also contain [`gabi.ProofD`](https://pkg.go.dev/github.com/privacybydesign/gabi#ProofD) instances, like the `proofs` array in [disclosure sessions](irma-protocol.md#disclosure-post-irma-session-clienttoken-proofs). When responding to this HTTP request (see below) with its signature(s) over the attributes, the IRMA server includes a zero-knowledge proof of its own, proving that it correctly constructed its signatures. The `n_2` field contains the nonce over which the issuer is to construct that zero-knowledge proof (c.f. the `nonce` in the session request, see [above](irma-protocol.md#get-irma-session-clienttoken-request)). diff --git a/yivi-docs/docs/irma-server.md b/yivi-docs/docs/irma-server.md index 15890bf..f1edf39 100644 --- a/yivi-docs/docs/irma-server.md +++ b/yivi-docs/docs/irma-server.md @@ -4,7 +4,7 @@ title: irma server `irma server` is an IRMA server executable (daemon) allowing you to perform IRMA sessions with -[Yivi apps](yivi-app.md). It handles all IRMA-specific cryptographic details of issuing or verifying IRMA attributes with an Yivi app on behalf of a [requestor](overview.md#participants) (the application wishing to verify or issue attributes). It exposes the following: +[Yivi apps](yivi-app.md). It handles all IRMA-specific cryptographic details of issuing or verifying IRMA attributes with an Yivi app on behalf of a [requestor](technical-overview.md#participants) (the application wishing to verify or issue attributes). It exposes the following: * HTTP endpoints under `/irma`, used by the Yivi app during IRMA sessions * a JSON API under `/sessions` for requestors, allowing them to request the server to verify or issue attributes. @@ -147,10 +147,10 @@ Assuming the URL of the `irma server` is `http://example.com`, the session confi } ``` -Only static [disclosure or attribute-based signature sessions](what-is-irma.md#session-types) are supported. +Only static [disclosure or attribute-based signature sessions](what-is-yivi.md#session-types) are supported. ### Permissions -For each of the [three IRMA session types](what-is-irma.md#session-types) (attribute verification; attribute-based signature sessions; and attribute issuance), permission to use specific attributes/credentials can be granted to requestors in the configuration. For example, including permissions in the `myapp` requestor from above: +For each of the [three IRMA session types](what-is-yivi.md#session-types) (attribute verification; attribute-based signature sessions; and attribute issuance), permission to use specific attributes/credentials can be granted to requestors in the configuration. For example, including permissions in the `myapp` requestor from above: ```json { "requestors": { diff --git a/yivi-docs/docs/issuer.md b/yivi-docs/docs/issuer.md index 38d2a8c..16173df 100644 --- a/yivi-docs/docs/issuer.md +++ b/yivi-docs/docs/issuer.md @@ -91,7 +91,7 @@ Some notes: - By specifying it explicitly using the `-c` or `--counter` flag. - By running `irma issuer keygen` within your issuer folder in the scheme; it will then infer the appropriate counter using the public keys already present in the `PublicKeys` folder. - Alternatively, after generating the keypair you can open the private and public keys in a text editor and set the `` tag to the appropriate number. -* 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](overview.md#special-attributes)) must be passed to the `-a` or `--numattributes` flag, to ensure that the new public key supports the required amount of attributes. +* 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](technical-overview.md#special-attributes)) must be passed to the `-a` or `--numattributes` flag, to ensure that the new public key supports the required amount of attributes. ## Issuer maintenance diff --git a/yivi-docs/docs/keyshare-protocol.md b/yivi-docs/docs/keyshare-protocol.md index 0969c4a..f2d55f2 100644 --- a/yivi-docs/docs/keyshare-protocol.md +++ b/yivi-docs/docs/keyshare-protocol.md @@ -6,7 +6,7 @@ This document describes the goals and details of the IRMA keyshare protocol. ## Introduction -The [IRMA mobile app](yivi-app.md) allows users to obtain and disclose [IRMA attributes](overview.md#cryptographic-entities), as well as attach them to signed statements. Before such an IRMA session proceeds, the Yivi app may ask the user to enter her IRMA PIN code so that the [requestor](overview.md#participants) can be sure that it is indeed the attribute owner initiating the session (as opposed to, e.g., a thief of the user's phone). The verification of the correctness of the IRMA PIN code, and preventing the session from happening when it is not, is the responsibility of the [IRMA keyshare server](https://github.com/privacybydesign/irma_keyshare_server). In order to do this, it interacts with the Yivi app and possibly the IRMA server in a protocol that we call the *keyshare protocol*. This protocol is documented here. +The [IRMA mobile app](yivi-app.md) allows users to obtain and disclose [IRMA attributes](technical-overview.md#cryptographic-entities), as well as attach them to signed statements. Before such an IRMA session proceeds, the Yivi app may ask the user to enter her IRMA PIN code so that the [requestor](technical-overview.md#participants) can be sure that it is indeed the attribute owner initiating the session (as opposed to, e.g., a thief of the user's phone). The verification of the correctness of the IRMA PIN code, and preventing the session from happening when it is not, is the responsibility of the [IRMA keyshare server](https://github.com/privacybydesign/irma_keyshare_server). In order to do this, it interacts with the Yivi app and possibly the IRMA server in a protocol that we call the *keyshare protocol*. This protocol is documented here. Each [IRMA scheme](schemes.md) decides whether or not it employs an IRMA keyshare server. If it does, then this keyshare server is involved in any IRMA session that involves attributes that fall under the scheme manager's responsibility. diff --git a/yivi-docs/docs/randomblind.md b/yivi-docs/docs/randomblind.md index b8bc8b7..832556d 100644 --- a/yivi-docs/docs/randomblind.md +++ b/yivi-docs/docs/randomblind.md @@ -165,7 +165,7 @@ attributes the following system can be realized: votes), the user must be uniquely identified in this stage. 2. (Casting the vote). To vote, a user creates an [attribute-based - signature](overview/#attribute-based-signatures) on a + signature](technical-overview/#attribute-based-signatures) on a "ballot" string, i.e., the user's choice using the randomblind attribute acquired in the previous step. This signature, the choice and the attribute are then registered in a database at party B. The signature ensures diff --git a/yivi-docs/docs/revocation.md b/yivi-docs/docs/revocation.md index 4e9e420..b09459f 100644 --- a/yivi-docs/docs/revocation.md +++ b/yivi-docs/docs/revocation.md @@ -11,7 +11,7 @@ This page explains in detail how revocation is implemented in IRMA and what it m ## Overview -Revocation in IRMA is an implementation of the RSA-B scheme from ["Accumulators with applications to anonymity-preserving revocation"](https://eprint.iacr.org/2017/043.pdf) by Baldimtsi et al, which in turn is based on ["Dynamic accumulators and application to efficient revocation of anonymous credentials"](http://static.cs.brown.edu/people/alysyans/papers/camlys02.pdf) by Camenisch et al. Using this scheme the app can prove nonrevocation of its credential in zero-knowledge, preserving [unlinkability of multiple disclosures](overview.md#irma-security-properties) of the attributes within the credential. +Revocation in IRMA is an implementation of the RSA-B scheme from ["Accumulators with applications to anonymity-preserving revocation"](https://eprint.iacr.org/2017/043.pdf) by Baldimtsi et al, which in turn is based on ["Dynamic accumulators and application to efficient revocation of anonymous credentials"](http://static.cs.brown.edu/people/alysyans/papers/camlys02.pdf) by Camenisch et al. Using this scheme the app can prove nonrevocation of its credential in zero-knowledge, preserving [unlinkability of multiple disclosures](technical-overview.md#irma-security-properties) of the attributes within the credential. In IRMA, revocation is enabled per credential type in the IRMA scheme. If so, when properly configured (more on that [below](#revocation-settings)) the issuer's IRMA server will issue revocation-enabled credentials of that type. During disclosures the Yivi app can then prove nonrevocation (but it will only do so if explicitly asked for by the requestor). diff --git a/yivi-docs/docs/schemes.md b/yivi-docs/docs/schemes.md index 817ddc1..b151d9e 100644 --- a/yivi-docs/docs/schemes.md +++ b/yivi-docs/docs/schemes.md @@ -2,7 +2,10 @@ title: IRMA schemes --- -In IRMA, every party ([Yivi apps](yivi-app.md), [IRMA servers](what-is-irma.md#irma-servers), [requestors](overview.md#participants)) must be aware of existing [credential types](overview.md#credential-types), attribute names, and the [issuers](overview.md#issuers) and their public keys. All such information is contained in IRMA *schemes*. It is the task of the *scheme manager* to determine and distribute this information to all parties, in the form of a directory structure [such as this one](https://github.com/privacybydesign/pbdf-schememanager), which contains: +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +In IRMA, every party ([Yivi apps](yivi-app.md), [IRMA servers](what-is-yivi.md#irma-servers), [requestors](technical-overview.md#participants)) must be aware of existing [credential types](technical-overview.md#credential-types), attribute names, and the [issuers](technical-overview.md#issuers) and their public keys. All such information is contained in IRMA *schemes*. It is the task of the *scheme manager* to determine and distribute this information to all parties, in the form of a directory structure [such as this one](https://github.com/privacybydesign/pbdf-schememanager), which contains: * All information about all issuers that fall under this scheme including their logos, * The IRMA public keys of said issuers, @@ -62,21 +65,22 @@ The `description.xml` of a credential type contains the definitions, including t These identifiers are used to refer to these entities within [IRMA session requests](session-requests.md), joined together using a dot `.` as separator. For example, the `description.xml` [below](#credential-types) shows the definition of the credential type `credentialtype-id` included in the directory tree above. This file contains an attribute whose identifier, as defined by the `id` XML attribute, is `boolean-attr`. Then the following would be a valid IRMA disclosure request that requests an Yivi app user to disclose this attribute: - - -```json -{ - "@context": "https://irma.app/ld/request/disclosure/v2", - "disclose": [[[ "scheme-id.issuer-id.credentialtype-id.boolean-attr" ]]] -} -``` - -```golang -irma.NewDisclosureRequest(irma.NewAttributeTypeIdentifier( - "scheme-id.issuer-id.credentialtype-id.boolean-attr", -)) -``` - + + + ```json + { + "@context": "https://irma.app/ld/request/disclosure/v2", + "disclose": [[[ "scheme-id.issuer-id.credentialtype-id.boolean-attr" ]]] + } + + + ```golang + irma.NewDisclosureRequest(irma.NewAttributeTypeIdentifier( + "scheme-id.issuer-id.credentialtype-id.boolean-attr", + )) + ``` + + IRMA identifiers may not themselves contain dots. Generally, only alphanumeric characters and the dash `-`are used. diff --git a/yivi-docs/docs/session-requests.md b/yivi-docs/docs/session-requests.md index 689a13c..931aab0 100644 --- a/yivi-docs/docs/session-requests.md +++ b/yivi-docs/docs/session-requests.md @@ -2,17 +2,20 @@ title: Session requests --- -Each [IRMA server](what-is-irma.md#irma-servers) exposes APIs for creating IRMA sessions with a session request. An *IRMA session request* contains all information required for the IRMA server and [Yivi app](yivi-app.md) to perform an IRMA session with, such as the attributes to be issued or verified. This page documents IRMA session requests. It applies to: +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +Each [IRMA server](what-is-yivi.md#irma-servers) exposes APIs for creating IRMA sessions with a session request. An *IRMA session request* contains all information required for the IRMA server and [Yivi app](yivi-app.md) to perform an IRMA session with, such as the attributes to be issued or verified. This page documents IRMA session requests. It applies to: * The [`POST /session`](api-irma-server.md#post-session) endpoint from [`irma server`](irma-server.md). * The [`StartSession()` function](https://godoc.org/github.com/privacybydesign/irmago/server/irmaserver#StartSession) in the `irmaserver` Go library. * The [`startSession()` function](api-irmajs.md#startsession) of `irmajs`. -For the precise role of session requests in an IRMA session, see this [diagram of an IRMA session](what-is-irma.md#irma-session-flow). +For the precise role of session requests in an IRMA session, see this [diagram of an IRMA session](what-is-yivi.md#irma-session-flow). ## Session request data types -For each of the [three IRMA session types](what-is-irma.md#session-types), we define a *session request* data type: an object whose JSON representation contains at least a [JSON-LD `@context`](https://w3c.github.io/json-ld-syntax/#the-context) key identifying which message type it is, and extra keys specific to the session type. The following three `@context` values identify disclosure, attribute-based signature, and issuance session requests respectively: +For each of the [three IRMA session types](what-is-yivi.md#session-types), we define a *session request* data type: an object whose JSON representation contains at least a [JSON-LD `@context`](https://w3c.github.io/json-ld-syntax/#the-context) key identifying which message type it is, and extra keys specific to the session type. The following three `@context` values identify disclosure, attribute-based signature, and issuance session requests respectively: * `"@context": "https://irma.app/ld/request/disclosure/v2"` * `"@context": "https://irma.app/ld/request/signature/v2"` @@ -23,56 +26,58 @@ For each of the [three IRMA session types](what-is-irma.md#session-types), we de ## Disclosure requests Disclosure sessions are started with an [`irma.DisclosureRequest`](https://godoc.org/github.com/privacybydesign/irmago#DisclosureRequest). Example: - - - -```json -{ - "@context": "https://irma.app/ld/request/disclosure/v2", - "disclose": [ - [ - [ "irma-demo.MijnOverheid.root.BSN" ] - ], - [ + + + ```json + { + "@context": "https://irma.app/ld/request/disclosure/v2", + "disclose": [ [ - "irma-demo.nijmegen.address.street", - "irma-demo.nijmegen.address.houseNumber", - "irma-demo.nijmegen.address.city" + [ "irma-demo.MijnOverheid.root.BSN" ] ], [ - "irma-demo.idin.idin.address", - "irma-demo.idin.idin.city" + [ + "irma-demo.nijmegen.address.street", + "irma-demo.nijmegen.address.houseNumber", + "irma-demo.nijmegen.address.city" + ], + [ + "irma-demo.idin.idin.address", + "irma-demo.idin.idin.city" + ] ] ] - ] -} -``` - -```golang -// Create a new empty request -request := irma.NewDisclosureRequest() - -// Request specific attributes -request.Disclose = irma.AttributeConDisCon{ - irma.AttributeDisCon{ - irma.AttributeCon{irma.NewAttributeRequest("irma-demo.MijnOverheid.root.BSN")}, - }, - irma.AttributeDisCon{ - irma.AttributeCon{ - irma.NewAttributeRequest("irma-demo.nijmegen.address.street"), - irma.NewAttributeRequest("irma-demo.nijmegen.address.houseNumber"), - irma.NewAttributeRequest("irma-demo.nijmegen.address.city"), - }, - irma.AttributeCon{ - irma.NewAttributeRequest("irma-demo.idin.idin.address"), - irma.NewAttributeRequest("irma-demo.idin.idin.city"), - }, - }, -} -``` - -condiscon - + } + ``` + + + ```golang + // Create a new empty request + request := irma.NewDisclosureRequest() + + // Request specific attributes + request.Disclose = irma.AttributeConDisCon{ + irma.AttributeDisCon{ + irma.AttributeCon{irma.NewAttributeRequest("irma-demo.MijnOverheid.root.BSN")}, + }, + irma.AttributeDisCon{ + irma.AttributeCon{ + irma.NewAttributeRequest("irma-demo.nijmegen.address.street"), + irma.NewAttributeRequest("irma-demo.nijmegen.address.houseNumber"), + irma.NewAttributeRequest("irma-demo.nijmegen.address.city"), + }, + irma.AttributeCon{ + irma.NewAttributeRequest("irma-demo.idin.idin.address"), + irma.NewAttributeRequest("irma-demo.idin.idin.city"), + }, + }, + } + ``` + + + condiscon + + This asks for a (demo) `BSN` attribute, as well as either `street`, `houseNumber` and `city` from `irma-demo.nijmegen.address`, or `address` and `city` from `irma-demo.idin.idin`. The three levels correspond to a *conjunction* of *disjunctions* of *conjunctions* of requested attributes, allowing verifiers to request multiple attribute sets from the user, offering choices for some or all of these sets. @@ -83,38 +88,41 @@ All of the attribute types (i.e., the string values) contained in the request mu ### Multiple credential types within inner conjunctions In the request above we call the three JSON lists that contain strings *inner conjunctions* (distinguishing them from the *outer conjunctions*, that contain not attribute but disjunctions). Asking for multiple attributes within such an inner conjunctions of a session request is subject to the following rules: -- When attributes coming from multiple credential types occur in an inner conjunction, at most one of them may be a non-[singleton](overview.md#singletons). +- When attributes coming from multiple credential types occur in an inner conjunction, at most one of them may be a non-[singleton](technical-overview.md#singletons). - If some of the attributes occuring in the inner conjunction come from the same credential type, then the attributes that the user sends must come from the same credential instance: it is not allowed to mix attributes coming from distinct instances of that credential type. (The Yivi app automatically only offers candidate sets as choices to the user that satisfy this property.) For example, consider the following session request: - - -```json -{ - "@context": "https://irma.app/ld/request/disclosure/v2", - "disclose": [ - [ + + + + ```json + { + "@context": "https://irma.app/ld/request/disclosure/v2", + "disclose": [ [ - "pbdf.pbdf.diploma.degree", - "pbdf.pbdf.diploma.institute" + [ + "pbdf.pbdf.diploma.degree", + "pbdf.pbdf.diploma.institute" + ] ] ] - ] -} -``` - -```golang -request := irma.NewDisclosureRequest() -request.Disclose = irma.AttributeConDisCon{ - irma.AttributeDisCon{ - irma.AttributeCon{ - irma.NewAttributeRequest("pbdf.pbdf.diploma.degree"), - irma.NewAttributeRequest("pbdf.pbdf.diploma.institute"), - }, - }, -} -``` - + } + ``` + + + ```golang + request := irma.NewDisclosureRequest() + request.Disclose = irma.AttributeConDisCon{ + irma.AttributeDisCon{ + irma.AttributeCon{ + irma.NewAttributeRequest("pbdf.pbdf.diploma.degree"), + irma.NewAttributeRequest("pbdf.pbdf.diploma.institute"), + }, + }, + } + ``` + + Supposing that the user has two instances of `pbdf.pbdf.diploma` whose `degree` and `institute` attributes are `(degree 1, institute 1)` and `(degree 2, institute 2)`, this means that the user can choose only either `(degree 1, institute 1)` or `(degree 2, institute 2)`, and not `(degree 1, institute 2)` or `(degree 2, institute 1)`. (If desired it would be possible to give the user those options by asking for the two attributes in two *outer* conjunctions instead of within an *inner* conjunction.) @@ -122,38 +130,41 @@ When combining multiple credential types within a disjunction these restrictions ### Requesting specific attribute values Within inner conjunctions, specific attribute values can be requested by replacing the string with an object like the following: - - -```json -{ - "@context": "https://irma.app/ld/request/disclosure/v2", - "disclose": [ - [ - [ - { "type": "pbdf.pbdf.diploma.degree", "value": "PhD" }, - { "type": "pbdf.pbdf.diploma.institute", "value": null } + + + + ```json + { + "@context": "https://irma.app/ld/request/disclosure/v2", + "disclose": [ + [ + [ + { "type": "pbdf.pbdf.diploma.degree", "value": "PhD" }, + { "type": "pbdf.pbdf.diploma.institute", "value": null } + ] + ] ] - ] - ] -} -``` - -```go -phd := "PhD" -request := irma.NewDisclosureRequest() -request.Disclose = irma.AttributeConDisCon{ - irma.AttributeDisCon{ - irma.AttributeCon{{ - Type: irma.NewAttributeTypeIdentifier("pbdf.pbdf.diploma.degree"), - Value: &phd, - }, { - Type: irma.NewAttributeTypeIdentifier("pbdf.pbdf.diploma.institute"), - Value: nil, - }}, - }, -} -``` - + } + ``` + + + ```go + phd := "PhD" + request := irma.NewDisclosureRequest() + request.Disclose = irma.AttributeConDisCon{ + irma.AttributeDisCon{ + irma.AttributeCon{{ + Type: irma.NewAttributeTypeIdentifier("pbdf.pbdf.diploma.degree"), + Value: &phd, + }, { + Type: irma.NewAttributeTypeIdentifier("pbdf.pbdf.diploma.institute"), + Value: nil, + }}, + }, + } + ``` + + This would only be satisfied by a `degree` attribute whose value is `PhD`, together with any `institute` attribute. (Note that the object and string syntaxes can be mixed within an inner conjunction, i.e. it would be permissible in the JSON example above to replace the second object with just `"pbdf.pbdf.diploma.institute"`.) @@ -162,41 +173,45 @@ This would only be satisfied by a `degree` attribute whose value is `PhD`, toget Whenever an attribute is marked with `optional` in the scheme ([example](https://github.com/privacybydesign/irma-demo-schememanager/blob/482ba298ee038ea43bd0cf8017567a844be0919e/MijnOverheid/Issues/fullName/description.xml#L54)), the issuer may skip it when it issues an instance of the containing credential type, assigning a `null` value to it (which is distinct from the empty string `""`). When disclosing the attribute, the verifier receives `null` instead of a string containing the attribute value. If a non-null attribute is required this can be requested using `notNull` as follows: - - -```json -{ - "@context": "https://irma.app/ld/request/disclosure/v2", - "disclose": [ - [ + + + + ```json + { + "@context": "https://irma.app/ld/request/disclosure/v2", + "disclose": [ [ - { "type": "irma-demo.MijnOverheid.fullName.prefix", "notNull": true } + [ + { "type": "irma-demo.MijnOverheid.fullName.prefix", "notNull": true } + ] ] ] - ] -} -``` - -```go -request := irma.NewDisclosureRequest() -request.Disclose = irma.AttributeConDisCon{ - irma.AttributeDisCon{ - irma.AttributeCon{{ - Type: irma.NewAttributeTypeIdentifier("irma-demo.MijnOverheid.fullName.prefix"), - NotNull: true, - }}, - }, -} -``` - + } + ``` + + + ```go + request := irma.NewDisclosureRequest() + request.Disclose = irma.AttributeConDisCon{ + irma.AttributeDisCon{ + irma.AttributeCon{{ + Type: irma.NewAttributeTypeIdentifier("irma-demo.MijnOverheid.fullName.prefix"), + NotNull: true, + }}, + }, + } + ```` + + The default value of `notNull` is `false`. ### Optional disjunctions A disjunction within a session request can be marked as *optional*, by including an empty inner conjunction in it: - - + + + ```json { "@context": "https://irma.app/ld/request/disclosure/v2", @@ -211,7 +226,8 @@ A disjunction within a session request can be marked as *optional*, by including ] } ``` - + + ```go request := irma.NewDisclosureRequest() request.Disclose = irma.AttributeConDisCon{ @@ -224,44 +240,14 @@ request.Disclose = irma.AttributeConDisCon{ }, } ``` - + + optional-disjunction - + + This can be useful when certain attributes are not required, so that if the user does not have them the session does not need to be aborted. -### Disjunction labels - -Per disjunction a *label* can be specified, which is shown in the Yivi app when the user is asked for permission to disclose attributes. For example, the session request from [above](#disclosure-requests) could be augmented with a label for the second disjunction as follows: - - - - -```json -{ - "@context": "https://irma.app/ld/request/disclosure/v2", - "disclose": [ - [ ... ], - [ ... ] - ], - "labels": { - "1": { "en": "Work address", "nl": "Werk adres" } - } -} -``` - -```go -request := irma.NewDisclosureRequest() -request.Labels = map[int]irma.TranslatedString{ - 1: {"en": "Work address", "nl": "Werk adres"}, -} -``` - -condiscon-label - - -In this way each disjunction can be given a optional label explaining to the user the purpose of the disjunction. It is recommended to only provide a label to explain something to the user that would otherwise not be obvious; for example, to request the user to send a work email address instead of a personal one. Repeating the credential or attribute name or description in labels is an antipattern. - ### Skip expiry check You can allow users to disclose expired instances of credentials. This is useful for [combined issuance-disclosure sessions](session-requests.md#issuance-requests) and [chained sessions](chained-sessions.md) if you only want to ensure that the user is still using the same device, and therefore the same [secret key](zkp.md), as during a previous issuance session. @@ -281,8 +267,9 @@ You can allow users to disclose expired instances of credentials. This is useful ## Attribute-based signature requests Attribute-based signature sessions are started with an [`irma.SignatureRequest`](https://godoc.org/github.com/privacybydesign/irmago#SignatureRequest), which are similar to disclosure requests: - - + + + ```json { "@context": "https://irma.app/ld/request/signature/v2", @@ -291,20 +278,23 @@ Attribute-based signature sessions are started with an [`irma.SignatureRequest`] "labels": ... } ``` - + + ```go request := irma.NewSignatureRequest("Message to be signed by user") request.Disclose = irma.AttributeConDisCon{ /* request attributes to attach to ABS */ } request.Labels = map[int]irma.TranslatedString{} ``` - + + The `message` field is required. The attributes to be attached to the attribute-based signature are requested with the `disclose` field, which along with the `labels` field work exactly like in disclosure sessions. ## Issuance requests Issuance sessions are started with an [`irma.IssuanceRequest`](https://godoc.org/github.com/privacybydesign/irmago#IssuanceRequest). Example: - - + + + ```json { "@context": "https://irma.app/ld/request/issuance/v2", @@ -322,7 +312,8 @@ Issuance sessions are started with an [`irma.IssuanceRequest`](https://godoc.org "labels": ... } ``` - + + ```go validity := irma.Timestamp(time.Unix(1592438400, 0)) request := irma.NewIssuanceRequest([]*irma.CredentialRequest{ @@ -340,9 +331,10 @@ request := irma.NewIssuanceRequest([]*irma.CredentialRequest{ request.Disclose = irma.AttributeConDisCon{} // optional request.Labels = map[int]irma.TranslatedString{} // optional ``` - + + -Per credential in the `credentials` array the `validity` is optional; if skipped it is assigned the default value of 6 months. If present, the validity is always rounded down to the [nearest epoch boundary](overview.md#special-attributes), which is one week (60 * 60 * 24 * 7 = 604800 seconds). +Per credential in the `credentials` array the `validity` is optional; if skipped it is assigned the default value of 6 months. If present, the validity is always rounded down to the [nearest epoch boundary](technical-overview.md#special-attributes), which is one week (60 * 60 * 24 * 7 = 604800 seconds). Attributes marked as `optional` in the containing credential type ([example](https://github.com/privacybydesign/irma-demo-schememanager/blob/482ba298ee038ea43bd0cf8017567a844be0919e/MijnOverheid/Issues/fullName/description.xml#L54)) may be skipped in the `attributes` map. This issues [the `null` value](#null-attributes) to these attributes. @@ -353,8 +345,8 @@ The `clientReturnUrl` option can also be used, both for issuance only and combin ## Client return URL If the user performs a mobile session, i.e. on the same device as where the Yivi app is installed on, then after the session has completed the user will be redirect to the `clientReturnUrl` specified in the session request, if present. - - + + ```json { "@context": "https://irma.app/ld/request/disclosure/v2", @@ -364,12 +356,14 @@ If the user performs a mobile session, i.e. on the same device as where the Yivi "clientReturnUrl": "https://example.com" } ``` - + + ```go request := irma.NewDisclosureRequest() request.ClientReturnURL = "https://example.com" ``` - + + The example shows a disclosure request but `clientReturnUrl` can be set on session requests of any type. If set, when the user finishes a session (either successfully or unsuccessfully), she is redirected to the location specified by `clientReturnUrl`. @@ -386,8 +380,9 @@ On iOS, toggling back to the calling app or website after the session can be sim It is possible to have the IRMA server augment the `clientReturnUrl` with the server token of a session (i.e., the `token` in the [response of the `/session` endpoint](api-irma-server.md#post-session)). This token is then appended as a query parameter with name `token` to the `clientReturnUrl`. Using this token, one can the retrieve the [session result](api-irma-server.md#get-session-token-result). To enable this, both the server configuration flag `augment-client-return-url` needs to be enabled, as well as the `augmentReturnUrl` session request parameter needs to be true. - - + + + ```json { "@context": "https://irma.app/ld/request/disclosure/v2", @@ -398,13 +393,15 @@ To enable this, both the server configuration flag `augment-client-return-url` n "clientReturnUrl": "https://example.com" } ``` - + + ```go request := irma.NewDisclosureRequest() request.ClientReturnURL = "https://example.com" request.AugmentReturnURL = true ``` - + + In this example, the client return url would be augmented to become `https://example.com?token=0123456789abcdef`, where `0123456789abcdef` would be the server token of the session. @@ -437,8 +434,9 @@ When you use `irma server`, you should explicitly specify [requestor permissions ## Extra parameters For each API that accepts one of the above session request data types, the requestor can provide additional parameters to configure the session at the IRMA server, by providing an *extended session request* instead, as follows: - - + + + ```json { "validity": 120, @@ -450,7 +448,8 @@ For each API that accepts one of the above session request data types, the reque "request": ... } ``` - + + ```go // See also corresponding types irma.SignatureRequestorRequest // and irma.IdentityProviderRequest @@ -464,7 +463,8 @@ irma.ServiceProviderRequest{ irma.NewDisclosureRequest(), } ``` - + + Below you can find an overview of all extra parameters and their default value. @@ -478,29 +478,32 @@ Below you can find an overview of all extra parameters and their default value. More information about session lifetimes and timeouts can be found in the [IRMA server documentation](irma-server.md#session-lifetime). ## JWTs: signed session requests -The IRMA API server or [`irma server`](irma-server.md) can be configured such that it only accepts session requests that have been digitally signed in the form of a [JWT](https://jwt.io). The form of the JWT depends on the [session type](what-is-irma.md#session-types). An example requesting [IRMATube](https://privacybydesign.foundation/demo/irmaTube) attributes:: +The IRMA API server or [`irma server`](irma-server.md) can be configured such that it only accepts session requests that have been digitally signed in the form of a [JWT](https://jwt.io). The form of the JWT depends on the [session type](what-is-yivi.md#session-types). An example requesting [IRMATube](https://privacybydesign.foundation/demo/irmaTube) attributes:: ``` eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImlybWF0dWJlIn0.eyJpYXQiOjE1NjQ2NTczNzUsInN1YiI6InZlcmlmaWNhdGlvbl9yZXF1ZXN0Iiwic3ByZXF1ZXN0Ijp7InJlcXVlc3QiOnsiQGNvbnRleHQiOiJodHRwczovL2lybWEuYXBwL2xkL3JlcXVlc3QvZGlzY2xvc3VyZS92MiIsImRpc2Nsb3NlIjpbW1sicGJkZi5wYmRmLmlybWF0dWJlLnR5cGUiXV0sW1sicGJkZi5wYmRmLmFnZUxpbWl0cy5vdmVyMTIiXSxbInBiZGYuZ2VtZWVudGUucGVyc29uYWxEYXRhLm92ZXIxMiJdXV19fX0.lW9mqjrLkoahDP6Fcw_9mH5hlfl1tq5qp3W3ga0Nrd_j0NXFj-6ngqHVXEV1zhC_OkVH4LN8fMBAgN8nqaFWgEdQvrCuB7-ynuBVjLR-QU272Ym86zLEWYggAkbZ5KY40MpTxU1dgFMucG7fyAESic04OribWOCVxstAMsM28yCxvzkBMCOSjFEe3abcg_N6VvQnLn3LgZP_UrxQmQsh4DK7mBjW04LesLG1vjcliyhDGUb52FHOP_NAsG7G2FvIgojPzALlPrpTMu5p8a95wc5CGR791wybmh0F8kDdwZWAU0W2FjlX5bNPsyXN8AxRVWaRmWoGrGsQhy_sKEf8lg ``` In case of disclosure sessions, the body of the JWT (the part in between the two dots) contains a Base64-encoding of the following: - - -```json -{ - "iat": 1550424847, - "sub": "verification_request", - "sprequest": ... -} -``` - -```go -// Sets iat, iss, and sub fields. -// See also corresponding functions irma.NewSignatureRequestorJwt() -// and irma.NewIdentityProviderJwt(). -// Obtain signed JWT string to POST to an irma server using Sign() method. -irma.NewServiceProviderJwt("IRMATube", irma.NewDisclosureRequest()) -``` - + + + + ```json + { + "iat": 1550424847, + "sub": "verification_request", + "sprequest": ... + } + ``` + + + ```go + // Sets iat, iss, and sub fields. + // See also corresponding functions irma.NewSignatureRequestorJwt() + // and irma.NewIdentityProviderJwt(). + // Obtain signed JWT string to POST to an irma server using Sign() method. + irma.NewServiceProviderJwt("IRMATube", irma.NewDisclosureRequest()) + ``` + + The fields are as follows: * `iat`: Unix timestamp of the creation date of the JWT. IRMA servers may reject JWTs beyond a certain age. diff --git a/yivi-docs/docs/overview.md b/yivi-docs/docs/technical-overview.md similarity index 99% rename from yivi-docs/docs/overview.md rename to yivi-docs/docs/technical-overview.md index 4f557ac..2a4a140 100644 --- a/yivi-docs/docs/overview.md +++ b/yivi-docs/docs/technical-overview.md @@ -146,7 +146,7 @@ IRMA attribute-based signatures can be used in any case where conventional (digi Technically, IRMA attribute-based signatures are very similar to disclosure proofs. As mentioned earlier IRMA disclosures use a challenge-response protocol: the verifier generates a random number called the nonce and sends it to the Yivi app, whose response has to take this nonce into account in a precise fashion (this is achieved using the [Fiat-Shamir heuristic](https://en.wikipedia.org/wiki/Fiat%E2%80%93Shamir_heuristic)). More precisely, the disclosure proof is a digital signature on the nonce that was used; if the nonce was freshly generated then the verifier can be sure that the attribute owner is actually present instead of replaying an earlier or eavesdropped disclosure proof. An IRMA attribute-based signature is the same except that not a nonce but an actual message is signed (or rather its SHA256 hash). -Currently IRMA only supports creating attribute-based signatures on strings, although we plan to support other types of documents as well. They can be created using [irmajs](https://github.com/privacybydesign/irmajs) and verified using [IRMA servers](what-is-irma.md#irma-servers) almost the same as disclosure proofs. An online demo is available on the [website of the Foundation](https://privacybydesign.foundation/demo/ondertekenen/). +Currently IRMA only supports creating attribute-based signatures on strings, although we plan to support other types of documents as well. They can be created using [irmajs](https://github.com/privacybydesign/irmajs) and verified using [IRMA servers](what-is-yivi.md#irma-servers) almost the same as disclosure proofs. An online demo is available on the [website of the Foundation](https://privacybydesign.foundation/demo/ondertekenen/). ## IRMA security properties diff --git a/yivi-docs/docs/what-is-irma.md b/yivi-docs/docs/what-is-yivi.md similarity index 92% rename from yivi-docs/docs/what-is-irma.md rename to yivi-docs/docs/what-is-yivi.md index e69263e..a1d3e67 100644 --- a/yivi-docs/docs/what-is-irma.md +++ b/yivi-docs/docs/what-is-yivi.md @@ -8,7 +8,7 @@ Yivi's roots lie within Radboud University. Back in the day, its code name was I Schematically: -
+