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
AmMemHandle Typedef
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
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)(AmCallModemode
, AmApplicationCtxType *pAppContext
, AmTokenPrivType *pPrivToken
, AmAuthenticationEnumauthType
, 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_textInfoLen
); status_t (*pluginImportTokenFtn) (AmTokenPrivType *pPrivToken
, uint8_t *pBuffer
, uint32_tbufferLen
); 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 anAmPluginCodePrintExtInfoType
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:
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
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
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, orNULL
if there is no additional data.
AmTokenPrivType Struct
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
AmCallMode Enum
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
AmInitializeUIContext Function
Purpose
Locks the UI context and grabs the event queue from the calling thread.
Declared In
AmPlugin.h
Prototype
status_t AmInitializeUIContext ( void )
Parameters
Returns
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
AmMemHandleFree Function
Purpose
Deallocates a dynamically-created memory chunk and disassociates it from the associated token.
Declared In
AmPlugin.h
Prototype
void AmMemHandleFree ( AmTokenPrivType*pPrivToken
, AmMemHandlehMem
)
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
Comments
The memory chunk being freed should not be locked when this function is called.
See Also
AmMemHandleNew()
, MemHandleFree()
AmMemHandleLock Function
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
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_tsize
)
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
Purpose
Unlocks a vault memory chunk previous locked with AmMemHandleLock()
.
Declared In
AmPlugin.h
Prototype
void AmMemHandleUnlock ( AmMemHandlehMem
, MemPtrpMem
)
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
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
Purpose
Unlock the UI context, and release the event queue.
Declared In
AmPlugin.h
Prototype
status_t AmReleaseUIContext ( void )
Parameters
Returns
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()
.