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
AzmActionType Typedef
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
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 toAzmNotificationRuleSetDestroyed
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
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
Miscellaneous Authorization Manager Constants
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
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
AzmAddRule Function
Purpose
Adds an access rule to an existing rule-set container for a specific action bitmap.
Declared In
azm.h
Prototype
status_t AzmAddRule ( AzmRuleSetTyperuleset
, AzmActionTypeaction
, 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
Purpose
Get the state of the sync bypass flags.
Declared In
azm.h
Prototype
status_t AzmGetSyncBypass ( AzmRuleSetTyperuleset
, 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:
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
AzmNonInteractiveAuthorize Function
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
Purpose
Set the state of the sync bypass flags.
Declared In
azm.h
Prototype
status_t AzmSetSyncBypass ( AzmRuleSetTyperuleset
, AzmActionTypeaction
, Booleanstate
)
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," whilefalse
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.