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
SecSvcsDecodeLockoutTimePtrType Typedef
Purpose
Pointer to the SecSvcsDecodeLockoutTime()
function.
Declared In
SecurityServices.h
Prototype
typedef status_t (*SecSvcsDecodeLockoutTimePtrType) (uint32_tencoded_level
, SecSvcsDeviceLockoutEnum*lockoutType
, uint32_t*hours
, uint32_t*minutes
)
SecSvcsEncodeLockoutTimePtrType Typedef
Purpose
Pointer to the SecSvcsEncodeLockoutTime()
function.
Declared In
SecurityServices.h
Prototype
typedef status_t (*SecSvcsEncodeLockoutTimePtrType) (SecSvcsDeviceLockoutEnumlockoutType
, uint32_t*encoded_level
, uint32_thours
, uint32_tminutes
)
SecSvcsGetDeviceLockoutPtrType Typedef
Purpose
Pointer to the SecSvcsGetDeviceLockout()
function.
Declared In
SecurityServices.h
Prototype
typedef status_t
(*SecSvcsGetDeviceLockoutPtrType)
(uint32_t *encoded_level
)
SecSvcsGetDevicePoliciesPtrType Typedef
Purpose
Pointer to the SecSvcsGetDevicePolicies()
function.
Declared In
SecurityServices.h
Prototype
typedef status_t (*SecSvcsGetDevicePoliciesPtrType) (uint32_tcreatorID
, uint8_t*buffer
, uint32_t*buflen
)
SecSvcsGetDeviceSettingPtrType Typedef
Purpose
Pointer to the SecSvcsGetDeviceSetting()
function.
Declared In
SecurityServices.h
Prototype
typedef status_t
(*SecSvcsGetDeviceSettingPtrType)
(SecSvcsDeviceSettingEnum *level
)
SecSvcsIsDeviceLockedPtrType Typedef
Purpose
Pointer to the SecSvcsIsDeviceLocked()
function.
Declared In
SecurityServices.h
Prototype
typedef Boolean (*SecSvcsIsDeviceLockedPtrType) (void)
SecSvcsSetDeviceLockedPtrType Typedef
Purpose
Pointer to the SecSvcsSetDeviceLocked()
function.
Declared In
SecurityServices.h
Prototype
typedef status_t (*SecSvcsSetDeviceLockedPtrType)
(Boolean locked
)
SecSvcsSetDeviceLockoutPtrType Typedef
Purpose
Pointer to the SecSvcsSetDeviceLockout()
function.
Declared In
SecurityServices.h
Prototype
typedef status_t
(*SecSvcsSetDeviceLockoutPtrType)
(uint32_t encoded_level
)
SecSvcsSetDeviceSettingPtrType Typedef
Purpose
Pointer to the SecSvcsSetDeviceSetting()
function.
Declared In
SecurityServices.h
Prototype
typedef status_t
(*SecSvcsSetDeviceSettingPtrType)
(SecSvcsDeviceSettingEnum level
)
Security Services Constants
Security Services Entry Points
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
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
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
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
Purpose
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
SecSvcsDecodeLockoutTime Function
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_tencoded_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
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 Function
Purpose
Encodes the lockout parameters into a 32-bit value for use with SecSvcsSetDeviceLockout()
.
Declared In
SecurityServices.h
Prototype
status_t SecSvcsEncodeLockoutTime ( SecSvcsDeviceLockoutEnumlockoutType
, uint32_t*encoded_level
, uint32_thours
, uint32_tminutes
)
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
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
SecSvcsGetDeviceLockout Function
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
See Also
SecSvcsGetDevicePolicies Function
Purpose
Obtain the security policies defined for the device.
Declared In
SecurityServices.h
Prototype
status_t SecSvcsGetDevicePolicies ( uint32_tcreatorID
, 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 throughbuflen
). -
↔ 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
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
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
Purpose
Determine whether the device is currently in a locked state.
Declared In
SecurityServices.h
Prototype
Boolean SecSvcsIsDeviceLocked ( void )
Parameters
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
Purpose
Declared In
SecurityServices.h
Prototype
status_t SecSvcsSetDeviceLocked (
Boolean locked
)
Parameters
Returns
- Returns
errNone
if the operation completed successfully, orsecSvcsErrServiceNotStarted
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
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
SecSvcsSetDeviceSetting Function
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.