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

14    Security Services

Security and Cryptography

Exploring Palm OS

The Security Services manage the device settings regarding the user's level of concern for security. This includes the overall security level set for the device as well as the device lockout settings.

This chapter provides reference documentation for the Security Services. It is organized into the following sections:

Security Services Structures and Types
Security Services Constants
Security Services Functions and Macros

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

Security Services Structures and Types ^TOP^

SecSvcsDecodeLockoutTimePtrType Typedef ^TOP^

Purpose

Pointer to the SecSvcsDecodeLockoutTime() function.

Declared In

SecurityServices.h

Prototype

typedef status_t


   (*SecSvcsDecodeLockoutTimePtrType)


   (uint32_t encoded_level,


   SecSvcsDeviceLockoutEnum *lockoutType,


   uint32_t *hours, uint32_t *minutes)


SecSvcsEncodeLockoutTimePtrType Typedef ^TOP^

Purpose

Pointer to the SecSvcsEncodeLockoutTime() function.

Declared In

SecurityServices.h

Prototype

typedef status_t


   (*SecSvcsEncodeLockoutTimePtrType)


   (SecSvcsDeviceLockoutEnum lockoutType,


   uint32_t *encoded_level, uint32_t hours,


   uint32_t minutes)


SecSvcsGetDeviceLockoutPtrType Typedef ^TOP^

Purpose

Pointer to the SecSvcsGetDeviceLockout() function.

Declared In

SecurityServices.h

Prototype

typedef status_t


   (*SecSvcsGetDeviceLockoutPtrType)


   (uint32_t *encoded_level)


SecSvcsGetDevicePoliciesPtrType Typedef ^TOP^

Purpose

Pointer to the SecSvcsGetDevicePolicies() function.

Declared In

SecurityServices.h

Prototype

typedef status_t


   (*SecSvcsGetDevicePoliciesPtrType)


   (uint32_t creatorID, uint8_t *buffer,


   uint32_t *buflen)


SecSvcsGetDeviceSettingPtrType Typedef ^TOP^

Purpose

Pointer to the SecSvcsGetDeviceSetting() function.

Declared In

SecurityServices.h

Prototype

typedef status_t


   (*SecSvcsGetDeviceSettingPtrType)


   (SecSvcsDeviceSettingEnum *level)


SecSvcsIsDeviceLockedPtrType Typedef ^TOP^

Purpose

Pointer to the SecSvcsIsDeviceLocked() function.

Declared In

SecurityServices.h

Prototype

typedef Boolean (*SecSvcsIsDeviceLockedPtrType)


   (void)


SecSvcsSetDeviceLockedPtrType Typedef ^TOP^

Purpose

Pointer to the SecSvcsSetDeviceLocked() function.

Declared In

SecurityServices.h

Prototype

typedef status_t (*SecSvcsSetDeviceLockedPtrType)


   (Boolean locked)


SecSvcsSetDeviceLockoutPtrType Typedef ^TOP^

Purpose

Pointer to the SecSvcsSetDeviceLockout() function.

Declared In

SecurityServices.h

Prototype

typedef status_t


   (*SecSvcsSetDeviceLockoutPtrType)


   (uint32_t encoded_level)


SecSvcsSetDeviceSettingPtrType Typedef ^TOP^

Purpose

Pointer to the SecSvcsSetDeviceSetting() function.

Declared In

SecurityServices.h

Prototype

typedef status_t


   (*SecSvcsSetDeviceSettingPtrType)


   (SecSvcsDeviceSettingEnum level)


Security Services Constants ^TOP^

Security Services Entry Points ^TOP^

Purpose

Each of the Security Services functions is identified by its entry point. These constants define those entry points.

Declared In

SecurityServices.h

Constants

#define entryNumSecSvcsDecodeLockoutTime (6)
#define entryNumSecSvcsEncodeLockoutTime (5)
#define entryNumSecSvcsGetDeviceLockout (3)
#define entryNumSecSvcsGetDevicePolicies (0)
#define entryNumSecSvcsGetDeviceSetting (1)
#define entryNumSecSvcsSetDeviceLockout (4)
#define entryNumSecSvcsSetDeviceSetting (2)

Security Services Errors ^TOP^

Purpose

Error codes returned by the various Security Services functions.

Declared In

SignVfy.h

Constants

#define secSvcsErrBufferTooSmall ((status_t)(secSvcsErrorClass | 2))
The supplied buffer was too small. The required size has been returned through the length parameter.
#define secSvcsErrInvalid ((status_t)(secSvcsErrorClass | 7))
The specified security level or lockout type isn't one of the allowable values.
#define secSvcsErrNoPolicies ((status_t)(secSvcsErrorClass | 3))
The licensee has not specified any policies for the device.
#define secSvcsErrNotImplemented ((status_t)(secSvcsErrorClass | 1))
A requested service is not implemented.
#define secSvcsErrOutOfMemory ((status_t)(secSvcsErrorClass | 5))
There was insufficient memory to complete the operation.
#define secSvcsErrServiceNotStarted ((status_t)(secSvcsErrorClass | 6))
The Security Services process has not started.
#define secSvcsErrUnauthorized ((status_t)(secSvcsErrorClass | 4))
The caller is not authorized to perform the requested operation.

