didexchange

Documentation

Overview

Package didexchange enables relationship between two agents via DID Exchange Protocol. The exchange request message is used to communicate the DID document of the invitee to the inviter using the provisional service information present in the invitation message. The exchange response message is used to complete the exchange and communicate the DID document of the inviter to the invitee. After inviter receives the exchange response, the exchange is technically complete however it is still unconfirmed to the inviter. The invitee sends ACK message to inviter to confirm the exchange.

Basic Flow:
1) Prepare client context
2) Create client
3) Register for action events (enables auto execution)
4) Create Invitation
5) Handle invitation
6) Use connection

Example

bob, err := New(mockContext())
if err != nil {
	fmt.Println("failed to create client for Bob")
}

bobActions := make(chan service.DIDCommAction, 1)

err = bob.RegisterActionEvent(bobActions)
if err != nil {
	fmt.Println("failed to create Bob's action channel")
}

go func() {
	service.AutoExecuteActionEvent(bobActions)
}()

alice, err := New(mockContext())
if err != nil {
	fmt.Println("failed to create client for Alice")
}

aliceActions := make(chan service.DIDCommAction, 1)

err = alice.RegisterActionEvent(aliceActions)
if err != nil {
	fmt.Println("failed to create Alice's action channel")
}

go func() {
	service.AutoExecuteActionEvent(aliceActions)
}()

invitation, err := bob.CreateInvitation("bob invites alice")
if err != nil {
	fmt.Printf("failed to create invitation: %s\n", err)
}

connectionID, err := alice.HandleInvitation(invitation)
if err != nil {
	fmt.Printf("failed to handle invitation: %s\n", err)
}

connection, err := alice.GetConnection(connectionID)
if err != nil {
	fmt.Printf("failed to get connection: %s\n", err)
}

fmt.Println(connection.TheirLabel)

Output:

bob invites alice

Index

• Constants
• Variables
• type Client
  • func New(ctx provider) (*Client, error)
  • func (c *Client) AcceptExchangeRequest(connectionID, publicDID, label string) error
  • func (c *Client) AcceptInvitation(connectionID, publicDID, label string) error
  • func (c *Client) CreateImplicitInvitation(inviterLabel, inviterDID string) (string, error)
  • func (c *Client) CreateImplicitInvitationWithDID(inviter, invitee *DIDInfo) (string, error)
  • func (c *Client) CreateInvitation(label string) (*Invitation, error)
  • func (c *Client) CreateInvitationWithDID(label, did string) (*Invitation, error)
  • func (c *Client) GetConnection(connectionID string) (*Connection, error)
  • func (c *Client) GetConnectionAtState(connectionID, stateID string) (*Connection, error)
  • func (c *Client) HandleInvitation(invitation *Invitation) (string, error)
  • func (c *Client) QueryConnections(request *QueryConnectionsParams) ([]*Connection, error)
  • func (c *Client) RemoveConnection(id string) error
• type Connection
• type DIDInfo
• type Event
• type Invitation
• type QueryConnectionsParams

Examples

• Package
• Client.CreateInvitation
• Client.CreateInvitationWithDID
• New

Constants

const (
	// InvitationMsgType defines the did-exchange invite message type.
	InvitationMsgType = didexchange.InvitationMsgType
	// RequestMsgType defines the did-exchange request message type.
	RequestMsgType = didexchange.RequestMsgType
)

Variables

var ErrConnectionNotFound = errors.New("connection not found")

ErrConnectionNotFound is returned when connection not found

Types

type Client

type Client struct {
	service.Event
	// contains filtered or unexported fields
}

Client enable access to didexchange api

func New

func New(ctx provider) (*Client, error)

New return new instance of didexchange client

Example

ctx := mockContext()

c, err := New(ctx)
if err != nil {
	fmt.Println(err)
}

if c != nil {
	fmt.Println("client created")
} else {
	fmt.Println("client is nil")
}

Output:

client created

func (*Client) AcceptExchangeRequest

func (c *Client) AcceptExchangeRequest(connectionID, publicDID, label string) error

AcceptExchangeRequest accepts/approves exchange request. This call is not used if auto execute is setup for this client (see package example for more details about how to setup auto execute)

