Skip to content

/ p2abcengine

Integrating the ABC Engine

Jump to bottom
fspreiss edited this page Jun 12, 2013 · 19 revisions

Integrating the ABC-Engine

The ABC-Engine (ABCE) provide integration points for user, issuer, verifer, inspector, and revocation authority. The integration is designed to be as simple as possible, but as any ABCE setup requires at least three entities (user, issuer, and verifier) attention must be paid to the details of the instructions.

For each service we have created a helper class which encapsulates and assist in the most common setup of the entities.

In the following we describe how to integrate each entity in an existing application. All the mentioned paths are relative to the current path of the application.

Issuer

  1. Initialize IssuanceHelper

    IssuanceHelper.initInstance(CryptoEngine.BRIDGED, issuerParamsPrefix, fileStoragePrefix, credSpecAndPolicy, ....);

    Where:

    • CryptoEngine.BRIDGED is identifying the crypto engine to use [BRIDGED, UPROVE, IDEMIX]
    • issuerParamsPrefix and fileStoragePrefix are strings containing the relative path prefix to identify locations where the issuer parameters and generated files are stored
    • credSpecAndPolicy is a SpecAndPolicy containing a uniques id, the relative paths to the credential specification, and the relative paths to the issuance policy

  2. Start issuance with initialize issuance

    IssuanceMessage im_with_policy = issuanceHelper.initIssuance(engine, specAndPolicyId, attributeValueMap);

    Where:

    • engine is a reference to the crypto engine
    • specAndPolicyId is the unique id of the SpecAndPolicy object
    • attributeValueMap contains a reference to a map of the attribute names and their value. This is issuer know attributes.

  3. Run a sequence of issuance steps until done (checked on the user side by looking at the cd field of the IssuMsgOrCredDesc class. If the field is not null then we are done).

    IssuanceMessageAndBoolean response = issuanceHelper.issueStep(engine, issuanceMessage);

    Where:

    • engine is a reference to the crypto engine
    • issuanceMessage is the message received from the user as reponce to either initIssuance or issueStep.

See also: integration-test-issuer

Verifier

  1. Initialize the VerificationHelper

    VerificationHelper.initInstance(CryptoEngine.BRIDGED, issuer_params_resource_list, cred_spec_resource_list, inspector_public_key_resource_list, fileStoragePrefix, presentationPoliciesResouces);

    Where:

    • issuer_params_resource_list is an array of relative path strings to the issuer parameters binary files
    • cred_spec_resource_list is an array of relative path strings to the credential specification files
    • inspector_public_key_resource_list is an array of relative path strings to the inspector public keys binary files
    • fileStoragePrefix is a string containing the relative path prefix to identify locations where the issuer parameters and generated files are stored.
    • presentationPoliciesResouces is an array of relative path strings to the presentation policies used by the verifier.

  2. Present a presentation policy 9. Create a nonce to prevent users to reuse old presentation tokens

    nonce = verificationHelper.generateNonce();
    1. Add nounce to presentation policy
    PresentationPolicyAlternatives ppa = verificationHelper.createPresentationPolicy(policyId, nonce, applicationData);

    Where:
* `policyId` is a unique id used to identify the policy
* `nonce` is the nonce generated in step 1
* `applicationData` is application specific data which should be added to the presentation policy
    1. Send the presentation policy to the user

  3. Verify the presentation token against the presentation policy. This also verifies that the nonce in the presentation token matches the nonce in the presentation policy.

    verificationHelper.verifyToken(presentationPolicyAlternatives, presentationToken);

    Where:

    • presentationPolicyAlternatives is the presentation policy
    • presentationToken is the presentation token received from the user

  4. Verify that all pseudonyms in the presentation token are known by the application, if needed.

See also: integration-test-verifier

User

  • Initialize the UserHelper

    UserHelper.initInstance(cryptoEngine, issuerParamsResourceList, fileStoragePrefix, credSpecResourceList, inspectorPublicKeyResourceList);

    Where:

    • cryptoEngine is a reference to the crypto engine
    • issuerParamsResourceList is an array of relative path strings to the issuer parameters binary files
    • fileStoragePrefix is a string containing the relative path prefix to identify locations where the issuer parameters and generated files are stored
    • credSpecResourceList is an array of relative path strings to the credential specification files
    • inspectorPublicKeyResourceList is an array of relative path strings to the inspector public keys binary files

  • The credential manager can be accessed through the userHelper.credentialManager field.

  • The crypto engine can be accessed through the userHelper.getEngine() method. Useful for creating presentation tokens:

    userHelper.getEngine().createPresentationToken(presentationPolicy);

    or for doing a issuance protocol step.

    userHelper.getEngine().issuanceProtocolStep(issuanceMessage, policySelector);

  • Integration with the identity selection UI

    The following protocol is run when the ABCE requests the user to select an identity (a set of credentials and pseudonyms needed to satisfy a policy):

    • Check and unlock smart card before Presentation/Issuance.
      1. Check if the last used card is still present and already unlocked:
      GET : "/user/checkSmartcard/{SessionID}"
      Http Response: 
      OK = 204 (no content) 
