gettcbattr or puttcbattr Subroutine

Purpose

Accesses the TCB information in the user database.

Library

Security Library (libc.a)

Syntax

#include <usersec.h>

int gettcbattr (Entry, Attribute, Value, Type) char * Entry; char * Attribute; void * Value; int Type;

int puttcbattr (Entry, Attribute, Value, Type)
char *Entry;
char *Attribute;
void *Value;
int Type;

Description

These subroutines access Trusted Computing Base (TCB) information.

The gettcbattr subroutine reads a specified attribute from the tcbck database. If the database is not already open, the subroutine will do an implicit open for reading.

Similarly, the puttcbattr subroutine writes a specified attribute into the tcbck database. If the database is not already open, the subroutine does an implicit open for reading and writing. Data changed by puttcbattr must be explicitly committed by calling the puttcbattr subroutine with a Type parameter specifying the SEC_COMMIT value. Until the data is committed, only get subroutine calls within the process will return the written data.

New entries in the tcbck databases must first be created by invoking puttcbattr with the SEC_NEW type.

The tcbck database usually defines all the files and programs that are part of the TCB, but the root user or a member of the security group can choose to define only those files considered to be security-relevant.

Parameters

Item	Description
Attribute	Specifies which attribute is read. The following possible values are defined in the sysck.h file: S_ACL The access control list for the file. Type: SEC_CHAR. S_CHECKSUM The checksum of the file. Type: SEC_CHAR. S_CLASS The logical group of the file. The attribute type is SEC_LIST. S_GROUP The file group. The attribute type is SEC_CHAR. S_LINKS The hard links to this file. Type: SEC_LIST. S_MODE The File mode. Type: SEC_CHAR. S_OWNER The file owner. Type: SEC_CHAR. S_PROGRAM The associated checking program for the file. Type: SEC_CHAR. S_SIZE The size of the file in bytes. Type: SEC_LONG. S_SOURCE The source for the file. Type: SEC_CHAR. S_SYMLINKS The symbolic links to the file. Type: SEC_LIST. S_TARGET The target file (if file is a symbolic link). Type: SEC_CHAR. S_TCB The Trusted Computer Base. The attribute type is SEC_BOOL. S_TYPE The type of file. The attribute type is SEC_CHAR. Additional user-defined attributes may be used and will be stored in the format specified by the Type parameter.
Entry	Specifies the name of the file for which an attribute is to be read or written.
Type	Specifies the type of attribute expected. Valid values are defined in the usersec.h file and include: SEC_BOOL A pointer to an integer (int ) that has been cast to a null pointer. SEC_CHAR* The format of the attribute is a null-terminated character string. SEC_LIST The format of the attribute is a series of concatenated strings, each null-terminated. The last string in the series is terminated by two successive null characters. SEC_LONG The format of the attribute is a 32-bit integer.
Value	Specifies the address of a pointer for the gettcbattr subroutine. The gettcbattr subroutine will return the address of a buffer in the pointer. For the puttcbattr subroutine, the Value parameter specifies the address of a buffer in which the attribute is stored. See the Type parameter for more details.

Security

Item	Description
Files Accessed:

Mode	File
rw	/etc/security/sysck.cfg (write access for puttcbattr)

Return Values

The gettcbattr and puttcbattr subroutines, when successfully completed, return a value of 0. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes

Note: These subroutines return errors from other subroutines.

These subroutines fail if the following is true:

Item	Description
EACCES	Access permission is denied for the data request.

The gettcbattr and puttcbattr subroutines fail if one or more of the following are true:

Item	Description
EINVAL	The Value parameter does not point to a valid buffer or to valid data for this type of attribute. Limited testing is possible and all errors may not be detected.
EINVAL	The Entry parameter is null or contains a pointer to a null string.
EINVAL	The Type parameter contains more than one of the SEC_BOOL, SEC_CHAR, SEC_LIST, or SEC_LONG attributes.
EINVAL	The Type parameter specifies that an individual attribute is to be committed, and the Entry parameter is null.
ENOENT	The specified Entry parameter does not exist or the attribute is not defined for this entry.
EPERM	Operation is not permitted.