Updates to enable the backwords compatibility and transitioning to did:peer:2/4 and all qualified DIDs

[swcurran]

In looking at the approach that has evolved in release 0.12.0 for handling the transition to the use of qualified DIDs only, we've decided on the following changes to the current implementation:

• Remove the new configuration parameters that were added as part of 0.12.0 --emit-did-peer-2 and --emit-did-peer-4.
  • Remove them as well from the "per-tenant" settings list of parameters.
  • We've decide that finer grained control is needed at the point of creating invitations and DID Exchange requests is more useful than configuration settings.
• A use_did parameter will be added to the outofband/create_invitation that takes either
  • a DID Method (options: did:peer:2 did:peer:4) so that a DID of that type is created (if necessary), and used in the invitation. If a DID of the type has to be created, it is flagged as the "invitation" DID and used in all future invitations so that connection reuse is the default behaviour.
    • This is the recommend approach, and we further recommend using did:peer:4.
    • Some care is needed when the DID method is called with one type than another. I would suggest each time a different DID Method is called (not the current default) a new DID be created and flagged for reuse in future invitations.
  • or
  • a complete DID, which will be used for the invitation being established. This supports the edge case of an entity wanting to use a new DID for every connection. It is the responsibility of the controller to create the DID before passing it in.
  • If not provided, the 0.11.0 behaviour of an unqualified DID is used.
    • We expect this behaviour will change in a later release to be that a did:peer:4 is created and (re)used.
• A use_did parameter will be added to the didexchange/create_request. didexchange/accept_invitation that takes either
  • a DID Method (options: did:peer:2 did:peer:4) so that a DID of that type is created for use in the connection being established. This is the recommend approach, and we further recommend using did:peer:4
  • or
  • a complete DID, which will be used for the connection being established. This supports the edge case of an entity wanting to use the same DID for all connections.
  • If not provided, the 0.11.0 behaviour of an unqualified DID is created if DID Exchange 1.0 is used, and a DID Peer 4 is used if DID Exchange 1.1 is used.
    • We expect this behaviour will change in a later release to be that a did:peer:4 is created.
• When auto-accept is used with DID Exchange, the an unqualified DID is created if DID Exchange 1.0 is being used, and a DID Peer 4 is used if DID Exchange 1.1 is used.

With these changes, an existing ACA-Py installation using unqualified DIDs can upgrade to use qualified DIDs:

• Reactively in 0.12.0, by using like DIDs from the other agent.
• Proactively, by adding the use_did parameter on the outofband/create_invitation, didexchange/create_request. and didexchange/accept_invitation endpoints and specifying did:peer:2 or did_peer:4.
  • The other agent must be able to process the selected DID Method.
• Proactively, by updating to use DID Exchange v1.1 and having the other side auto-accept the connection.

[dbluhm]

@swcurran I took a stab at updating this text according to what has been implemented in #2862:

In looking at the approach that has evolved in release 0.12.0 for handling the transition to the use of qualified DIDs only, we've decided on the following changes to the current implementation:

• Remove the new configuration parameters that were added as part of 0.12.0 --emit-did-peer-2 and --emit-did-peer-4.
  • Remove them as well from the "per-tenant" settings list of parameters.
  • We've decide that finer grained control is needed at the point of creating invitations and DID Exchange requests is more useful than configuration settings.
• Two parameters will be added to the outofband/create_invitation that takes:
  • use_did_method: a DID Method (options: did:peer:2 did:peer:4) so that a DID of that type is created (if necessary), and used in the invitation. If a DID of the type has to be created, it is flagged as the "invitation" DID and used in all future invitations so that connection reuse is the default behaviour.
    • This is the recommend approach, and we further recommend using did:peer:4.
    • Some care is needed when the DID method is called with one type than another. I would suggest each time a different DID Method is called (not the current default) a new DID be created and flagged for reuse in future invitations.
  • use_did: a complete DID, which will be used for the invitation being established. This supports the edge case of an entity wanting to use a new DID for every invitation. It is the responsibility of the controller to create the DID before passing it in.
  • If not provided, the 0.11.0 behaviour of an unqualified DID is used.
    • We expect this behaviour will change in a later release to be that use_did_method="did:peer:4" is the default, which is created and (re)used.
• Two parameters will be added to the didexchange/create_request. didexchange/accept_invitation that takes either
  • use_did_method: a DID Method (options: did:peer:2 did:peer:4) so that a DID of that type is created (if necessary), and used in the invitation. If a DID of the type has to be created, it is flagged as the "invitation" DID and used in all future invitations so that connection reuse is the default behaviour.
    • This is the recommend approach, and we further recommend using did:peer:4.
    • Some care is needed when the DID method is called with one type than another. I would suggest each time a different DID Method is called (not the current default) a new DID be created and flagged for reuse in future invitations.
  • use_did: a complete DID, which will be used for the invitation being established. This supports the edge case of an entity wanting to use the same DID for all connections. It is the responsibility of the controller to create the DID before passing it in.
  • If not provided, the 0.11.0 behaviour of an unqualified DID is created if DID Exchange 1.0 is used, and a DID Peer 4 is used if DID Exchange 1.1 is used.
    • We expect this behaviour will change in a later release to be that a did:peer:4 is created and DID Exchange 1.1 is always used.
• When auto-accept is used with DID Exchange, the an unqualified DID is created if DID Exchange 1.0 is being used, and a DID Peer 4 is used if DID Exchange 1.1 is used.

With these changes, an existing ACA-Py installation using unqualified DIDs can upgrade to use qualified DIDs:

• Reactively in 0.12.0, by using like DIDs from the other agent.
• Proactively, by adding the use_did or use_did_method parameter on the outofband/create_invitation, didexchange/create_request. and didexchange/accept_invitation endpoints and specifying did:peer:2 or did_peer:4.
  • The other agent must be able to process the selected DID Method.
• Proactively, by updating to use DID Exchange v1.1 and having the other side auto-accept the connection.