NC Registry Software Functional Specification

Contents.

1.0 Overview

The NC Registry provides a consistent interface to client applications which need to access this data, and performs simple access control on smartcard files. In addition, the registry correlates available network interfaces with corresponding bootblocks on the smartcard and selects the most likely network interface for the user session based on inferences made from this data.

The NC Registry maintains at most two active bootblocks at any one time; one which is derived from a valid smartcard (the smartcard bootblock ), and one which may be loaded across a network from a central server (the network bootblock ).. This allows network-wide initialization of global NC parameters to be performed as part of the normal boot process, while ensuring that user specific details are still read from a valid smartcard. Network bootblocks may not be updated by the NC.

The format of bootblocks stored on NC smartcards was revised and extended in December 1996. Smartcard bootblocks carry version information which identifies their format: the NC Registry will operate with both the current and previous bootblock formats.

The user and programmer interfaces for this registry version are broadly compatible with the previous version, the difference being some added functionality.

Additional status bits have been added to status words to indicate bootblock failure due to version issues (ie 'too old' and 'too new' flags).

Registry enquiries return additional status information concerning the bootblock entry (the entry tags, plus an indication of whether the tag is a soft mapping or not).

New SWIs have been added to allow the creation, editing, and removal of soft tag mappings. Soft tag mappings will be written in the same way as other bootblock tags, ie they will only exist on the smartcard after a write-through operation, but will become active immediately.

Releases of the registry carry two major version numbers and one minor version number. The two major version numbers will provide the current major version, and the minimum backwards-compatible version. This is provided so that obsolete bootblock interpreter code may be phased out of future registry releases.

Major version numbers will be used for significant upheavals in the format. A version of the registry will be able to interpret all bootblocks with lesser major version numbers, provided the major version number is greater than or equal to the registry's minimum backwards-compatibility version. If bootblocks are encountered with a higher major version number than the executing registry module, the bootblock will be marked invalid.

A registry implementation will operate with a lower minor version bootblock, provided that there is sufficient information in the bootblock for the registry to meet its mandatory tag requirements. Failure to do so will result in the bootblock being considered invalid for the current session.

If the bootblock minor version is less than or equal to the current registry minor version, unrecognised tag ids will cause the bootblock to be considered invalid for the current session.

A registry implementation will operate with a higher minor version bootblock, provided that its mandatory tag requirements can be met. In this case, unrecognized tag ids in the bootblock will be ignored by the registry - it will merely track them for storage reasons, but will not attempt to interpret them.

2.0 Outstanding issues

Parts of this specification which are italicised like this are either undecided issues or are liable to change.

3.0 Technical background

The NC Registry also co-exists with current network boot protocols such as BOOTP and DHCP, and allows selected fields in a smartcard boot block to be overridden by a network server.

Because of these factors and others such as the need to provide authentication and arbitration between multiple network interfaces and multiple smartcard bootblocks, a standard RISC OS filing system interface would be impractical.

4.0 User interface

The following CLI commands will exist in the NC Registry:

5.0 Programmer interface

NCRegistry_EnumerateNetworkDrivers (0x4d380)

On entry:

On exit:

where "network driver information " is a pointer to a linked list of the following format:

typedef struct mydiblist {

  unsigned int flags;     /* flag bits - see below */
  dci4_dib *dib_ptr;      /* pointer to a DCI4 compliant driver information block */
  struct mydiblist *next; /* next entry, or NULL for end of list */
} mydci4_diblist;

#define DIB_FLAG_PRIMARY 0x1   /* this is the primary interface as far as the registry is concerned */
#define DIB_FLAG_STATS   0x2   /* device driver supports statistics */
#define DIB_FLAG_STATUS  0x4   /* interface is working OK */
#define DIB_FLAG_UP      0x8   /* interface is UP */
#define DIB_FLAG_PTP     0x10  /* interface is point2point */
#define DIB_FLAG_SCOK    0x20  /* interface is supported by a smartcard boot block */
#define DIB_FLAG_IGNORE  0x40  /* Registry discarded this interface during nic selection */

NCRegistry_Enquiry (0x4d382)

On entry:

On exit:

