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

3    Authentication Manager

Security and Cryptography

Exploring Palm OS

The Authentication Manager provides abstract methods for authenticating access to protected objects. It allows modules (plug-ins) to be written that implement specific authentication scenarios, such as PIN, PKI, or password. Users of the Authentication Manager deal with generic interfaces and opaque objects that define an authentication context.

The Authentication Manager is the authority that can answer the question "Are you X?" reliably, by utilizing some method of identity verification. The question "Are you X?" may be asked either about a user or an application.

The services provided by the Authentication Manager handle the following tasks: credential (token) management (creation, deletion, modification, and storage), authentication against stored credentials (querying user for system password), and a framework for run-time extensibility via plug-ins.

Every authentication model is a plug-in. Palm OS Cobalt includes three authentication models: password, signed code, and hashed code.

The remainder of this chapter documents the Authentication Manager APIs. It is organized into the following sections:

Authentication Manager Structures and Types
Authentication Manager Constants
Authentication Manager Functions and Macros

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

Authentication Manager Structures and Types ^TOP^

AmApplicationCtxType Struct ^TOP^

Purpose

A data structure that is prepared by the caller of the Authentication Manager, it holds information about the application that needs to be authenticated and other private data specific to the plug-in. The data for the plug-in is defined by plug-in type.

Declared In

Am.h

Prototype

typedef struct {
   uint32_t processIDKey;
   AmTokenEnum dataType;
   uint8_t padding1;
   uint16_t padding2;
   union {
      struct {
         char *password;
         uint32_t passwordLength;
         char *hint;
         uint32_t hintLength;
      } passwordCtxType;
      struct {
         uint8_t *certificateId;
         uint32_t certificateIdLength;
      } signatureCtxType;
      struct {
         uint32_t type;
         uint32_t creator;
         char *dbname;
         uint32_t dbnameLength;
      } appFingerprintCtxType;
      struct {
         uint8_t *dataPtr;
         uint32_t dataLength;
      } customCtxType;
   } data;
} AmApplicationCtxType, *AmApplicationCtxPtr

Fields

processIDKey
Used during authentication. The key ID of the application being authenticated must be placed here. Mostly used by the Authorization Manager, but anyone calling AmAuthenticateToken() should fill this member in.
dataType
The type of data being passed. This is one of the AmTokenEnum values, and it controls which of the data enum data structures applies.
padding1
Padding bytes.
padding2
Padding bytes.
passwordCtxType
Data structure used when creating a password token.
password
The clear-text password. Depending on the call, this field is used to verify or set the password.
passwordLength
Length of the password buffer, bytes.
hint
Hint to save in the new password token.
hintLength
Length of the hint buffer, in bytes.
signatureCtxType
Data structure used when creating a signed-code token.
certificateId
ID of the certificate. This field is used during creation.
certificateIdLength
Length of the certificate ID buffer, in bytes.
appFingerprintCtxType
Data structure used when creating a code-fingerprint token.
type
The type of the application's resource database.
creator
The creator ID of the application's resource database.
dbname
The name of the application's resource database.
dbnameLength
The length, in bytes, of the application's resource database name.
customCtxType
Data structure used when both creating and verifying a custom token.
dataPtr
A data buffer passed into the plug-in.
dataLength
The length, in bytes, of the data buffer passed into the plug-in.

AmPluginInfoType Struct ^TOP^

Purpose

A structure through which the Authorization Manager shares information about a plug-in with applications. Use AmGetPluginInfo() to get plug-in information.

Declared In

Am.h

Prototype

typedef struct {
   char friendlyName[amPluginFriendlyNameLength];
   char vendor[amPluginVendorLength];
   uint32_t version;
   AmTokenPropertiesType tokenProperties;
} AmPluginInfoType, *AmPluginInfoPtr

Fields