ERROR = other
      1. Check status of smart card
      GET : "/user/smartcardStatus"
      Http Response: 
      OK = 200,204
ERROR = other
      1. Unlock smart card using pin code
      POST : "/user/unlockSmartcards/{SessionID}" 
BODY : <PIN>
      Http Responce: 
      OK = 200,204
ERROR 
  - 401 Wrong PIN
  - 403 Card as locked
  - other - other error
    • Presentation
      1. Given a PresentationPolicyAlternatives XML document return descriptions of the matching presentation tokens the user can choose among
      Post: "/user/createPresentationToken/{SessionID}"
Body: XML PresentationPolicyAlternatives
      Http Responce: 
      203: SelectPresentationTokenDescription as a JSON structure
OTHER: Error
      1. Select a presentation token to be used for the verification
      POST: "/user/createPresentationTokenIdentitySelection/{SessionID}"
BODY: A JSON structure:
  { TokenCandidateUID : <UID>, 
    TokenIndex : <IX>
    PseudonymsList : [UID, UID, ...],
    InspectorsList : [UID, UID, ...]
  }
      Http Responce: 
      200: XML PresentationToken
Other: Error
    • Issuance
      1. Given a IssuanceMessage XML document return descriptions of the matching presentation tokens the user can choose among
      POST : "/user/issuanceProtocolStep/{SessionID}"
BODY : XML IssuanceMessage
      Http Responce: 
      203: SelectIssuanceTokenDescription as a JSON structure
OTHER: Error
      1. Select a presentation token to be used for the issuance
      POST: "/user/issuanceProtocolStepSelect/{SessionID}"
BODY: A JSON structure:
  { TokenCandidateUID : <UID>, 
    TokenIndex : <IX>
    PseudonymsList : [UID, UID, ...],
    InspectorsList : [UID, UID, ...]
  }
      Http Responce: 
      200: XML IssuanceMessage
OTHER: Error

See: integration-test-user

##Revocation Authority

  • Initialize the InspectorHelper

        RevocationHelper.initInstance(ProductionModule.CryptoEngine.BRIDGED, revocationStoragePrefix,
        revocationResourcesPrefix, systemParametersResource, issuerParamsResourceList,
        credSpecResourceList, revocationReferences);

    Where:

    • revocationStoragePrefix is a string containing the relative path prefix to identify locations where the revocation authority files are stored
    • revocationResourcesPrefix is a string containing the relative path prefix to identify locations where the revocation authority resources are stored
    • systemParameterResource is a string containing the relative path prefix to a file containing the system parameters
    • issuerParamsResourceList is an array of relative path strings to the issuer parameters binary files
    • credSpecResourceList is an array of relative path strings to the revocable credential specification files
    • revocationReferences is an array of RevocationReferences containing the revocation authority UID and the endpoints (URIs) for where to obtain revocation information, non-revocation evidence, and non revocation updates

  • Revoke attribute

        RevocationInformation ri = RevocationHelper.getInstance().engine.revoke(revParUid, attributes);

    Where:

    • revParUid is the revocation parameters UID
    • atttributes is a list of revocation handle attributes

  • Obtain revocation information

        RevocationHelper.getInstance().revocationProxyAuthority.processRevocationMessage(in);

    Where:

    • in is a revocation message with a crypto element containing a RevocationMessageType of REQUEST_REVOCATION_INFORMATION or GET_CURRENT_REVOCATION_INFORMATION

  • Obtain non-revocation evidence

        RevocationHelper.getInstance().revocationProxyAuthority.processRevocationMessage(in);

    Where:

    • in is a revocation message with a crypto element containing a RevocationMessageType of UPDATE_REVOCATION_EVIDENCE

  • Request revocation handle

        RevocationHelper.getInstance().revocationProxyAuthority.processRevocationMessage(in);

    Where:

    • in is a revocation message with a crypto element containing a RevocationMessageType of REQUEST_REVOCATION_HANDLE

See also: integration-test-revocation

##Inspector

  1. Initialize the InspectorHelper

       inspectorHelper.initInstance(inspectorStoragePrefix, inspectorResourcePrefix, systemParameterResource, 
       inspector_public_key_uids, inspection_cred_spec_resource_list);

    Where:

    • inspectorStoragePrefix is a string containing the relative path prefix to identify locations where the inspector files are stored
    • inspectorResourcePrefix is a string containing the relative path prefix to identify locations where the inspector resources are stored
    • systemParameterResource is a string containing the relative path prefix to a file containing the system parameters
    • inspector_public_key_uids is an array of URIs to the inspector public keys
    • inspection_cred_spec_resource_list is an array of relative path strings to the inspectable credential specification files

  2. Inspect the inspectable attributes in the presentation token:

        List<Attribute> atts = inspectorHelper.inspect(presentationToken.getValue());

    Where:

    • presentationToken contains a reference to the presentation token

  3. Recover the value from its BigInteger representation:

        for(Attribute a : atts) {
        MyAttributeValue value = MyAttributeEncodingFactory.recoverValueFromBigInteger(
            a.getAttributeDescription().getEncoding(), (BigInteger) a.getAttributeValue(), null);
    }

See also: integration-test-inspector

You can’t perform that action at this time.