auth

README

go-iden3-auth

Library for verification of authorization response messages of communication protocol in JWZ format

go get github.com/lastingasset/go-iden3-auth

General description:

The goal of iden3auth libraries is to handle authentication messages of communication protocol.

Currently, library implementation includes support of next message types

1. https://iden3-communication.io/authorization/1.0/request
2. https://iden3-communication.io/authorization/1.0/response

---

Auth verification procedure:

1. JWZ token verification
2. Zero-knowledge proof verification of request proofs
3. Query request verification for atomic circuits
4. Verification of identity and issuer states for atomic circuits

Zero-knowledge proof verification

Groth16 proof are supported by auth library

Verification keys must be provided using KeyLoader interface

Query verification

Proof for each atomic circuit contains public signals that allow extracting user and issuer identifiers, states, signature, challenges, etc.

Circuit public signals marshallers are defined in the go-circuits library.

Verification of user / issuer identity states

The blockchain verification algorithm is used

1. Gets state from the blockchain (address of id state contract and URL must be provided by the caller of the library):

   1. Empty state is returned - it means that identity state hasn’t been updated or updated state hasn’t been published. We need to compare id and state. If they are different it’s not a genesis state of identity then it’s not valid.
   2. The non-empty state is returned and equals to the state in provided proof which means that the user state is fresh enough and we work with the latest user state.
   3. The non-empty state is returned and it’s not equal to the state that the user has provided. Gets the transition time of the state. The verification party can make a decision if it can accept this state based on that time frame.

2. Only latest states for user are valid. Any existing issuer state for claim issuance is valid.

Verification of GIST

The blockchain verification algorithm is used

1. Get GIST from the blockchain (address of id state contract and URL must be provided by the caller of the library):
   1. A non-empty GIST is returned, equal to the GIST is provided by the user, it means the user is using the latest state.
   2. The non-empty GIST is returned and it’s not equal to the GIST is provided by a user. Gets the transition time of the GIST. The verification party can make a decision if it can accept this state based on that time frame.

How to use:

1. go get https://github.com/lastingasset/go-iden3-auth

2. Request generation:

   basic auth:

   var request protocol.AuthorizationRequestMessage
   // if you need'message' to sign (e.g. vote)
   request = auth.CreateAuthorizationRequestWithMessage("test flow", "message to sign","verifier id", "callback url")
   // or if you don't need 'message' to sign
   request = auth.CreateAuthorizationRequest("test flow","verifier id", "callback url")
   

   if you want request specific proof (example):

   var mtpProofRequest protocol.ZeroKnowledgeProofRequest
   mtpProofRequest.ID = 1
   mtpProofRequest.CircuitID = string(circuits.AtomicQueryMTPV2CircuitID)
   mtpProofRequest.Query = map[string]interface{}{
      "allowedIssuers": []string{"*"},
      "credentialSubject": map[string]interface{}{
         "countryCode": map[string]interface{}{
            "$nin": []int{840, 120, 340, 509},
         },
      },
      "context": "https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json-ld/kyc-v2.json-ld",
      "type":    "KYCCountryOfResidenceCredential",
   }
   request.Body.Scope = append(request.Body.Scope, mtpProofRequest)       
   

3. Token verification

   Init Verifier:

   var verificationKeyloader = &loaders.FSKeyLoader{Dir: keyDIR}
   resolver := state.ETHResolver{
      RPCUrl:          <polygon_node_http>,
      ContractAddress: <state_contract_address>,
   }
   
   resolvers := map[string]pubsignals.StateResolver{
      "polygon:mumbai": resolver,
   }
   verifier := auth.NewVerifier(verificationKeyloader, loaders.DefaultSchemaLoader{IpfsURL: "ipfs.io"}, resolvers)
   

4. FullVerify:

   authResponse, err := verifier.FullVerify(
      r.Context(), 
      string(tokenBytes),
      authRequest.(protocolAuthorizationRequestMessage), 
      ...VerifyOpt,
   )
   userId = authResponse.from // msg sender
   

   Verify manually if thread id is used a session id to match request with VerifyJWZ / VerifyAuthResponse functions

Notes on prover optimization for x86_64 hardware

See readme in iden3/go-rapidsnark/prover

Documentation

Index

• func CreateAuthorizationRequest(reason, sender, callbackURL string) protocol.AuthorizationRequestMessage
• func CreateAuthorizationRequestWithMessage(reason, message, sender, callbackURL string) protocol.AuthorizationRequestMessage
• func VerifyState(ctx context.Context, id, s *big.Int, opts state.ExtendedVerificationsOptions) error
• type Verifier
  • func NewVerifier(keyLoader loaders.VerificationKeyLoader, ...) *Verifier
  • func (v *Verifier) FullVerify(ctx context.Context, token string, ...) (*protocol.AuthorizationResponseMessage, error)
  • func (v *Verifier) VerifyAuthResponse(ctx context.Context, response protocol.AuthorizationResponseMessage, ...) error
  • func (v *Verifier) VerifyJWZ(ctx context.Context, token string, opts ...pubsignals.VerifyOpt) (t *jwz.Token, err error)

Functions

func CreateAuthorizationRequest

func CreateAuthorizationRequest(reason, sender, callbackURL string) protocol.AuthorizationRequestMessage

CreateAuthorizationRequest creates new authorization request message sender - client identifier reason - describes purpose of request callbackURL - url for authorization response

func CreateAuthorizationRequestWithMessage

func CreateAuthorizationRequestWithMessage(reason, message, sender,
	callbackURL string) protocol.AuthorizationRequestMessage

CreateAuthorizationRequestWithMessage creates new authorization request with message for signing with jwz

func VerifyState

func VerifyState(ctx context.Context, id, s *big.Int, opts state.ExtendedVerificationsOptions) error

VerifyState allows to verify state without binding to verifier instance

Types

type Verifier

type Verifier struct {
	// contains filtered or unexported fields
}

Verifier is a struct for auth instance

func NewVerifier

func NewVerifier(
	keyLoader loaders.VerificationKeyLoader,
	claimSchemaLoader loaders.SchemaLoader,
	resolver map[string]pubsignals.StateResolver) *Verifier

NewVerifier returns setup instance of auth library

func (*Verifier) FullVerify

func (v *Verifier) FullVerify(
	ctx context.Context,
	token string,
	request protocol.AuthorizationRequestMessage,
	opts ...pubsignals.VerifyOpt,
) (*protocol.AuthorizationResponseMessage, error)

FullVerify performs verification of jwz token and auth request

func (*Verifier) VerifyAuthResponse

func (v *Verifier) VerifyAuthResponse(
	ctx context.Context,
	response protocol.AuthorizationResponseMessage,
	request protocol.AuthorizationRequestMessage,
	opts ...pubsignals.VerifyOpt,
) error

VerifyAuthResponse performs verification of auth response based on auth request

func (*Verifier) VerifyJWZ

func (v *Verifier) VerifyJWZ(
	ctx context.Context,
	token string,
	opts ...pubsignals.VerifyOpt,
) (t *jwz.Token, err error)

VerifyJWZ performs verification of jwz token