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

7    Authorization Manager

Security and Cryptography

Exploring Palm OS

The Authorization Manager is the top-level component in the security suite that enables protection of objects in the operating system. The Authorization Manager is designed around the Access Control List paradigm.

The Authorization Manager maintains a list of rule-set containers that represent protected objects. Associated with each rule-set container is the protected object's fully-qualified name as defined by the creator of the protected object and one or more rules specifying how the object referenced by the Access Control List container is protected. Each rule is an association between one or more actions that could be performed on the object and the set of authentications required to perform those actions.

The Authorization Manager relies on the managers of objects to provide a fully-qualified name for the objects they want to protect, and to define what actions can be performed on those objects.

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

Authorization Manager Structures and Types
Authorization Manager Constants
Authorization Manager Functions and Macros

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

Authorization Manager Structures and Types ^TOP^

AzmActionType Typedef ^TOP^

Purpose

Defines a bitmap of actions. Each bit in the AzmActionType value corresponds to a different rule.

Declared In

azm.h

Prototype

typedef uint32_t AzmActionType

AzmNotificationType Struct ^TOP^

Purpose

Data structure that accompanies notifications sent by the Authorization Manager.

Declared In

azm.h

Prototype

typedef struct {
   union {
      struct {
         uint8_t name [azmRuleSetNameMaxLength];
         uint32_t length;
      } ruleSetDestroyed;
   } data;
   uint16_t version;
   uint16_t padding;
} AzmNotificationType

Fields

data
A union of structures, one for each of the notifications that can be sent.
ruleSetDestroyed
The data variant that applies to AzmNotificationRuleSetDestroyed notifications. This structure has two fields: the name of the rule-set being destroyed, and the length of that name.
version
The version of the AzmNotificationType structure. The structure as detailed above is version 1.
padding
Padding bytes.

AzmRuleSetType Typedef ^TOP^

Purpose

An opaque handle to an rule-set container managed by the Authorization Manager.

Declared In

azm.h

Prototype

typedef uint32_t AzmRuleSetType

Authorization Manager Constants ^TOP^

Miscellaneous Authorization Manager Constants ^TOP^

Purpose

The header file azm.h also declares these constants.

Declared In

azm.h

Constants

#define azmActionModify 0x80000000
Predefined MODIFY action. This action may not be redefined. This is an Authorization Manager-specific action which gates the modification of a rule-set container. A modification of a rule-set container is defined as creation (always allowed), addition or modification of ACE entries, or destruction.
#define azmCreator 'azm_'
Creator ID used for the vault that contains secure databases.
#define azmInvalidRuleSet 0xFFFFFFFF
Rule-set handle value representing an invalid rule-set.
#define azmMaxTokenNodes 2
Maximum number of token nodes.
#define azmMaxTokensInNode 8
Maximum number of tokens that can be placed into a single node.
#define azmMaxTokensInTree azmMaxTokenNodes * azmMaxTokensInNode
The maximum number of tokens that can occur in an access rule.
#define AzmNotificationRuleSetDestroyed 0x1
"Rule-set destroyed" notification callback opcode.
#define azmRuleFormatLength 60
The maximum length in bytes (including the null terminator) of a rule format string.
#define azmRuleSetNameMaxLength 20
The maximum length, in bytes, of an Authorization Manager rule-set name.
#define AzmServiceName "psysAuthorizationMgr"
The name under which the Authorization Manager is registered with the Service Manager.
#define azmSyncRuleSet 0x00800000
Handle to the rule-set container for synchronization.

Authorization Manager Error Codes ^TOP^

Purpose

Error codes returned by the various Authorization Manager functions.

Declared In

azm.h

Constants

#define azmErrAlreadyExists (azmErrorClass | 19)
The specified rule-set already exists.
#define azmErrAuthorizationFailed (azmErrorClass | 9)
The authorization request has failed.
#define azmErrBackupInProgress (azmErrorClass | 17)
A backup is in progress.
#define azmErrBadParam (azmErrorClass | 1)
One of the supplied parameters is invalid.
#define azmErrInvalidParameter (azmErrorClass | 18)
One of the supplied parameters is invalid.
#define azmErrInvalidReference (azmErrorClass | 8)
The reference to the rule-set container is invalid.
#define azmErrInvalidRuleSyntax (azmErrorClass | 16)
The syntax of the supplied rule definition is invalid.
#define azmErrInvalidTokenReference (azmErrorClass | 15)
The token reference is invalid.
#define azmErrMaxRuleSets (azmErrorClass | 5)
The system already has the maximum number of rule sets allowed.
#define azmErrMemory (azmErrorClass | 6)
The Authorization Manager encountered a memory error. This may indicate a possible out-of-memory condition.
#define azmErrMgrAlreadyRegistered (azmErrorClass | 13)
The manager creator ID is already registered.
#define azmErrMgrNotRegistered (azmErrorClass | 10)
A request was recieved from an unregistered manager.
#define azmErrNotFound (azmErrorClass | 12)
The rule-set being looked up was not found.
#define azmErrNotImplemented (azmErrorClass | 2)
The Authorization Manager attempted to perform an unimplemented operation.
#define azmErrNotOpen (azmErrorClass | 3)
The library has not been opened.
#define azmErrOutOfMemory (azmErrorClass | 7)
There is insufficient memory to complete the requested operation.
#define azmErrRestrictedAPI (azmErrorClass | 11)
This call can only be made from a registered manager.
#define azmErrStillOpen (azmErrorClass | 4)
The library is opened by others and cannot be closed.
#define azmErrTooManyTokensInRule (azmErrorClass | 14)
You have exceeded the limit on the number of tokens per rule.