The requested tag is returned to the buffer if there is sufficient room for it.

'Tag string' means one of the 'Name' parameters from the table in section 1.0 of NC smartcard boot block contents. If the registry is unable to find this tag name in its list of hard tag mappings, it will pursue it in any soft mappings which may have been loaded from the bootblock.

The tag flags word denotes the type of tag returned in the least significant nibble, and various other flags in other bit positions.

Bits	Meaning
0-3	Tag type
4	Updateable
5	Overrideable
6	Mandatory

Nibble	Tag type
0x0	No such tag
0x1	Hard tag
0x2	Soft tag
0x3	Special tag

Returned values are either character strings, integers, pair of integers (for proxy info), or send/expect lists for the ISP_SCRIPT parameter. Client applications are expected to know the format of their requested tags. System flags can either be fetched in word wide quantities, eg by requesting the tag SYSTEM_FLAGS1, or single flags may be fetched by using their unique name, eg LINK_AUTH. Single flags are shifted down to occupy the least significant bits of the returned word, ie LINK_AUTH will appear in the least significant byte of the returned value, and so will USER_PREFS when requested. Requesting the tag ISP_SCRIPT returns a pointer to a linked list of the following format:

typedef struct script_script_list {
  unsigned int cntrl;
  char *string;
  struct script_script_list *next;
} SCRIPT_LIST;

        0x1 - this is an expect string
        0x2 - this is a send string
        0x3 - this is a pause command
        0x4 - read back IP address from standard input

The next most significant byte of cntrl contains a timeout for that command in seconds. The list is terminated by a NULL value for 'next'. Note that the list is not guaranteed to adhere to any particular sequence: there is no fixed send/expect order.

The ISP_SCRIPT field is pre-interpreted by the script support module to take account of conditionals in the script.

Negative values returned in r0 from this SWI indicate an error condition. The possible error conditions are:

Return code	Error condition
-1	No such tag
-2	No support module for requested tag
-3	No tag info available
-4	Insufficient buffer space
-5	Invalid or absent smartcard
-6	Couldn't claim workspace
-7	Couldn't read ancillary tag
-8	Support SWI failed
-9	Bad source selector
-10	Decompression error
-11	Requested operation not supported

NCRegistry_LoadSmartCardBlock (0x4d383)

On entry:

On exit:

This call allows a boot block to be loaded into the NC Registry's network boot block area. The network boot block will in certain instances override the values in a smartcard boot block when a tag is requested from the Registry. This allows a network boot server to perform system wide configuration of its NCs, whilst some parameters remain unique to the user and are derived from the user's smartcard.

This SWI also allows the smartcard bootblock to be updated from a suitable MIME object as detected by the NC Browser.

NCRegistry_Status (0x4d384)

On entry:

On exit:

Bits in the two status words are set as follows:

#define BB_STATUS_INSERTED      0x1    /* bootblock present */
#define BB_STATUS_SC_VALID      0x2    /* smartcard validated by smartcard transport layer */
#define BB_STATUS_BB_VALID      0x4    /* smartcard boot block validated by registry */
#define BB_STATUS_PIN           0x8    /* smartcard is PIN protected */
#define BB_STATUS_LOCKED        0x10   /* smartcard is currently locked */
#define BB_STATUS_WRITEOK       0x20   /* last physical write to smartcard succeeded */
#define BB_STATUS_WRITEFAIL     0x40   /* last physical write to smartcard failed */
#define BB_STATUS_CLIENT	0x80   /* the current bootblock is client updateable */
#define BB_STATUS_AUTHFAIL      0x100  /* the last authentication procedure failed */
#define BB_STATUS_TOOOLD	0x200  /* the bootblock format is of too old a version to be interpreted */
#define BB_STATUS_TOONEW	0x400  /* the bootblock format is of too new a version to be interpreted */

The two delta_status words indicate which bits in the corresponding status words have changed since the last time NCRegistry_Status was called. Note that this is independent of the delta_status words broadcast via the service call. You should not rely on the delta_status words to detect bits which have changed since the last time you were called - NCRegistry_Status may have been called by another application in the interim.

In addition the Registry issues service call 0xba with:

