Project

General

Profile

Implement TAN Methods in Your Application

The way to implement the new optical TAN methods is to implement AB_Gui_GetPassword(). The prototype for this
function is:

typedef int GWENHYWFAR_CB(*GWEN_GUI_GETPASSWORD_FN)(GWEN_GUI *gui,
                                                    uint32_t flags,
                                                    const char *token,
                                                    const char *title,
                                                    const char *text,
                                                    char *buffer,
                                                    int minLen,
                                                    int maxLen,
                                                    GWEN_GUI_PASSWORD_METHOD methodId,
                                                    GWEN_DB_NODE *methodParams,
                                                    uint32_t guiid);

The parameters are:

gui pointer to your implementation of GWEN_GUI
flags flags to control the behaviour of the input, most important flag in this case is GWEN_GUI_INPUT_FLAGS_TAN. Other interesting flags are:
- GWEN_GUI_INPUT_FLAGS_NUMERIC (only numeric input allowed)
- GWEN_GUI_INPUT_FLAGS_SHOW (show the input, otherwise handle it as secret input by echoing the input as asterisks)
token unique identification for the password or pin. This can be used to read the password from a cache or file (not applicable for TAN)
title title you can use for your GUI dialog
text text to present to the user together with images provided
buffer buffer to store the response in. Must have at least room for "maxLen" bytes
minLen minimal length of the password (if 0 then there is no low limit)
maxLen size of the buffer including the trailing NULL character
methodId currenty either GWEN_Gui_PasswordMethod_Text (normal text input) or GWEN_Gui_PasswordMethod_OpticalHHD (optical input)
methodParams storage object containing variables conveying necessary information (like image type, image data etc.)
guiid you can safely ignore that or pass it to other GWEN_GUI functions

Determine the General Type of Input Requested

First step is to check the methodId. In case of

  GWEN_Gui_PasswordMethod_Text

just a simple textual input of the TAN is needed.

If the method id is

GWEN_Gui_PasswordMethod_OpticalHHD

an optical TAN method is selected (e.g. "photoTAN", "chipTAN optisch").

Determine the Optical Tan Method

To further determine which method to use look at the given function argument "methodParams". This is just a storage object which contains some variables that can be accessed using the following functions:

  const char *GWEN_DB_GetCharValue(GWEN_DB_NODE *n,
                                   const char *path,
                                   int index,
                                   const char *defaultValue);

  int GWEN_DB_GetIntValue(GWEN_DB_NODE *n,
                          const char *path,
                          int index,
                          int defaultValue);

  const void *GWEN_DB_GetBinValue(GWEN_DB_NODE *n,
                                  const char *path,
                                  int index,
                                  const void *defaultValuePointer,
                                  unsigned int defaultValueSize,
                                  unsigned int *returnValueSize);

Every optical TAN method has its own set of variables to transport the necessary information.

Determine the requested method by inspecting the variable "methodId":

  opticalMethodId=GWEN_DB_GetIntValue(methodParams, "tanMethodId", 0, AB_BANKING_TANMETHOD_TEXT);

Currently defined method ids are;

  • AB_BANKING_TANMETHOD_TEXT
  • AB_BANKING_TANMETHOD_CHIPTAN
  • AB_BANKING_TANMETHOD_CHIPTAN_OPTIC
  • AB_BANKING_TANMETHOD_CHIPTAN_USB
  • AB_BANKING_TANMETHOD_CHIPTAN_QR
  • AB_BANKING_TANMETHOD_PHOTOTAN

AB_BANKING_TANMETHOD_TEXT

This is the simplest method. The implementor just needs to present the text to the user and ask for a TAN. Also used as fallback.

AB_BANKING_TANMETHOD_CHIPTAN

This is basically the same as AB_BANKING_TANMETHOD_TEXT, the given text is just a bit more complex and the user needs to enter some of it into a special device provided by the bank. Just handle it as AB_BANKING_TANMETHOD_TEXT.

AB_BANKING_TANMETHOD_CHIPTAN_OPTIC

This needs you to present the user with a flickering graphic which is derived from a given binary string. Its not too complicated to implement but that's out of the scope of this document (for now, TODO: Add links).

AB_BANKING_TANMETHOD_CHIPTAN_QR

Here an image provided by the bank server has to be shown to the user.

Get the mimetype of the image to be shown with:

  const char *mimeType;

  mimeType=GWEN_DB_GetCharValue(methodParams, "mimeType", 0, NULL);

Most images currently use "image/png".

Get the raw binary image to be shown with:

    const char *pChallenge;
    uint32_t lChallenge;

    pChallenge=(const char*) GWEN_DB_GetBinValue(methodParams, "imageData", 0, NULL, 0, &lChallenge);
    if (!(pChallenge && lChallenge)) {
      /* empty optical data */
      return GWEN_ERROR_NO_DATA;
    }

AB_BANKING_TANMETHOD_PHOTOTAN

Basically the same as AB_BANKING_TANMETHOD_CHIPTAN_QR, it also uses an image which needs to be presented.