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
AmApplicationCtxType Struct
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 thedata
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.
AmPluginInfoType Struct
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
Purpose
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
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
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
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
Purpose
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
Well-Known Tokens
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
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 returnsamInvalidToken
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
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
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
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
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
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
AmAuthenticateToken Function
Purpose
Declared In
Am.h
Prototype
status_t AmAuthenticateToken ( AmTokenTypetoken
, AmApplicationCtxPtrpAppCtx
, AmAuthenticationEnumauthType
, 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
Purpose
Declared In
Am.h
Prototype
status_t AmCreateToken ( AmTokenPtrpToken
, char*pSystemId
, char*pFriendlyName
, AmTokenPropertiesPtrpProperties
, AmApplicationCtxPtrpAppCtx
, BooleansystemToken
)
Parameters
-
← pToken
- Pointer to an
AmTokenType
variable that receives the reference to the newly-created token. If an error occurs,*
pToken
is set toamInvalidToken
. -
→ 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
Purpose
Frees all resources associated with a specified token.
Declared In
Am.h
Prototype
status_t AmDestroyToken ( AmTokenTypetoken
, AmApplicationCtxPtrpAppCtx
)
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
Purpose
Get the public info block for a plug-in.
Declared In
Am.h
Prototype
status_t AmGetPluginInfo ( AmPluginTypeplugin
, AmPluginInfoPtrpInfo
)
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:
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
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 anAmPluginType
that references a single plug-in. -
↔ pSize
- The number of elements in the
refList
array. IfrefList
isNULL
, 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
AmGetTokenBySystemId Function
Purpose
Find a token reference given its system ID.
Declared In
Am.h
Prototype
status_t AmGetTokenBySystemId ( AmTokenPtrpToken
, 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:
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
Purpose
Get extra information about this token.
Declared In
Am.h
Prototype
status_t AmGetTokenExtendedInfo ( AmTokenTypetoken
, 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. IfpExtInfo
isNULL
or if this parameter's value indicates that thepExtInfo
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 Function
Purpose
Get the public info block for the referenced token.
Declared In
Am.h
Prototype
status_t AmGetTokenInfo ( AmTokenTypetoken
, AmTokenInfoPtrpInfo
)
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:
Comments
Applications call this function after creating a token to examine the properties of the generated token.
See Also
AmCreateToken()
, AmGetTokenExtendedInfo()
AmModifyToken Function
Purpose
Replace or modify an existing token.
Declared In
Am.h
Prototype
status_t AmModifyToken ( AmTokenTypetoken
, AmTokenPropertiesPtrpProperties
, AmApplicationCtxPtrpAppCtxOld
, AmApplicationCtxPtrpAppCtxNew
)
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
Purpose
Register a plug-in in the Authentication Manager.
Declared In
Am.h
Prototype
status_t AmRegisterPlugin ( uint32_tcreator
, Booleanforce
)
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 tofalse
.
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 Function
Purpose
Declared In
Am.h
Prototype
status_t AmRemovePlugin (
uint32_t creator
)
Parameters
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.