friendlyName
A "friendly" name for the plug-in that can be used for display purposes.
vendor
A string that identifies the vendor of this plug-in.
version
The plug-in's version.
tokenProperties
The properties of the tokens that this plug-in creates. A AmTokenPropertiesType value.

AmPluginType Typedef ^TOP^

Purpose

Reference to a token.

Declared In

Am.h

Prototype

typedef uint32_t AmPluginType

Comments

Supply a token reference of this type when getting information about a plug-in (AmGetPluginInfo()). When you retrieve a list of all plug-ins (with AmGetPluginReferences()), you receive a set of AmPluginType values.

AmTokenAttributesType Struct ^TOP^

Purpose

Flags that indicate various token attributes. The plug-in sets these values and uses them to allow or reject certain actions.

Declared In

Am.h

Prototype

typedef struct {
   int destroy:1;
   int modify:1;
   int interactive:1;
   int empty:1;
   int system:1;
   int reserved:11;
   uint16_t padding;
} AmTokenAttributesType, *AmTokenAttributesPtr

Fields

destroy
The token may be destroyed.
modify
The token can be modified.
interactive
The token is user interactive. That is, it is a password, PIN, or the like.
empty
The token is empty.
system
The token is a system token.
reserved
Reserved for future use.
padding
Padding bits.

AmTokenInfoType Struct ^TOP^

Purpose

The public info block that the plug-in fills in. Applications may request this info block by calling AmGetTokenInfo().

Declared In

Am.h

Prototype

typedef struct {
   AmTokenType ref;
   AmTokenEnum type;
   AmTokenCacheSettings cacheSettings;
   AmTokenStrength strength;
   uint8_t rfu;
   AmTokenAttributesType attributes;
   uint8_t systemId[amTokenSystemIdLength];
   char friendlyName[amTokenFriendlyNameLength];
} AmTokenInfoType, *AmTokenInfoPtr

Fields

ref
Reference to the token.
type
The token's type. One of the AmTokenEnum values.
cacheSettings
The cache settings that govern this token. One of the AmTokenCacheSettings values.
strength
The strength of the token. One of the AmTokenStrength values.
rfu
Reserved for future use.
attributes
Token attribute flags. See AmTokenAttributesType for the attribute flag values.
systemId
The token's system ID. Token system IDs will never exceed amTokenSystemIdLength bytes in length.
friendlyName
A "friendly" name for the token that can be used for display purposes.

AmTokenPropertiesType Struct ^TOP^

Purpose

Structure containing various token properties. Used when creating or modifying a token with AmCreateToken() or AmModifyToken().

Declared In

Am.h

Prototype

typedef struct {
   uint32_t identifier;
   AmTokenEnum type;
   AmTokenStrength strength;
   AmTokenCacheSettings cacheSettings;
   uint8_t rfu;
} AmTokenPropertiesType, *AmTokenPropertiesPtr

Fields

identifier
Identifier for the plug-in that will service this token.
type
The token's type. One of the AmTokenEnum values.
strength
The strength of the token. One of the AmTokenStrength values.
cacheSettings
The cache settings that will govern this token. One of the AmTokenCacheSettings values.
rfu
Reserved for future use.

Comments

This structure is used during token creation. The application creating the token fills in the token type, strength and cache settings.

If the token is supported by a custom plug-in, the application should fill in the custom identifier. The Authentication Manager will match the custom identifier to the custom identifiers registered with the Authentication Manager.

AmTokenType Typedef ^TOP^

Purpose

Reference to a token.

Declared In

Am.h

Prototype

typedef uint32_t AmTokenType, *AmTokenPtr

Comments

Supply a token reference of this type when creating, modifying, destroying, or getting information about a token.

Authentication Manager Constants ^TOP^

Well-Known Tokens ^TOP^

Purpose

System IDs of various well-known tokens.

Declared In

Am.h

Constants

