Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

4    AmPlugin

Security and Cryptography

Exploring Palm OS

AmPlugin.h declares a set of APIs that are used by Authentication Manager plug-ins to implement a particular authentication model.. These plug-ins are shared libraries of type 'ampl'. After initialization, which is done by sending the plug-in standard launch codes, the Authentication Manager interacts with functions exported by the plug-in through the AmPluginFunctionsType structure.

The contents of this chapter are divided into the following sections:

AmPlugin Structures and Types
AmPlugin Constants
AmPlugin Functions and Macros

The header file AmPlugin.h declares the API that this chapter describes.

For information on writing Authentication Manager plug-ins, see "Creating an Authentication Manager Plug-In." Information on registering a plug-in with the Authentication Manager or removing a registered plug-in can be found under "Manipulating Authentication Manager Plug-Ins."

AmPlugin Structures and Types ^TOP^

AmMemHandle Typedef ^TOP^

Purpose

Handle to a memory chunk allocated in the vault.

Declared In

AmPlugin.h

Prototype

typedef uint32_t AmMemHandle

Comments

You must use the AmMemHandle... functions to manipulate Authentication Memory handles. All dynamic memory used by a plug-in that is associated with a token should be done through a call to one of the AmMemHandle... functions.

AmPluginFunctionsType Struct ^TOP^

Purpose

Identifies those functions in the set that makes up the interface between the Authentication Manager and a plug-in that are implemented by the plug-in.

Declared In

AmPlugin.h

Prototype

typedef struct {
   status_t (*pluginCaptureFtn)(AmCallMode mode,
      AmApplicationCtxType *pAppContext,
      AmTokenPrivType *pPrivToken,
      AmAuthenticationEnum authType,
      char *title, char *description);
   status_t (*pluginMatchFtn)
      (AmApplicationCtxType *pAppContext,
      AmTokenPrivType *pToken1,
      AmTokenPrivType *pToken2);
   status_t (*pluginDestroyNotifyFtn)
      (AmTokenPrivType *pPrivToken);
   status_t (*pluginGetTokenExtendedInfoFtn)
      (AmTokenPrivType *pPrivToken,
      uint8_t *pExtInfo, uint32_t extInfoLen);
   status_t (*pluginImportTokenFtn)
      (AmTokenPrivType *pPrivToken, 
      uint8_t *pBuffer, uint32_t bufferLen);
   status_t (*pluginExportTokenFtn)
      (AmTokenPrivType *pPrivToken,
      uint8_t *pBuffer, uint32_t *bufferLen);
   status_t (*pluginGetDerivedData)
      (AmTokenPrivType *pPrivToken,
      uint8_t *data, uint32_t *dataLength);
   status_t (*pluginAdminFtn)
      (AmPluginType *plugin);
} AmPluginFunctionsType

Fields

pluginCaptureFtn
The Capture function is called whenever the AM needs your plug-in to create a new token, or to verify or replace an existing token created by the plug-in. Parameters passed to this function are:
mode
An AmCallMode that indicates whether the plug-in should create, verify, or replace a token.
pAppContext
An AmApplicationCtxType structure that holds information about the application that needs to be authenticated and other private data specific to the plug-in.
pPrivToken
An AmTokenPrivType data structure that holds information regarding the credentials that must be matched for a valid authentication to occur.
authType
A AmAuthenticationEnum value that identifies the authentication situation—the reason that the plug-in is being called.
title
An optional string that the plug-in may choose to display to the user. The string is meant to be a reason for the authentication request. This parameter is NULL if the caller doesn't want a string to be displayed.
description
An optional string that the plug-in may choose to display to the user. The string is meant to be a more in-depth description of the reason for the authentication request. This parameter is NULL if the caller doesn't want such a string to be displayed.
pluginMatchFtn
When the AM needs to verify a token it invokes the associated plug-in's Match entry point, passing in two token structures for comparision. Parameters passed to this function are:
pAppContext
An AmApplicationCtxType structure that holds information about the application that needs to be authenticated and other private data specific to the plug-in.
pToken1
An AmTokenPrivType data structure that holds information regarding the credentials for the first token being matched.
pPToken2
An AmTokenPrivType data structure that holds information regarding the credentials for the second token being matched.
pluginDestroyNotifyFtn
The Destroy Notify entry point is called when a token is destroyed. Destroying a token is an action that may be taken if the user has lost the ability to authenticate against that token (as in the case of a lost password). This function takes a single parameter:
pPrivToken
An AmTokenPrivType data structure that holds information about the token being destroyed.
pluginGetTokenExtendedInfoFtn
The Get Extended Info function is used to answer the query for extended info by an application. A plug-in is not required to support this entry point, though it can be useful for certain types of tokens. The Palm OS PKI plug-in returns the certificate ID of the token (in an AmPluginSignedCodeExtInfoType structure). The Palm OS Code Fingerprint plug-in returns the type, creator, and name of the database that was fingerprinted (in an AmPluginCodePrintExtInfoType structure). The Palm OS password plug-in, however, doesn't implement this function. Parameters passed to this function are:
pPrivToken
An AmTokenPrivType data structure that holds information about the token for which extended information is being requested.
pExtInfo
Pointer to the buffer into which the information is to be written.
extInfoLen
The size, in bytes, of the pExtInfo buffer.
pluginImportTokenFtn
The Import and Export entry points are for copying internal data about a token for import or export. In your import function, the contents of the provided buffer should be copied to memory that is associated with a token and is managed by the plug-in. Parameters passed to this function are:
pPrivToken
An AmTokenPrivType data structure that holds information about the token being imported.
pBuffer
Pointer to the buffer containing the token info being imported.
bufferLen
The size, in bytes, of the pBuffer buffer.
pluginExportTokenFtn
The Import and Export entry points are for copying internal data about a token for import or export. In your export function, memory that is associated with a token and is managed by the plug-in should be copied to the provided buffer and returned to the AM. Parameters passed to this function are:
pPrivToken
An AmTokenPrivType data structure that holds information about the token being exported.
pBuffer
Pointer to the buffer into which the token info should be written.
bufferLen
The size, in bytes, of the pBuffer buffer.
pluginGetDerivedData
The Get Derived Data function is used solely by the operating system to get seed data for a cryptographic key derived from an authentication token (such as password derived keys). Currently the only user of this feature is the Data Manager; it uses this feature to generate password-derived keys for the backup function. Parameters passed to this function are:
pPrivToken
An AmTokenPrivType data structure that holds information about the token for which derived data is being requested.
data
Buffer into which your function should write seed data derived from the authentication token.
dataLength
Size, in bytes, of the data buffer.
pluginAdminFtn
This function is the admin entry point for the plug-in. Some plug-ins may have settings that can be changed (a biometric plug-in, for instance, might allow the user to tweak the settings it uses to match tokens); accordingly, the plug-in can implement an admin UI in its implementation of this function. Parameters passed to this function are:
plugin
A reference to the plug-in.