func (*Client) AcceptInvitation

func (c *Client) AcceptInvitation(connectionID, publicDID, label string) error

AcceptInvitation accepts/approves exchange invitation. This call is not used if auto execute is setup for this client (see package example for more details about how to setup auto execute)

func (*Client) CreateImplicitInvitation

func (c *Client) CreateImplicitInvitation(inviterLabel, inviterDID string) (string, error)

CreateImplicitInvitation enables invitee to create and send an exchange request using inviter public DID.

func (*Client) CreateImplicitInvitationWithDID

func (c *Client) CreateImplicitInvitationWithDID(inviter, invitee *DIDInfo) (string, error)

CreateImplicitInvitationWithDID enables invitee to create implicit invitation using inviter and invitee public DID.

func (*Client) CreateInvitation

func (c *Client) CreateInvitation(label string) (*Invitation, error)

CreateInvitation creates an invitation. New key pair will be generated and base58 encoded public key will be used as basis for invitation. This invitation will be stored so client can cross reference this invitation during did exchange protocol

Example

bob, err := New(mockContext())
if err != nil {
	fmt.Println("failed to create client for Bob")
}

invitation, err := bob.CreateInvitation("bob invites julia")
if err != nil {
	fmt.Printf("failed to create invitation: %s\n", err)
}

fmt.Println(invitation.Label)

Output:

bob invites julia

func (*Client) CreateInvitationWithDID

func (c *Client) CreateInvitationWithDID(label, did string) (*Invitation, error)

CreateInvitationWithDID creates an invitation with specified public DID. This invitation will be stored so client can cross reference this invitation during did exchange protocol

Example

bob, err := New(mockContext())
if err != nil {
	fmt.Println("failed to create client for Bob")
}

invitation, err := bob.CreateInvitationWithDID("bob invites maria", "did:example:abc-123")
if err != nil {
	fmt.Printf("failed to create invitation with DID: %s\n", err)
}

fmt.Println(invitation.DID)

Output:

did:example:abc-123

func (*Client) GetConnection

func (c *Client) GetConnection(connectionID string) (*Connection, error)

GetConnection fetches single connection record for given id

func (*Client) GetConnectionAtState

func (c *Client) GetConnectionAtState(connectionID, stateID string) (*Connection, error)

GetConnectionAtState fetches connection record for connection id at particular state.

func (*Client) HandleInvitation

func (c *Client) HandleInvitation(invitation *Invitation) (string, error)

HandleInvitation handle incoming invitation and returns the connectionID that can be used to query the state of did exchange protocol. Upon successful completion of did exchange protocol connection details will be used for securing communication between agents.

func (*Client) QueryConnections

func (c *Client) QueryConnections(request *QueryConnectionsParams) ([]*Connection, error)

QueryConnections queries connections matching given criteria(parameters)

func (*Client) RemoveConnection

func (c *Client) RemoveConnection(id string) error

RemoveConnection removes connection record for given id

type Connection

type Connection struct {
	*connection.Record
}

Connection model

This is used to represent query connection result

type DIDInfo

type DIDInfo struct {

	// the DID
	DID string

	// the label associated with DID
	Label string
}

DIDInfo model for specifying public DID and associated label

type Event

type Event interface {
	// connection ID
	ConnectionID() string

	// invitation ID
	InvitationID() string
}

Event properties related api. This can be used to cast Generic event properties to DID Exchange specific props.

type Invitation

type Invitation struct {
	*didexchange.Invitation
}

Invitation model for DID Exchange invitation.

type QueryConnectionsParams

type QueryConnectionsParams struct {

	// Alias of connection invitation
	Alias string `json:"alias,omitempty"`

	// Initiator is Connection invitation initiator
	Initiator string `json:"initiator,omitempty"`

	// Invitation key
	InvitationKey string `json:"invitation_key,omitempty"`

	// MyDID is DID of the agent
	MyDID string `json:"my_did,omitempty"`

	// State of the connection invitation
	State string `json:"state"`

	// TheirDID is other party's DID
	TheirDID string `json:"their_did,omitempty"`

	// TheirRole is other party's role
	TheirRole string `json:"their_role,omitempty"`
}

QueryConnectionsParams model

Parameters for querying connections