r2 = smartcard boot block status
r3 = network boot block status
r4 = smartcard delta_status
r5 = network delta_status

Here, the delta_status words indicate which bits have changed in the corresponding status words since the last time the service call was issued. For the network boot block, BB_STATUS_INSERTED and BB_STATUS_SC_VALID are set when a valid network boot block is loaded across the network. BB_STATUS_BB_VALID is set when the registry has had a chance to examine the contents of the file and confirm its validity. All bits are reset to zero when a valid smartcard is removed. BB_STATUS_PIN is set if the current bootblock file is protected by a CHV (card holder verification) key. BB_STATUS_LOCKED is set for a bootblock file which is CHV protected and which has not yet been unlocked. BB_STATUS_CLIENT indicates whether the bootblock parameters should be updateable by client software.

Service call delta_status words indicate which bits have changed since the last service call was issued. An application should not rely on the delta_status words to detect which bits have changed since the last service call received, since it may have missed a service call in the intervening period.

When a smartcard is removed from the NC the smartcard status word is reset to zero and the delta_status word is set to 0xffffffff to indicate a status reset.

NCRegistry_Write (0x4d385)

On entry:

On exit:

This call allows a tag in the current smartcard boot block to be updated. Calling this SWI with a tag value causes the registry soft copy of the boot block to be updated - you must call this SWI with r0=r1=r2=0 to write through to the smartcard.

The tag flags word returned in r0 is the same os that for NCRegistry_Read.

Soft-writes return immediately, indicating 0 for success or one of the following error values:

Error	Meaning
-1	no such tag
-2	tag not updateable
-3	new tag value too big
-4	boot block not writeable
-5	invalid smartcard
-6	nothing to write
-7	registry busy
-8	no support module for requested tag
-9	no tag info available
-10	parent tag does not exist
-11	requested operation not supported

Write-throughs return a status immediately, which indicates the status of the write request itself, not of the completed write operation. Write success/failure is returned asynchronously to the registry, which in turn notifies client applications by setting the relevant status bits and issuing a service call. Clients which need to know whether the data was successfully written or not must wait for the service call or poll on an NCRegistry_Status call. Immediately returned values are 0 for success or a negative error value.

Upon receipt of 'registry busy' response the client application should timeout and retry later.

As with NCRegistry_Enquiry, system flags words can either be set in their entirety, or single bits may be set by using the appropriate tag name. In the latter case, only the least significant bit of the value in the buffer is used to set the flag value.

The NCFresco data block is a special case. When this is written, the registry alters its softcopy. When a write-through is requested for this data, the registry compresses the data and attempts to write it to the card. If the compressed data exceeds the available smartcard storage space for this file, error -3 (tag value too big) is returned. This tag is intended for internal use by the NC Browser only.

NCRegistry_Authenticate (0x4d386)

On entry:

On exit:

This SWI allows client applications to authenitate themselves to the smartcard. The authentication key is a maximum of 8 bytes. If a bigger key is provided, it will be truncated to 8 bytes. It is only necessary to authenticate in this way once per smartcard insertion. The Registry remembers the authentication key and uses it on all subsequent read, write, CHV change and registry proxy requests. When a new smartcard is inserted, the registry performs the following actions:

• Read the index file - this should always succeed since the index file is never read protected. If the Registry is unable to read this file due to a read error or an authentication error then it rejects the card as invalid.
• Check PIN status - if the card is PIN protected, the Registry will pause pending a CHV1 PIN notification from higher level software. On receipt of a PIN, the registry will resume.
• Consolidate network interfaces with available bootblock files and select the most likely bootblock file from those available on the smartcard.
• Read the relevant bootblock file. If an incorrect CHV1 PIN has been entered the registry will fail at this point, since it has no authority to read the file. Higher level applications should note this and prompt the user to re-enter the PIN.
• Upon receipt of valid authentication information, the registry will resume reading the bootblock file if it is present, or it will proceed immediately to the next stage.
• Extract, decompress, and interpret the ISP_SCRIPT field, generating associated special tags in the process.

NCRegistry_SupportInit (0x4d387)

On entry:

On exit:

