Package KM104

Interface T104OpenAPI

All Superinterfaces:
javacard.framework.Shareable
public interface T104OpenAPI
extends javacard.framework.Shareable

  • Field Details

  • Method Details

    • appLogin

      short appLogin​(byte[] param, short paramOffset, short paramLen)
      Login of current applet to the T104 applet for an authenticated session to perform T104 OpenAPI calls.

      Call the appLogin twice. The first appLogin call will retrieve a session challenge from the T104OpenAPI and placed into the param parameter by the T104 Applet. The second call will require a HMAC-SHA256 signature over the challenge as the message and the AOC PIN or Password as the HMAC key.

      Execution sequence:
      1. Call appLogin with a global array to contain the challenge (10 bytes).
      2. If returned length from the initial appLogin returns 10 bytes length, proceed further else an error has occured.
      3. Perform HMAC-SHA256 signature with the AOC PIN/Password as the key and challenge as the message. Copy the signature into a global array.
      4. Call appLogin with the param, paramOffset, paramLen respectively loaded with the global array details containing the signature.
      5. If returned is '1' it indicates Success, if '0' it indicates failure on the signature based authentication and '-1' as an error indicating an invalid AOC container (not registered), invalid or null param related inputs or an internally invalid authentication state.
      6. Cache the challenge as the session ticket.
      Parameters:
      param - the first call of appLogin will be a global array (i.e. APDU buffer) to receive the 10 byte challenge and the second call of appLogin will be a global array set with the HMAC-SHA256 signed challenge.
      paramOffset - offset into the global array to contain the challenge if it is an initial call or an offset into the global array that contains the signature of the challenge.
      paramLen - initial call of appLogin will omit this. Second call of appLogin will indicate the length of the signature in the global array to read.
      Returns:
      If returned is '1' it indicates Success, if '0' it indicates failure on the signature based authentication and '-1' as an error indicating an invalid AOC container (not registered), invalid or null param related inputs or an internally invalid authentication state.

    • createAOCContainer

      boolean createAOCContainer​(byte secretType, byte[] secret, short secretOffset, short secretLen, short maxRetry)
      Registers an applet to allow access to the T104OpenAPI interface. An AOC container profile would be created in the T104 applet to represent the applet. During the registering of the applet and creation of the AOC container, a shared secret in the form of a PIN or a binary Password can be selected up to a length of 64 bytes. The PIN or binary Password would be used for HMAC-SHA256 signature based challenge-response session login via the appLogin call.

      A maximum of 10 unique applets maybe registered and AOC container profile created only.

      A maximum retry of 99 retries and a minimum of 1 retry is allowed.

      Accepted secret types:
      • CRED_AUTHTYPE_PIN: 0 to 9 in ASCIIfied binary
      • CRED_AUTHTYPE_PIN: 8-bit octet


      The authentication secret stored in the AOC container profile on the T104 applet side is encrypted with a non-exportable randomly generated 256-bit storage master key with Cipher.ALG_AES_CBC_PKCS5 with an all zero IV.

      If an applet already exists with the exact same AID (RID + PIX) , it will fail to register.

      It is always advisable to retrieve a shareable interface and call a getAOCInfo call which is accessible without registration of applet before attempting to register applet and create an AOC container profile.
      Parameters:
      secretType - secret type used for authentication
      secret - global array containing secret used for authentication
      secretOffset - offset into global array containing authentication secret
      secretLen - length of authentication secret
      maxRetry - maximum retry for session login before locking of applet
      Returns:
      result of AOC container creation

    • destroyAOCContainer

      boolean destroyAOCContainer()
      Deregisters and deletes an existing applet from the T104 Environment only. GP environment remains intact. No appLogin is required.

      If an applet does not exist in the T104 Environment, it will simply return a false value.

      Note: When an applet gets locked out due to too many invalid authentication attempts, it is advisable to destroy the container and recreate a new container.
      Returns:
      result of applet deregistration and AOC container destruction.

    • manageAOCContainer

      boolean manageAOCContainer​(byte fieldType, byte[] input, short offset, short len, short maxRetry, byte[] ticket, short ticketOff)
      Manage but not delete the registered applet and AOC container profile. Currently only allows the changing of PIN or Password.

      If a PIN type was registered, a new PIN is expected. If a Password type was registered, a new Password is expected. Mixing of a registered PIN authenticator type for a new Password type secret authenticator is not allowed.

      Rules for PIN / Password authenticator is the same as createAOCContainer method.

      If an applet does not exist in the T104 Environment, it will simply return a false value.

      The applet must have logged in via appLogin to access this method.
      Parameters:
      fieldType - only the CRED_FIELD_SECRET field type is allowed.
      input - global array containing the new authenticator secret
      offset - offset within global array containing the new authenticator secret to read
      len - length of new authenticator secret
      maxRetry - new maximum retry length
      ticket - global array containing the current session ticket.
      ticketOff - offset in the global array to read the current session ticket.
      Returns:
      result of management activities on the AOC container.

    • getAOCInfo

      short getAOCInfo​(byte[] output, short outOffset)
      Extracts the publicly available AOC container information. Does not require AOC container registration and login to access.

      AOC Container Information Format (sequence)
      • Is Applet Registered - 1 byte - 0x00 (No), 0x01 (Yes)
      • Secret Type - 1 byte - CRED_AUTHTYPE_PIN or CRED_AUTHTYPE_PWD
      • Auth Retry Left - 1 byte - Number of retries left
      • Auth Retry Max - 1 byte - Number of maximum retries allowed
      • AID Length - 1 byte - Length of AID
      • AID - AIDLength byte - AID
      Parameters:
      output - global array to store information of the AOC container information.
      outOffset - offset within global array to store information of the AOC container information.
      Returns:
      amount of bytes of returned AOC container information.

    • getCardInfo

      short getCardInfo​(byte[] output, short outOffset)
      Returns information about the card.

      TLV is being used after the initial two byte version sequence. All TLV length are restricte to one byte length only.

      A list of supported TLV tags:
      public static final byte TLV_TAG_HW_INFO = (byte) 0x01;
      public static final byte TLV_TAG_HW_CAP = (byte) 0x02;
      public static final byte TLV_TAG_HW_USR = (byte) 0x03;
      public static final byte TLV_TAG_HW_MEM_PERSIST = (byte) 0x04;
      public static final byte TLV_TAG_HW_MEM_TEMP_RST = (byte) 0x41;
      public static final byte TLV_TAG_HW_MEM_TEMP_DST = (byte) 0x42;
      public static final byte TLV_TAG_HW_ID = (byte) 0x05;
      public static final byte TLV_TAG_HW_ID_PUB = (byte) 0x51;
      public static final byte TLV_TAG_HW_ID_ATTEST = (byte) 0x52;
      public static final byte TLV_TAG_HW_SCP = (byte) 0x06;
      public static final byte TLV_TAG_HW_BK = (byte) 0x07;
      public static final byte TLV_TAG_HW_INTERACT = (byte) 0x08;
      public static final byte TLV_TAG_HW_CRED_FORMAT = (byte) 0x09;
      public static final byte TLV_TAG_AOC_CRED_ID = (byte) 0x0A;
      public static final byte TLV_TAG_AOC_AUXDATA = (byte) 0x0B;
      public static final byte TLV_OBJ_FIELD_ID = (byte) 0x08;
      public static final byte TLV_OBJ_FIELD_HANDLE = (byte) 0x0E;

      HW Info Format (sequence):
      • Version - 2 byte - 0x0100
      • HW Secure Input Capability (TLV) - 5 byte - TLV_TAG_HW_CAP; 0x00 - No capability (i.e. secure keypad)
      • User (TLV) - 4 byte - TLV_TAG_HW_USR; 0x01 - Card Admin User
      • Secure Channel (TLV) - 4 byte - TLV_TAG_HW_SCP; 0x0A03 - Proprietary ThothTrust A03 SCP protocol
      • HW Partition Backup Capability (TLV) - 2 byte - TLV_TAG_HW_BK; 0 length - No known backup
      • HW Interactive Capability (TLV) - 3 byte - TLV_TAG_HW_INTERACT; 0x01 - Screen available
      • Credential Secret Format (TLV) - 3 byte - TLV_TAG_HW_CRED_FORMAT; CRED_AUTHTYPE_PIN (0x80)
      • Persistent Memory (TLV) - 6 byte - TLV_TAG_HW_MEM_PERSIST; 4 byte integer of remaining persistent memory size
      • Temporary Resettable Memory (TLV) - 6 byte - TLV_TAG_HW_MEM_TEMP_RST; 4 byte integer of remaining resettable RAM memory size
      • Temporary Deselectable Memory (TLV) - 6 byte - TLV_TAG_HW_MEM_TEMP_DST; 4 byte integer of remaining deselectable RAM memory size
      • Hardware ID (TLV) - 2 byte ++ - TLV_TAG_HW_ID; Contains nested TLV tag(s)
      • Hardware Public Key (TLV) - 66 byte - TLV_TAG_HW_ID_PUB; raw 64 bytes X || Y representation of non-exportable ECC-SECP256K1 public key for secure channel and other hardware related PKI security for T104 environment
      Parameters:
      output - global array to store information of the Hardware information.
      outOffset - offset within global array to store Hardware information.
      Returns:
      length of card information.
      Since:
      version 1.0-Stable

    • displayToScreen

      void displayToScreen​(byte[] input, short off, short len, byte[] ticket, short ticketOff)
      Displays arbitrary positive integer digits up to 6 digits to screen. Useful for OTP code.
      Parameters:
      input - global array containing ASCIIfied hexadecimal bytes of 6 digit positive integer.
      off - offset within global array containing input for display
      len - lengh of input for display
      ticket - global array containing the current session ticket.
      ticketOff - offset in the global array to read the current session ticket.

    • setGlobalWalletAmount

      short setGlobalWalletAmount​(byte displayWalletRecordSlot, byte[] balance, short balanceOff, short balanceLen, byte[] payment, short paymentOff, short paymentLen, byte[] loading, short loadingOff, short loadingLen, byte[] ticket, short ticketOff)
      Sets one or more wallet slots (Balance, Payment and/or Loaded Funds) and then displays the particular slot value on the screen after successfully updating the wallet slots.

      The E-Wallet module has three global value storage slots to store values for 'Balance', 'Payment' and 'Loaded Funds' related amount. These amount will need to be accessed and displayed on demand whenever the user powers on the cards.

      Applets have to follow these steps to utilize the global stored value:
      1. Manually retrieve the value(s) of the targeted slot(s)
      2. Convert them to a format that their applets could process (i.e. to short, int or BigNumber types)
      3. Perform the required logical operations in their own applets
      4. Convert the results of the logical operations for each of the global value(s) they wish to update
      5. Write the updated value(s) to the slot(s)


      The following requirements for slot value must be met for rendering:
      • Either a 8 digit positive integer or a two-decimal placed positive decimal with the the numbers before the decimal place up to 6 digit place
      • The maximum positive two-decimal placed decimal value shall be 999999.99 and the smallest value shall be 0.00
      • Encoding of the input shall be in hexadecimal value
      • Example of value 999999.99 shall be encoded in hexadecimal as input as 3939393939392E3939


      The displayWalletRecordSlot variable shall use the following:
      • T104OpenAPI.WALLET_BALANCE_RECORD_SLOT - Displays Balance slot upon successful write operation
      • T104OpenAPI.WALLET_PAYMENT_RECORD_SLOT - Displays Payment slot upon successful write operation
      • T104OpenAPI.WALLET_LOADING_RECORD_SLOT - Displays Loaded Funds slot upon successful write operation.


      Upon successful updating of the slots, the values are stored persistently and powering up the card will allow on-demand access to these values displayed on screen via toggling the E-Wallet scrolling mechanical button.
      Parameters:
      displayWalletRecordSlot - the record type to display upon successful update of record(s)
      balance - global array carrying containing the balance value for update
      balanceOff - offset in the global array carrying containing the balance value for update to read
      balanceLen - length of balance value to read
      payment - global array carrying containing the payment value for update
      paymentOff - offset in the global array carrying containing the payment value for update to read
      paymentLen - length of payment value to read
      loading - global array carrying containing the loaded funds value for update
      loadingOff - offset in the global array carrying containing the loaded funds value for update to read
      loadingLen - length of laoded funds value to read
      ticket - global array containing the current session ticket.
      ticketOff - offset in the global array to read the current session ticket.
      Returns:
      If returned is '1' it indicates Success, '-1' as a general error, '-2' as a invalid displayWalletRecordSlot, '-3' and beyond as incorrect data values or length of the value slot(s) for updating. format of value,

    • getGlobalWalletAmount

      short getGlobalWalletAmount​(byte type, byte[] output, short off, byte[] ticket, short ticketOff)
      Retrieves wallet amount for a particular slot (Balance, Payment or Loaded Funds). Output will be ASCIIfied hexadecimal.

      An example for 123456.78 will be returned as 0x3132333435362E3738
      Parameters:
      type - wallet slot type either WALLET_BALANCE_RECORD_SLOT, WALLET_PAYMENT_RECORD_SLOT or WALLET_LOADING_RECORD_SLOT.
      output - global array to store information of the wallet slot selected.
      off - offset within global array to store wallet slot information.
      ticket - global array containing the current session ticket.
      ticketOff - offset in the global array to read the current session ticket.
      Returns:
      returns the length of byte array data of selected slot for reading. If '-1', invalid calling applet, if '-2', invalid type parameter.

    • setCardTimeout

      short setCardTimeout​(short timeout, byte[] ticket, short ticketOff)
      Set the timeout on the card.

      Use the following accepted timeout in seconds and their effects:
      • 65535 - Disable timeout by. Card stays powered on forever if the power button is not pressed again to shutdown the card manually.
      • 0 to 9 - Card timeout automatically readjusts to 10 seconds.
      • 10 to 65534 - Accepted.
      • Others - Unaccepted.
      Parameters:
      timeout - timeout timing in seconds.
      ticket - global array containing the current session ticket.
      ticketOff - offset in the global array to read the current session ticket.
      Returns:
      If returned is '1' it indicates Success, if '0' it indicates failure and '-1' as an error.
      Since:
      version 1.0-Stable

    • getCardTimeout

      short getCardTimeout()
      Returns the card timeout time. Publicly accessible without requiring registration of applet to T104 Environment for access.

      Return Results
      • 0 - No timeout of card. Remains on when switched on.
      • 1 to 65534 - Timeout in seconds.
      • -1 - Internal error.
      Returns:
      card timeout in seconds.
      Since:
      version 1.0-Stable