Authorization Manager Functions and Macros ^TOP^

AzmAddRule Function ^TOP^

Purpose

Adds an access rule to an existing rule-set container for a specific action bitmap.

Declared In

azm.h

Prototype

status_t AzmAddRule (
   AzmRuleSetType ruleset,
   AzmActionType action,
   char *rulefmt,
   ...
)

Parameters

ruleset
A valid handle to a rule-set container managed by the Authorization Manager.
action
Bitmap of actions to apply these rules to.
rulefmt
A rule format string of the form: [%t]+ (OR [%t]*)?. This string should not exceed azmRuleFormatLength bytes in length.
...
A variable argument list containing a valid AmTokenType for each "%t" in the rule format string.

Returns

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

azmErrParam
The rule format string is invalid.
azmErrMemory
Out of memory, or the Authorization Manager detected an invalid internal memory structure.
azmErrInvalidReference
ruleset is invalid.
azmErrAuthorizationFailed
The modify rule-set rule was not authenticated properly.
azmErrTooManyTokensInRule
Your rule has too many tokens. A given rule cannot have more than azmMaxTokensInTree tokens.

Comments

The rule format string is in the canonical form "%t (OR %t)". That is, at least one "%t". This may be followed by " OR %t" to indicate the right hand side of the ACE rule. In the right hand side of the ACE rule there may be zero or more "%t" references.

There must be a valid AmTokenType in the variable argument list for each "%t" in the rule format string.

If the action referenced in the function call already has a rule associated with it, the rule is replaced. See "Schema Database Access Rule Action Types" of Exploring Palm OS: Memory, Databases, Files for the set of constants that correspond to those schema database actions for which you can set access rules. For an example of how to use this function to secure a schema database, see "Securing Databases."

Although this function is usually called by applications, it can be called from anywhere. However, in order for the call to succeed you must pass the rule-set container modify rule. To create a rule that allows access to anyone, use the well-known system token amEmptyToken and create a rule that only contains that token for the action you wish to allow free access to. For example,


AmGetTokenBySystemId(&token, "empty"); 
AzmAddRule(ruleSetRef, action, "%t",  token); 

AzmGetSyncBypass Function ^TOP^

Purpose

Get the state of the sync bypass flags.

Declared In

azm.h

Prototype

status_t AzmGetSyncBypass (
   AzmRuleSetType ruleset,
   uint32_t *statebitfield
)

Parameters

ruleset
A reference to the rule-set container for which the bypass settings are being requested.
statebitfield
A bitmap of the actions. If a bit is set for a specific action then its bypass flag is set.

Returns

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

azmErrInvalidReference
ruleset is invalid
azmErrBadParam
statebitfield is NULL.

Comments

Upon return *statebitfield contains a 1 for each state that has bypass enabled. Checking for a flag is easy. For instance, to see if sync bypass it set for ACTION_READ, simply do the following:


if ((stateBitField & ACTION_READ) > 0) 

Note that it is not possible to set a sync bypass for Authorization Manager actions such as ACTION_MODIFY.

See Also

AzmSetSyncBypass()

AzmNonInteractiveAuthorize Function ^TOP^

Purpose

Authorize an action given a rule-set reference.

Declared In

azm.h

Prototype

status_t AzmNonInteractiveAuthorize (
   AzmRuleSetType ruleSet,
   AzmActionType action,
   uint32_t appIdentityKeyId
)

Parameters

ruleSet
A valid handle to a rule-set container managed by the Authorization Manager.
action
A bitmap of the action to authorize. Only one action may be authorized.
appIdentityKeyId
The keyID for the application ID key that was passed in to the manager during the action request message.

Returns

errNone if the authorization request succeeds. Otherwise, this function returns one of the following:

azmErrInvalidReference
The reference to the Authorization Manager rule-set container is invalid.
azmErrParam
The action paarameter is empty. That is, it has a value of 0.
azmErrMemory
An internal memory error occurred.
azmErrAuthorizationFailed
Authorization failed.

Comments

The authorization function treats all interactive tokens as failed authentications (without calling the Authentication Manager for authentication), therefore the result is whether a non-interactive authorization succeeds. This means that the device won't bother the user while this function is in operation.

The rule-set container must have been created prior to calling this function.

AzmSetSyncBypass Function ^TOP^

Purpose

Set the state of the sync bypass flags.

Declared In

azm.h

Prototype

status_t AzmSetSyncBypass (
   AzmRuleSetType ruleset,
   AzmActionType action,
   Boolean state
)

Parameters

ruleset
A reference to the rule-set container for which the bypass settings are to be modified.
action
A bitmap of the actions. If a bit is set for a specific action then its bypass flag is set, otherwise it is cleared.
state
What state to set the relationship to: true corresponds to "allow sync," while false corresponds to "disallow sync."

Returns

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

AzmErrInvalidReference
ruleset is invalid.
AzmErrAuthorizationFailed
Authorization of the rule-set container modify rule failed. You must be the manager that created the rule-set.

Comments

Every rule-set can have a set of sync-bypass flags associated with it. These bypass flags can be enabled or disabled on a per-action basis.

When sync-bypass is enabled for a specific action, an authenticated sync agent will be able to complete that action successfully. (The sync-bypass rules takes care of authenticating sync agents). For example, if a data manager object (protected database) sets sync bypass for the READ action, a sync agent such as HotSync can access the contents of the database for READ only, thus enabling one-way sync.

Although this function can be called from anywhere, only callers that pass the ACTION_MODIFY rule will succeed in setting a bypass flag.

See Also

AzmGetSyncBypass()