Comments

These functions may return any error defined in Am.h.

Upon receipt of a sysAppLaunchCmdNormalLaunch launch code, the plug-in should, among other things, identify which of these functions it implements. Accompanying the launch code is a AmTokenPrivType structure; this structure's ftn field is an AmPluginFunctionsType structure into which you write the addresses of those functions that your plug-in implements.

AmPluginPrivType Struct ^TOP^

Purpose

Describes a plug-in. This structure is used by the AM to reference a plug-in loaded onto the system.

Declared In

AmPlugin.h

Prototype

typedef struct {
   AmPluginType pluginRef;
   uint32_t recordId;
   AmPluginInfoType info;
   uint32_t tokenDataLength;
   uint32_t tokenExtendedInfoLength;
   AmPluginFunctionsType ftn;
} AmPluginPrivType, *AmPluginPrivPtr

Fields

pluginRef
Reference to this plug-in. This field is set by the AM.
recordId
Record ID for this plug-in in the AM vault. This field is set by the AM.
info
An AmPluginInfoType structure that contains information about the plug-in to be shared with applications.
tokenDataLength
The size, in bytes, of the tokens managed by this plug-in.
tokenExtendedInfoLength
The length, in bytes, of any extended information that is returned to caller by the Get Extended Info entry point.
ftn
A list of plug-in entry points. Not all entry point function pointers need to be initialized: only those entry points that a plug-in chooses to implement need to be set in this structure. See AmPluginFunctionsType for the complete set of entry points a plug-in can export.

Comments

An Authentication Manager plug-in fills in a data structure of this type during initialization. Within this data structure are entry points that provide the Authentication Manager with direct access to the plug-in functions.

See the discussion of the sysAppLaunchCmdNormalLaunch launch code under "Open and Close" for more information on filling out this structure's fields.

AmTokenDataType Struct ^TOP^

Purpose

An optional linked list of record IDs that identify dynamic data associated with the token.

Declared In

AmPlugin.h

Prototype

typedef struct _AmTokenDataTag {
   uint32_t recordId;
   struct _AmTokenDataTag *next;
} AmTokenDataType, *AmTokenDataPtr

Fields

recordId
ID of the record that contains the dynamic data.
next
Pointer to the next AmTokenDataType structure in the linked list, or NULL if there is no additional data.

AmTokenPrivType Struct ^TOP^

Purpose

An opaque (to AM clients) data structure that holds information regarding the credentials that must be matched for a valid authentication to occur.

Declared In

AmPlugin.h

Prototype

typedef struct {
   AmTokenInfoType header;
   uint32_t pluginCreatorId;
   uint32_t tokenRecId;
   MemPtr dataPtr;
   uint32_t dataLength;
   AmTokenDataPtr dynamicData;
} AmTokenPrivType, *AmTokenPrivPtr

Fields

header
Public information common to all tokens. See AmTokenInfoType.
pluginCreatorId
The creator ID that manages this token. This is the creator ID of the plug-in.
tokenRecId
Reference to the record ID for this token in the AM vault.
dataPtr
Pointer to the token's data segment.
dataLength
Length, in bytes, of the token't data segment.
dynamicData
Pointer to an AmTokenDataType structure that holds dynamic data associated with the token.

