1.14 Using Extension Structures

Each function in the NSSS API can accept an optional parameter of type SS_EXT_T. This parameter has been included to provide access to extended functionality in the API for future expansions without having to change the interface.

    // optional extension structuretypedefstruct_ss_extension{unsigned long clientVersion;//* INvoid *extParms;//* IN-pointer to optional data}SS_EXT_T;

A description of the extension structures and example of how to use them are showin in the following sections:

1.14.1 Extension Structure Levels

There are two levels of extension structures:

  1. The simple SS_EXT_T structure. This provides a generic way to pass to each API function the address of a structure that extends the functionality of that particular function.
  2. The second level of extension structures consists of all the function-specific structures, whose address is placed in the extParms field of the function specific structure prior to calling the API functions. Currently version 3.2 of SecretStore only has extensions defined for the NSSSGetServiceInformation and NSSSReadSecret function to optionally return statistical information.

    NSSO Function

    Extension Structure

    NSSSGetServiceInformation

    SS_GSINFOEXT_T

    NSSSReadSecret

    SS_READEXT_T

    NSSSWriteSecret

    SS_WRITEEXT_T

    NSSSRemoveSecret

    SS_REMEXT_T

    NSSSUnlockSecrets

    SS_UNLOCKEXT_T

    NSSSRemoveSecretStore

    SS_REMSTOREEXT_T

    NSSSEnumerateSecretIDs

    SS_ENUMEXT_T

    NSSSSetEPMasterPassword

    SS_SETMPEXT_T

    NOTE:Please refer to the Section 5.0, Functions for a discussion of the fields in each of the extension structures mentioned above.

1.14.2 Using Extension Structures

An example of how to use these extension structures is provided in the file sstst.c. Typically, the steps for using the two extension structure levels are:

  1. Allocate storage for the extension structures. This can be done on the stack or as global variables. Typically it makes sense to have only one SS_SERVER_INFO_T structure used by all the function-specific extension structures because it was designed to preserve information between function calls. The structures are initialized as they are allocated in the following code fragment:

        /* Structure passed to all API functions. */SS_EXT_T ext = {0};/* Example of structures for individual API functions */SSS_READEXT_T readInfo = {0};SSS_GSINFOEXT_T gsInfo = {0};

  2. Initialize the extension structures. All function-specific extension structures point to the same server information structure:

        readInfo.ssServerInfo = &serverInfo;gsInfo.ssServerInfo = &serverInfo;

  3. Prepare to call an API function by placing the address of the function-specific extension structure into the extParms field of the generic extension structure:

        ext.clientVersion = NSSS_VERSION_NUMBER;ext.extParms = &gsInfo;

  4. Call the desired API function.

NOTE:If all of the state data (such as changes to context or server information, etc. that can be obtained through an initializing call to NSSSGetServiceInformation and used on subsequent calls) are not provided, each API call initializes the information automatically on entry and destroys it on return. So, when enabling an application that only requires a read from SecretStore, the overhead of initialization is neither required nor recommended through calling NSSSGetServiceInformation.