Miscellaneous Security Services Constants ^TOP^

Purpose

The SecurityServices.h header file also declares these constants.

Declared In

SecurityServices.h

Constants

#define SecSvcsServiceName "pSysSecSvcs"
The name under which the Security Services are registered with the Service Manager.

SecSvcsDeviceLockoutEnum Enum ^TOP^

Purpose

"Lockout type" values that specify when the device will be automatically locked by the operating system.

Declared In

SecurityServices.h

Constants

SecSvcsDeviceLockoutNever = 0
The device never locks.
SecSvcsDeviceLockoutPowerOff
The device locks upon power off.
SecSvcsDeviceLockoutAt
The device is locked at the specified time.
SecSvcsDeviceLockoutAfter
The device is locked after the specified amount of time has elapsed.

SecSvcsDeviceSettingEnum Enum ^TOP^

Purpose

The user's "paranoia level."

Declared In

SecurityServices.h

Constants

SecSvcsDeviceSecurityNone = 0
No security needed: the device and services should be as open as possible.
SecSvcsDeviceSecurityMedium
The user would like to be notified whenever security-related operations take place, and where appropriate given the opportunity to veto the operation.
SecSvcsDeviceSecurityHigh
The user is extremely security-conscious and likely wants all security-related operations denied.

Security Services Functions and Macros ^TOP^

SecSvcsDecodeLockoutTime Function ^TOP^

Purpose

Decodes the 32-bit encoded_level value obtained from SecSvcsGetDeviceLockout() into a set of lockout parameters (lockoutType, hours, and minutes).

Declared In

SecurityServices.h

Prototype

status_t SecSvcsDecodeLockoutTime   (
   uint32_t encoded_level,
      SecSvcsDeviceLockoutEnum *lockoutType,
      uint32_t *hours,
   uint32_t *minutes
)

Parameters

encoded_level
The encoded lockout parameters.
lockoutType
One of the SecSvcsDeviceLockoutEnum values that specifies when the device will be locked.
hours
In conjunction with minutes, the time when the device will lock or the amount of time that must elapse before the device will lock. See the Comments section, below, for more information.
minutes
In conjunction with hours, the time when the device will lock or the amount of time that must elapse before the device will lock. See the Comments section, below, for more information.

Returns

Always returns errNone.

Comments

If the lockout type is SecSvcsDeviceLockoutAt, the device will lock at the time specified by hours and minutes. If the lockout type is SecSvcsDeviceLockoutAfter, the device will lock after the specified number of hours and minutes have elapsed.

See Also

SecSvcsEncodeLockoutTime()

SecSvcsEncodeLockoutTime Function ^TOP^

Purpose

Encodes the lockout parameters into a 32-bit value for use with SecSvcsSetDeviceLockout().

Declared In

SecurityServices.h

Prototype

status_t SecSvcsEncodeLockoutTime   (
   SecSvcsDeviceLockoutEnum lockoutType,
      uint32_t *encoded_level,
   uint32_t hours,
      uint32_t minutes
)

Parameters

lockoutType
One of the SecSvcsDeviceLockoutEnum values that specifies when the device will be locked.
encoded_level
The encoded lockout parameters.
hours
In conjunction with minutes, the time when the device will lock or the amount of time that must elapse before the device will lock. See the Comments section, below, for more information.
minutes
In conjunction with hours, the time when the device will lock or the amount of time that must elapse before the device will lock. See the Comments section, below, for more information.

Returns

Always returns errNone.

Comments

If the lockout type is SecSvcsDeviceLockoutAt, the device will lock at the time specified by hours and minutes. If the lockout type is SecSvcsDeviceLockoutAfter, the device will lock after the specified number of hours and minutes have elapsed.

See Also

SecSvcsDecodeLockoutTime()

SecSvcsGetDeviceLockout Function ^TOP^

Purpose

Gets the lockout parameters as currently set for the device.

Declared In

SecurityServices.h

Prototype

status_t SecSvcsGetDeviceLockout   (
   uint32_t *encoded_level
)

Parameters

encoded_level
The lockout parameters. These are encoded to save space and must be decoded using SecSvcsDecodeLockoutTime().

Returns

Always returns errNone.

See Also

SecSvcsSetDeviceLockout()

SecSvcsGetDevicePolicies Function ^TOP^

Purpose

Obtain the security policies defined for the device.

Declared In

SecurityServices.h

Prototype

status_t SecSvcsGetDevicePolicies   (
   uint32_t creatorID,
   uint8_t *buffer,
      uint32_t *buflen
)