NCRegistry_SupportExit (0x4d388)

On entry:

On exit:

NCRegistry_ChangeSmartCardCHV (0x4d389)

On entry:

On exit:

NCRegistry_Proxy (0x4d38a)

On entry:

On Exit:

This SWI allows higher level applications to perform an SCInterface_Read on a CHV1 PIN protected smartcard bootblock without having to know the user's PIN itself. This call uses the Registry's cached version of the CHV1 PIN to perform an SCInterface_Read SWI, therefore it will only succeed if a valid PIN has been entered.

NCRegistry_Delete (0x4d38b)

On entry:

On Exit:

This SWI allows the deletion of a tag from a registry bootblock. The tag must be updateable in order to be deletable. The tag flags word returned in r3 is the same as for NCRegistry_Read. Error values returned in r0 are the same as for NCRegistry_Write.

NCRegistry_Create (0x4d38d)

On entry:

On Exit:

This SWI creates a soft tag in a registry bootblock. If the tag already exists, its contents are updated. The tag flags word returned in r3 is the same as for NCRegistry_Read. Error values returned in r0 are the same as for NCRegistry_Write.

6.0 Data interchange

All registry clients exchange data with the registry throught the NCRegistry_ SWIs exclusively.

The NC Registry may exchange data with separate registry support modules using a SWI interface. These SWIs are not intended to be called by any process other than the NC Registry module. Currently the only support module is the NC Registry Scripting Support module which implements the following SWIs:

NCRegistryScript_Init (0x4d3c0)

NCRegistryScript_SpecialTag (0x4d3c1)

7.0 Data formats

Network Driver Information list

typedef struct mydiblist {

  unsigned int flags;     /* flag bits - see below */
  dci4_dib *dib_ptr;      /* pointer to a DCI4 compliant driver information block */
  struct mydiblist *next; /* next entry, or NULL for end of list */
} mydci4_diblist;

#define DIB_FLAG_PRIMARY 0x1   /* this is the primary interface as far as the registry is concerned */
#define DIB_FLAG_STATS   0x2   /* device driver supports statistics */
#define DIB_FLAG_STATUS  0x4   /* interface is working OK */
#define DIB_FLAG_UP      0x8   /* interface is UP */
#define DIB_FLAG_PTP     0x10  /* interface is point2point */
#define DIB_FLAG_SCOK    0x20  /* interface is supported by a smartcard boot block */
#define DIB_FLAG_IGNORE  0x40  /* Registry discarded this interface during nic selection */

Interpreted ISP script list

typedef struct script_script_list {
  unsigned int cntrl;
  char *string;
  struct script_script_list *next;
} SCRIPT_LIST;

        0x1 - this is an expect string
        0x2 - this is a send string
        0x3 - this is a pause command
        0x4 - read back IP address from standard input

8.0 External dependencies

External dependencies are:

• Various smartcard related modules.
• Availability of correctly formatted and minted smartcards.

9.0 Acceptance test

The software will be deemed acceptable if it successfully meets the criteria listed in section 9.0 Development test strategy.

10.0 Non compliances

11.0 Development test strategy

Test harnesses have been written to exercise all SWIs provided by the NCRegistry in as many permutations as possible:

• repeatedly create, alter, read and destroy all hard tags
• repeatedly create, alter, read and destroy various soft tags
• test with bootblocks of various sizes
• test with old and new format bootblocks
• test with bootblocks in various authorisation states
• test with invalid bootblocks

12.0 Product organisation

13.0 Future enhancements

It has been proposed that the NC Registry may manage a portion of the NC's non-volatile RAM, treating it as a persistent bootblock where machine dependent settings may be stored. This functionality is still in the design stage.

14.0 Glossary

15.0 References

Standards as follows:

[RFC951]

W.Croft & J.Gilmore, "Bootstrap Protocol (BOOTP)", Stanford University & Sun Microsystems, September 1985.

[RFC1533]

S.Alexander, "DHCP Options and BOOTP Vendor Extensions", Bucknell University, October 1993.

[RFC1541]

R.Droms, "Dynamic Host Configuration Protocol", Bucknell University, October 1993.

16.0 History