#define SysAdminToken "SysAdminToken"
The Administrator token.
#define SysEmptyToken "SysEmptyToken"
The empty token.
#define SysLockOutToken "SysLockOutToken"
The "lockout" token.
#define SysUserToken "SysUserToken"
The User token.

Miscellaneous Authentication Manager Constants ^TOP^

Purpose

The header file Am.h also declares these constants.

Declared In

Am.h

Constants

#define amInvalidToken 0xFFFFFFFF
An invalid token value. If AmCreateToken() fails, it returns amInvalidToken as a token value.
#define amPluginFriendlyNameLength 48
The maximum length, in bytes, of a plug-in's "friendly" name--a name that can be displayed to the user.
#define amPluginVendorLength 48
The maximum length, in bytes, of a plug-in's vendor string.
#define AmServiceName "psysAuthenticationMgr"
The name under which the Authentication Manager is registered with the Service Manager.
#define amTokenFriendlyNameLength 36
The maximum length, in bytes, of a token's "friendly" name--a name that can be displayed to the user.
#define amTokenSystemIdLength 20
The maximum length, in bytes, of a token's system ID.
#define amTokenTypeIdentifierLength 8

Authentication Manager Error Codes ^TOP^

Purpose

Error codes returned by the various Authentication Manager functions.

Declared In

Am.h

Constants

#define amErrActionNotSupported (amErrorClass | 0x16)
The required action is not suppoted for this token by its plug-in.
#define amErrAlreadyRegistered (amErrorClass | 0x0D)
The specified plug-in was already registered.
#define amErrAuthenticationFailed (amErrorClass | 0x10)
The authentication operation failed.
#define amErrBackupInProgress (amErrorClass | 0x17)
A backup is in progress.
#define amErrBufferTooSmall (amErrorClass | 0x14)
The supplied buffer is too small.
#define amErrInvalidImportBuffer (amErrorClass | 0x15)
The supplied import buffer is invalid.
#define amErrInvalidParam (amErrorClass | 0x02)
One or more function parameters is invalid.
#define amErrInvalidPlugin (amErrorClass | 0x0B)
The specified plug-in reference is invalid.
#define amErrInvalidToken (amErrorClass | 0x09)
The specified token reference is invalid.
#define amErrLibNotOpen (amErrorClass | 0x03)
The library has not been opened.
#define amErrLibStillOpen (amErrorClass | 0x04)
An attempt to close the library returned without closing.
#define amErrMaxPlugins (amErrorClass | 0x0A)
The maximum number of plug-ins allowed in the system has been reached.
#define amErrMaxTokens (amErrorClass | 0x08)
The maximum number of tokens allowed in the system has been reached.
#define amErrMemory (amErrorClass | 0x06)
An internal memory error occurred.
#define amErrNoPluginsAllowed (amErrorClass | 0x11)
Security is set to high: no plug-ins are allowed.
#define amErrNotFound (amErrorClass | 0x0C)
The named resource was not found.
#define amErrNotImplemented (amErrorClass | 0x01)
The plug-in does not implement the requested function.
#define amErrOutOfMemory (amErrorClass | 0x05)
There was insufficient memory to complete the requested operation.
#define amErrResourceNotFound (amErrorClass | 0x0E)
An Authentication Manager resource or plug-in is missing.
#define amErrTokenDestroyed (amErrorClass | 0x12)
The token was destroyed during the action.
#define amErrTokenExists (amErrorClass | 0x13)
The named token already exists.
#define amErrUnsupportedTokenType (amErrorClass | 0x07)
The requested token type is unsupported.
#define amErrUserCancel (amErrorClass | 0x0F)
The user cancelled the action (such as password gathering).

AmAuthenticationEnum Enum ^TOP^

Purpose

An enumeration of the different types of authentication situations. When calling AmAuthenticateToken() you can pass a situation so that the plug-in will have an idea of the type of UI to put up for the user.

Declared In

Am.h

Constants