Parameters

creatorID
Specifies the particular policies being requested. Note that this is not specifically related to actual creator ID values but rather agreed-upon and documented names. In this way a manager can utilize multiple sets of policies.
buffer
A caller-allocated buffer that will receive the requested policies, or NULL to request the necessary buffer size (which is then returned through buflen).
buflen
When calling this function, this is the size of buffer. Upon return it is set to the total size of the returned policies.

Returns

Returns errNone if the operation completed successfully, secSvcsErrNoPolicies if the device has no policies, or one of the following otherwise:

secSvcsErrBufferTooSmall
The specified buffer is too small to contain the security policies. *buflen has been set to the needed buffer size.

Comments

Upon calling this function, you can expect one of three "valid" returns:

  • No policies returned (secSvcsErrNoPolicies). The licensee has not specified any policies and the service or manager should behave openly (that is, with no restrictions).
  • A multiple of 20 bytes is returned, with each 20 byte boundary representing a valid certificate ID.
  • One 20 byte wildcard certificate is returned. A wildcard certificate represents a slightly higher level of security than the totally open device. The wildcard means that the service or manager will check to see if the code is signed by a signer already in the list of trusted roots. If the code is signed by one of the trusted roots, then allow the operation. If the code is not signed by one of the trusted roots or not signed at all then annoy the user with as much information about the code as possible (not signed, signed by whom, etc.) and ask the user if the code should be applied.

SecSvcsGetDeviceSetting Function ^TOP^

Purpose

Obtain the current security services setting.

Declared In

SecurityServices.h

Prototype

status_t SecSvcsGetDeviceSetting   (
   SecSvcsDeviceSettingEnum *level
)

Parameters

level
One of the SecSvcsDeviceSettingEnum values.

Returns

Always returns errNone.

Comments

Generally, for SecSvcsDeviceSecurityNone the user does not care and the device and services should be as open as possible. For SecSvcsDeviceSecurityMedium the user is requesting notification for operations performed by various services, perhaps a yes/no dialog before the operation takes place. For SecSvcsDeviceSecurityHigh the user is "paranoid" and probably wants the operations denied

See Also

SecSvcsGetDevicePolicies(), SecSvcsIsDeviceLocked(), SecSvcsSetDeviceSetting()

SecSvcsIsDeviceLocked Function ^TOP^

Purpose

Determine whether the device is currently in a locked state.

Declared In

SecurityServices.h

Prototype

Boolean SecSvcsIsDeviceLocked (
   void
)

Parameters

None.

Returns

Returns true if the device is locked, false if it is not.

Comments

This function is intended to be used for low-level modules that control whether or not the device is locked.

See Also

SecSvcsGetDeviceLockout(), SecSvcsSetDeviceLocked()

SecSvcsSetDeviceLocked Function ^TOP^

Purpose

Lock or unlock the device.

Declared In

SecurityServices.h

Prototype

status_t SecSvcsSetDeviceLocked (
   Boolean locked
)

Parameters

locked
Supply a value of true to lock the device, or false to unlock it.

Returns

Returns errNone if the operation completed successfully, or secSvcsErrServiceNotStarted if the Security Services process has not started.

Comments

This function is intended to be used for low-level modules that control whether or not the device is locked.

See Also

SecSvcsIsDeviceLocked(), SecSvcsSetDeviceLockout()

SecSvcsSetDeviceLockout Function ^TOP^

Purpose

Sets the current lockout parameters for the device.

Declared In

SecurityServices.h

Prototype

status_t SecSvcsSetDeviceLockout   (
   uint32_t encoded_level
)

Parameters

encoded_level
The lockout parameters. These must have been encoded using SecSvcsEncodeLockoutTime().

Returns

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

amErrUserCancel
The user canceled the operation.
secSvcsErrInvalid
The specified lockout type isn't one of the allowable values.
secSvcsErrServiceNotStarted
The Security Services process has not started.

Comments


IMPORTANT: When called from the main application thread, this function may block. While blocked, the application will not receive events and won't redraw its windows. As well, deferred sublaunches and notifications won't execute while the main application thread is blocked.

See Also

SecSvcsGetDeviceLockout()

SecSvcsSetDeviceSetting Function ^TOP^

Purpose

Change the current security services setting.

Declared In

SecurityServices.h

Prototype

status_t SecSvcsSetDeviceSetting   (
   SecSvcsDeviceSettingEnum level
)

Parameters

level
One of the SecSvcsDeviceSettingEnum values.

Returns

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

amErrUserCancel
The user canceled the operation.
secSvcsErrInvalid
The specified level isn't one of the allowable values.

Comments


IMPORTANT: When called from the main application thread, this function may block. While blocked, the application will not receive events and won't redraw its windows. As well, deferred sublaunches and notifications won't execute while the main application thread is blocked.

See Also

SecSvcsGetDeviceSetting()