Comments

The creation and management of tokens (these structures) is left up to the authentication plug-in.

AmPlugin Constants ^TOP^

AmCallMode Enum ^TOP^

Purpose

Indicates whether the pluginCaptureFtn() entry point function is being called to create new credentials, verify existing credentials, or replace existing credentials.

Declared In

AmPlugin.h

Constants

AmEnrollment = 0
The plug-in should create new credentials.
AmVerification
The plug-in should verify credentials.
AmReplacementStart
First phase of replacing a token. See the Comments section, below.
AmReplacementEnd
Second phase of replacing a token. See the Comments section, below.

Comments

The replacement mode is used when a credential is being modified. There are two stages. ReplacementStart is used first. In this stage the plug-in must authenticate whoever is trying to modify the token, be it a user or an application. ReplacementEnd is used last; this is when the plug-in creates the new replacement credentials.

AmPlugin Functions and Macros ^TOP^

AmInitializeUIContext Function ^TOP^

Purpose

Locks the UI context and grabs the event queue from the calling thread.

Declared In

AmPlugin.h

Prototype

status_t AmInitializeUIContext (
   void
)

Parameters

None.

Returns

Always returns errNone.

Comments

If your plugin needs to interact with the user, at the point where you need to display some form of UI it should call WinStartThreadUI(), then it should call this function.

If the UI context is currently locked when this function is called, this function blocks until it is released.

See Also

AmReleaseUIContext()

AmMemHandleFree Function ^TOP^

Purpose

Deallocates a dynamically-created memory chunk and disassociates it from the associated token.

Declared In

AmPlugin.h

Prototype

void AmMemHandleFree (
   AmTokenPrivType *pPrivToken,
   AmMemHandle hMem
)

Parameters

pPrivToken
Pointer to the token with which the memory chunk is associated.
hMem
Pointer to the memory chunk to be freed. This memory chunk must have been allocated with AmMemHandleNew().

Returns

Nothing.

Comments

The memory chunk being freed should not be locked when this function is called.

See Also

AmMemHandleNew(), MemHandleFree()

AmMemHandleLock Function ^TOP^

Purpose

Obtain a pointer to a chunk of memory referenced by an AmMemHandle.

Declared In

AmPlugin.h

Prototype

MemPtr AmMemHandleLock (
   AmMemHandle hMem
)

Parameters

hMem
Handle to the memory chunk. This handle must have been returned from AmMemHandleNew().

Returns

A pointer to the memory chunk, or NULL if the chunk couldn't be locked.

Comments

This function does not return a pointer to the actual memory chunk in the vault. Instead, an ordinary memory buffer of the corresponding size is allocated using MemPtrNew() and the contents of the vault chunk are copied into it. The pointer to this new buffer is returned. When AmMemHandleUnlock() is called, the buffer's contents are copied back to the vault and the buffer allocated during the call to AmMemHandleLock() is freed.

See Also

AmMemHandleNew(), AmMemHandleUnlock(), MemHandleLock()

AmMemHandleNew Function ^TOP^

Purpose

Allocates a memory chunk of a specified size in the vault and associates it with a specified token.

Declared In

AmPlugin.h

Prototype

AmMemHandle AmMemHandleNew (
   AmTokenPrivType *pPrivToken,
   uint32_t size
)

Parameters

pPrivToken
Pointer to the token with which the record is to be associated.
size
Size, in bytes, of the memory chunk to be allocated.

Returns

Returns a handle to the newly-allocated memory chunk, or 0 if the chunk could not be allocated as specified.

Comments

The newly-allocated memory chunk is actually a database record of the specified size.

You must call AmMemHandleLock() in order to obtain a pointer to a buffer into which you can write (or from which you can read).

See Also

AmMemHandleFree(), AmMemHandleLock(), MemHandleNew()

AmMemHandleUnlock Function ^TOP^

Purpose

Unlocks a vault memory chunk previous locked with AmMemHandleLock().

Declared In

AmPlugin.h

Prototype

void AmMemHandleUnlock (
   AmMemHandle hMem,
   MemPtr pMem
)

Parameters

hMem
Handle to the vault memory chunk previously allocated with AmMemHandleNew().
pMem
Pointer to the memory buffer returned from a call to AmMemHandleLock().

Returns

Nothing.

Comments

This function copies the contents of the memory buffer pMem to the memory chunk in the vault referenced by hMem. It then frees the buffer pMem.

See Also

AmMemHandleLock(), AmMemHandleNew(), MemHandleUnlock()

AmReleaseUIContext Function ^TOP^

Purpose

Unlock the UI context, and release the event queue.

Declared In

AmPlugin.h

Prototype

status_t AmReleaseUIContext (
   void
)

Parameters

None.

Returns

Always returns errNone.

Comments

As soon as possible after the AM plugin is done interacting with the user, it should call this function and then it should call WinFinishThreadUI().

See Also

AmInitializeUIContext()