AmAuthenticationNone = 0
System use only.
AmAuthenticationOther
Other authentication.
AmAuthenticationDataAccess
Database access.
AmAuthenticationDeviceUnlock
The device is being unlocked.
AmAuthenticationTokenModify
The token is being modified. For instance, the password is changing.

AmTokenCacheSettings Enum ^TOP^

Purpose

Different policies that can be applied to a token in the system. The application creating the token defines the cache settings.

Declared In

Am.h

Constants

AmTokenCacheNever
The token is not cached.
AmTokenCacheSystem
The token is kept in the system's token cache.

AmTokenEnum Enum ^TOP^

Purpose

An enumeration of the different types of tokens that can be requested from the system.

Declared In

Am.h

Constants

AmTokenUnknown = 0
The token type is unknown.
AmTokenCustom
A custom token. See the Comments section, below, for more on custom tokens.
AmTokenPassword
A password token.
AmTokenSignedCode
A signed code token.
AmTokenCodeFingerprint
A code-fingerprint (hash) token.

Comments

These are the most common type of tokens that the device will deal with. The custom type allows the plug-in to announce a custom type of plug-in that it will service. If an application requests a custom type token, the Authentication Manager examines all plug-ins and find all that match that custom type. Out of all the matches the best fit is picked to create the token.

AmTokenStrength Enum ^TOP^

Purpose

Token strengths: the minimum level of strength that a plug-in supports for token creation.

Declared In

Am.h

Constants

AmTokenStrengthLow
Lowest level. No requirements for token creation.
AmTokenStrengthMedium
Some measures are taken to reject weak tokens.
AmTokenStrengthHigh
The generated token should be guaranteed to not be a weak token.

Comments

A weak token is an authentication token that can be easily guessed or broken, such as dictionary words for passwords, or weak cryptography keys.

Authentication Manager Functions and Macros ^TOP^

AmAuthenticateToken Function ^TOP^

Purpose

Authenticates a token.

Declared In

Am.h

Prototype

status_t AmAuthenticateToken (
   AmTokenType token,
   AmApplicationCtxPtr pAppCtx,
   AmAuthenticationEnum authType,
   char *titleString,
   char *descriptionString
)

Parameters

token
The token to be authenticated.
pAppCtx
A pointer to the application context information. The application context contains data that the application wishes to pass to the plug-in. The plug-in may also return data in this structure.
authType
A hint to the Authentication Manager about why the token is being authenticated—one of the AmAuthenticationEnum values. This hint will be passed onto the plug-in that handles this type of token. The plug-in is free to use the hint as it sees fit. The hint is useful when the plug-in displays UI to the user.
titleString
An optional string that is passed into the plug-in. The plug-in may choose to display the string to the user if it is interactive. The string is meant to be a reason for the authentication request. Pass NULL if the plug-in doesn't display a string or if you don't want one displayed.
The plug-in will typically display this string on the title of the modal window for authentication. Accordingly, the string must fit in the title of the window.
descriptionString
An optional string that is passed into the plug-in. The plug-in may choose to display the string to the user if it is interactive. The string is meant to be a more in-depth description of the reason for the authentication request. Pass NULL if the plug-in doesn't display a string or if you don't want one displayed.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

AmErrInvalidToken
The token reference is invalid.
AmErrAuthenticationFailed
The authentication failed.
AmErrOutOfMemory
The Authentication Manager ran out of memory while attempting to authenticate the token.

Comments

The Authentication Manager invokes the plug-in to gather a new token, and then calls the plug-in to compare the new token with the supplied token. If the plug-in decides that they are a match, the authentication is successful.

AmCreateToken Function ^TOP^

Purpose

Create a new token.

Declared In

Am.h

Prototype

status_t AmCreateToken (
   AmTokenPtr pToken,
   char *pSystemId,
   char *pFriendlyName,
   AmTokenPropertiesPtr pProperties,
   AmApplicationCtxPtr pAppCtx,
   Boolean systemToken
)

Parameters

pToken
Pointer to an AmTokenType variable that receives the reference to the newly-created token. If an error occurs, *pToken is set to amInvalidToken.
pSystemId
Optional system name for this token. This is a system unique name; applications can later get a reference to this token by looking up this ID. If this argument is set to NULL, a system ID will be assigned by the Authentication Manager to this token.
The name is copied into system space, so it may be de-allocated by the caller as soon as this function returns.
pFriendlyName
Optional pointer to a string buffer containing the "friendly" name that will be associated with this token. This is a name that can be displayed to the user.
pProperties
A description of the parameters the new token should meet. The system will attempt to meet all requirements, but this is not guaranteed. The only parameter that must be met is the type of token.
pAppCtx
A pointer to the application context information. The application context contains data that the application wishes to pass to the plug-in. The plug-in may also return data in this structure.
systemToken
true if this token should be marked as a system token. The only difference between a non-system token and a system token is that when they are destroyed, the reference to the token is not invalidated. The Authentication Manager will keep the token's reference valid, but the token will be empty after being destroyed. The notification about the token being destroyed is still sent to the Authorization Manager.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

AmErrInvalidParam
One of the input parameters is invalid (most likely a NULL pToken).
AmErrSystemIDInUse
The specified token system ID is already in use.
AmErrSystemIDTooLong
The name was larger than allowed. The token was not created.
AmErrOutOfMemory
The Authentication Manager ran out of memory
AmErrUnsupportedTokenType
The specified token type is not supported

Comments

The token property parameter is used by the caller to describe the desired properties of the new token. The system will find the plug-in that best meets these requirements, but does not guarantee that all (or any) requirements will be met. Once a token has been created, the caller may call AmGetTokenInfo() to get the properties of the created token.

See Also

AmDestroyToken(), AmModifyToken()

AmDestroyToken Function ^TOP^

Purpose

Frees all resources associated with a specified token.

Declared In

Am.h

Prototype

status_t AmDestroyToken (
   AmTokenType token,
   AmApplicationCtxPtr pAppCtx
)

Parameters

token
Reference to the token to destroy.
pAppCtx
A pointer to the application context information. The application context contains data that the application wishes to pass to the plug-in. The plug-in may also return data in this structure.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

AmErrInvalidParam
One of the input parameters is invalid.
AmErrInvalidToken
The referenced token does not exist.
AmErrTokenDestructionRejected
Destruction of the token failed, either due to the user rejecting it, or the plug-in vetoing the destruction, or the authentication of the protecting token failing.

Comments

Call this function when you would like to remove the token from the system, but cannot authenticate against it prior to its deletion. (That is, the token is lost).

The Authentication Manager will verify if there are other tokens protecting the destruction of this token. If there are, those tokens must be authenticated prior to destruction of the specified token.

The Authentication Manager will verify if the action is allowed with the plug-in. If it is allowed then the token will be removed, along with all the data that it protected. Care must be taken when a plug-in allows destruction of tokens, as the deletion of certain data objects may leave the system in a non-useful state.

Any application may call this function when a token is lost, even if they did not create the token. (All data protected by this token is deleted though, so this doesn't introduce a security loophole). The Authentication Manager will display a dialog informing the user that the destruction of the token will lead to possible data loss.

When the token is destroyed, a notification is broadcast throughout the system about the token being destroyed.

See Also

AmCreateToken(), AmModifyToken()

AmGetPluginInfo Function ^TOP^

Purpose

Get the public info block for a plug-in.

Declared In

Am.h

Prototype

status_t AmGetPluginInfo (
   AmPluginType plugin,
   AmPluginInfoPtr pInfo
)

Parameters

plugin
AmPluginType that references the plug-in for which you want information.
pInfo
Pointer to an AmPluginInfoType structure, allocated by the caller, that is filled in by this function.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

AmErrInvalidParam
pInfo is NULL.
AmErrInvalidPlugin
The reference to the plug-in is invalid.

Comments

The AmPluginInfoType data structure contains information about the plug-in, such as vendor name, friendly name, and information about the type of tokens that the plug-in can create.

AmGetPluginReferences Function ^TOP^

Purpose

Get references to all of the plug-ins registered on the system.

Declared In

Am.h

Prototype

status_t AmGetPluginReferences (
   AmPluginType *refList,
   uint16_t *pSize
)

Parameters

refList
A caller-allocated array where references to the installed plug-ins are returned, or NULL to determine how large the array should be. Each array element is an AmPluginType that references a single plug-in.
pSize
The number of elements in the refList array. If refList is NULL, or if the supplied array isn't large enough, this function sets *pSize to the required array size.

Returns

Returns errNone if the operation completed successfully, or AmErrBufferTooSmall if the supplied buffer is too small.

Comments

When calling this function you must pre-allocate an array of references and pass the address of this array in refList. If the buffer is too small or if refList is NULL, the pSize parameter is set to the required number of entries in the array. Accordingly, you may want to call this function twice. First, call it with refList set to NULL in order to obtain the size of the needed buffer. Then, after allocating a buffer of the proper size, call this function again to obtain the plug in references.

See Also

AmGetPluginInfo()

AmGetTokenBySystemId Function ^TOP^

Purpose

Find a token reference given its system ID.

Declared In

Am.h

Prototype

status_t AmGetTokenBySystemId (
   AmTokenPtr pToken,
   char *pSystemId
)

Parameters

pToken
Pointer to an AmTokenType variable that receives the reference to the token.
pSystemId
The token's system ID.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

AmErrSystemIDUnknown
The requested token was not found
AmErrInvalidParameter
pToken is NULL

Comments

This function allows for the creation of "well known" tokens, such as the system password, and the admin password on a device. Applications that wish to protect data with the system password can get a reference to it by invoking this function. See "Well-Known Tokens" for the predefined set of well-known tokens.

AmGetTokenExtendedInfo Function ^TOP^

Purpose

Get extra information about this token.

Declared In

Am.h

Prototype

status_t AmGetTokenExtendedInfo (
   AmTokenType token,
   uint8_t *pExtInfo,
   uint32_t *pExtInfolen
)

Parameters

token
A reference to the token about which information is needed.
pExtInfo
Pointer to the buffer into which the information is written, or NULL to determine how large the buffer should be.
pExtInfolen
The size of the pExtInfo buffer. If pExtInfo is NULL or if this parameter's value indicates that the pExtInfo buffer isn't large enough to hold the information to be returned, the size of the needed buffer is written to *pExtInfolen.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

AmErrInvalidParam
pExtInfo is NULL.
AmErrInvalidToken
The referenced token is invalid.
AmErrBufferTooSmall
pExtInfo is too small to hold the extended information. The correct size is returned in *pExtInfolen.
AmErrNotSupported
The underlying plug-in doesn't provide any extra information about the token.

Comments

The plug-in responds to this call directly. For PKI tokens managed by the Palm OS PKI plug-in, the returned data is the certificate ID of the token (in an AmPluginSignedCodeExtInfoType structure). For tokens managed by the Palm OS Code Fingerprint plug-in, the returned data contains the type, creator, and name of the database that was fingerprinted (in an AmPluginCodePrintExtInfoType structure). For password tokens managed by the Palm OS password plug-in, the returned data is the hint. No extended information is available for code-fingerprint tokens managed by the Palm OS code-fingerprint plug-in.

See Also

AmGetTokenInfo()

AmGetTokenInfo Function ^TOP^

Purpose

Get the public info block for the referenced token.

Declared In

Am.h

Prototype

status_t AmGetTokenInfo (
   AmTokenType token,
   AmTokenInfoPtr pInfo
)

Parameters

token
A reference to the token about which information is needed.
pInfo
Pointer to a location into which the contents of the token's public info block are written. This should be a AmTokenInfoType structure.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

AmErrInvalidParam
pInfo is NULL.
AmErrInvalidToken
The referenced token is invalid.

Comments

Applications call this function after creating a token to examine the properties of the generated token.

See Also

AmCreateToken(), AmGetTokenExtendedInfo()

AmModifyToken Function ^TOP^

Purpose

Replace or modify an existing token.

Declared In

Am.h

Prototype

status_t AmModifyToken (
   AmTokenType token,
   AmTokenPropertiesPtr pProperties,
   AmApplicationCtxPtr pAppCtxOld,
   AmApplicationCtxPtr pAppCtxNew
)

Parameters

token
Reference to the token to be modified. The new token replaces the old token, using the same reference.
pProperties
An optional description of the parameters the new token should meet. The system will attempt to meet all requirements, but that is not guaranteed. The only parameter that must be met is the type of token.
If no new properties are specified (pass NULL for this parameter), the properties of the token being modified are not changed.
pAppCtxOld
A pointer to the application context information as it relates the token being modified. The caller may place information required to authenticate the token—such as a password, for a password token—in the application context.
pAppCtxNew
A pointer to the application context information for the new token that will be created to replace the token being modified, or NULL. The caller may place information needed to create the token in this optional parameter.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

AmErrInvalidParam
One of the input parameters is invalid (most likely a NULL pToken).
AmErrInvalidToken
The specified token was not found.
AmErrOutOfMemory
The Authentication Manager ran out of memory
AmErrUnsupportedTokenType
Token type is not supported
AmErrModifyRejected
The modification action was rejected: authentication of the token protecting the to-be-modified token must have failed.

Comments

Applications wishing to change tokens, (for instance, to change the password, clear the password, and so on) use this function. This function can be used to replace or even remove (by making the token empty) an authentication token. The token being modified is destroyed and a new token is created which takes its place.

The actual operation of this function depends on the plug-in.

If the token properties are specified, and a different token type is requested, then the replacement token that is created will be of a different type. (For example, you may replace a password token with a biometric token). This means that the authentication model is changed.

Tokens may be protected from modification by authentication contexts. With the help of the Authorization Manager the Authentication Manager authenticates the user prior to modification of the token.

After authentication for modify, the Authentication Manager creates a new token, given the properties supplied in pProperties. The new token will replace the old token.

See Also

AmCreateToken(), AmDestroyToken()

AmRegisterPlugin Function ^TOP^

Purpose

Register a plug-in in the Authentication Manager.

Declared In

Am.h

Prototype

status_t AmRegisterPlugin (
   uint32_t creator,
   Boolean force
)

Parameters

creator
The creator ID of the plug-in being registered.
force
true to force the registration, even if the plug-in has already been loaded.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

AmErrOutOfMemory
Out of memory.
AmErrAlreadyRegistered
The plug-in was already registered and force is set to false.

Comments

Note that although you specify the plug-in's creator, you don't specify its type. The plug-in type is implicit: all plug-ins are of type 'ampl'.

The plug-in's shared library need not be loaded prior to registration. This function loads and opens the shared library. If you set force to true, forcing a re-registration, the shared library is closed and unloaded. Then, it is reloaded and reopened. The reference to the plug-in doesn't change: it is re-used. Thus, all tokens still have a valid reference to their creator.

See Also

AmRemovePlugin()

AmRemovePlugin Function ^TOP^

Purpose

Remove a registered plug-in.

Declared In

Am.h

Prototype

status_t AmRemovePlugin (
   uint32_t creator
)

Parameters

creator
The creator ID of the plug-in being removed.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

AmErrNotFound
A plug-in with the specified creator ID has not been registered.
AmErrHasTokens
Tokens exist for this plug-in, and removing the plug-in would invalidate them.

Comments

In order for this function to work, there must not be any tokens with references back to this plug-in.

See Also

AmRegisterPlugin()