nis_objects(3NSL) Networking Services Library Functions nis_objects(3NSL)NAMEnis_objects - NIS+ object formats
SYNOPSIS
cc [ flag ... ] file ... -lnsl [ library ... ]
/usr/include/rpcsvc/nis_objects.x
DESCRIPTION
Common Attributes
The NIS+ service uses a variant record structure to hold the contents
of the objects that are used by the NIS+ service. These objects all
share a common structure that defines a set of attributes that all
objects possess. The nis_object structure contains the following mem‐
bers:
typedef char *nis_name;
struct nis_object {
nis_oid zo_oid;
nis_name zo_name;
nis_name zo_owner;
nis_name zo_group;
nis_name zo_domain;
uint_t zo_access;
uint32_t zo_ttl;
objdata zo_data;
};
In this structure, the first member zo_oid, is a 64 bit number that
uniquely identifies this instance of the object on this server. This
member is filled in by the server when the object is created and
changed by the server when the object is modified. When used in con‐
junction with the object's name and domain it uniquely identifies the
object in the entire NIS+ namespace.
The second member, zo_name, contains the leaf name of the object. This
name is never terminated with a `.' (dot). When an object is created
or added to the namespace, the client library will automatically fill
in this field and the domain name from the name that was passed to the
function.
zo_domain contains the name of the NIS+ domain to which this object
belongs. This information is useful when tracking the parentage of an
object from a cache. When used in conjunction with the members zo_name
and zo_oid, it uniquely identifies an object. This makes it possible
to always reconstruct the name of an object by using the code fragment
sprintf(buf,"%s.%s", obj->zo_name, obj->zo_domain);
The zo_owner and zo_group members contain the NIS+ names of the
object's principal owner and group owner, respectively. Both names must
be NIS+ fully qualified names. However, neither name can be used
directly to identify the object they represent. This stems from the
condition that NIS+ uses itself to store information that it exports.
The zo_owner member contains a fully qualified NIS+ name of the form
principal.domain. This name is called a NIS+ principal name and is used
to identify authentication information in a credential table. When the
server constructs a search query of the form
[cname=principal],cred.org_dir.domain.
The query will return to the server credential information about prin‐
cipal for all flavors of RPC authentication that are in use by that
principal. When an RPC request is made to the server, the authentica‐
tion flavor is extracted from the request and is used to find out the
NIS+ principal name of the client. For example, if the client is using
the AUTH_DES authentication flavor, it will include in the authentica‐
tion credentials the network name or netname of the user making the
request. This netname will be of the form
unix.UID@domain
The NIS+ server will then construct a query on the credential database
of the form
[auth_name=netname,auth_type=AUTH_DES],cred.org_dir.domain.
This query will return an entry which contains a principal name in the
first column. This NIS+ principal name is used to control access to
NIS+ objects.
The group owner for the object is treated differently. The group owner
member is optional (it should be the null string if not present) but
must be fully qualified if present. A group name takes the form
group.domain.
which the server then maps into a name of the form
group.groups_dir.domain.
The purpose of this mapping is to prevent NIS+ group names from con‐
flicting with user specified domain or table names. For example, if a
domain was called engineering.foo.com., then without the mapping a NIS+
group of the same name to represent members of engineering would not be
possible. The contents of groups are lists of NIS+ principal names
which are used exactly like the zo_owner name in the object. See
nis_groups(3NSL) for more details.
The zo_access member contains the bitmask of access rights assigned to
this object. There are four access rights defined, and four are
reserved for future use and must be zero. This group of 8 access rights
can be granted to four categories of client. These categories are the
object's owner, the object's group owner, all authenticated clients
(world), and all unauthenticated clients (nobody). Note that access
granted to ``nobody'' is really access granted to everyone, authenti‐
cated and unauthenticated clients.
The zo_ttl member contains the number of seconds that the object can
``live'' in a cache before it is expired. This value is called the time
to live for this object. This number is particularly important on group
and directory (domain) objects. When an object is cached, the current
time is added to the value in zo_ttl. Then each time the cached object
is used, the time in zo_ttl is compared with the current time. If the
current time is later than the time in zo_ttl the object is said to
have expired and the cached copy should not be used.
Setting the TTL is somewhat of an art. You can think of it as the
``half life'' of the object, or half the amount of time you believe
will pass before the object changes. The benefit of setting the ttl to
a large number is that the object will stay in a cache for long periods
of time. The problem with setting it to a large value is that when the
object changes it will take a long time for the caches to flush out old
copies of that object. The problems and benefits are reversed for set‐
ting the time to a small value. Generally setting the value to 43200
(12 hrs) is reasonable for things that change day to day, and 3024000
is good for things that change week to week. Setting the value to 0
will prevent the object from ever being cached since it would expire
immediately.
The zo_data member is a discriminated union with the following members:
zotypes zo_type;
union {
struct directory_obj di_data;
struct group_obj gr_data;
struct table_obj ta_data;
struct entry_obj en_data;
struct link_obj li_data;
struct {
uint_t po_data_len;
char *po_data_val;
} po_data;
} objdata_u;
The union is discriminated based on the type value contained in
zo_type. There six types of objects currently defined in the NIS+ ser‐
vice. These types are the directory, link, group, table, entry, and
private types.
enum zotypes {
BOGUS_OBJ = 0,
NO_OBJ = 1,
DIRECTORY_OBJ = 2,
GROUP_OBJ = 3,
TABLE_OBJ = 4,
ENTRY_OBJ = 5,
LINK_OBJ = 6,
PRIVATE_OBJ = 7
};
typedef enum zotypes zotypes;
All object types define a structure that contains data specific to
that type of object. The simplest are private objects which are defined
to contain a variable length array of octets. Only the owner of the
object is expected to understand the contents of a private object. The
following section describe the other five object types in more signifi‐
cant detail.
Directory Objects
The first type of object is the directory object. This object's variant
part is defined as follows:
enum nstype {
UNKNOWN = 0,
NIS = 1,
SUNYP = 2,
DNS = 4,
X500 = 5,
DNANS = 6,
XCHS = 7,
}
typedef enum nstype nstype;
struct oar_mask {
uint_t oa_rights;
zotypes oa_otype;
}
typedef struct oar_mask oar_mask;
struct endpoint {
char *uaddr;
char *family;
char *proto;
}
typedef struct endpoint endpoint;
struct nis_server {
nis_name name;
struct {
uint_t ep_len;
endpoint *ep_val;
} ep;
uint_t key_type;
netobj pkey;
}
typedef struct nis_server nis_server;
struct directory_obj {
nis_name do_name;
nstype do_type;
struct {
uint_t do_servers_len;
nis_server *do_servers_val;
} do_servers;
uint32_t do_ttl;
struct {
uint_t do_armask_len;
oar_mask *do_armask_val;
} do_armask;
}
typedef struct directory_obj directory_obj;
The main structure contains five primary members: do_name, do_type,
do_servers, do_ttl, and do_armask. The information in the do_servers
structure is sufficient for the client library to create a network con‐
nection with the named server for the directory.
The do_name member contains the name of the directory or domain repre‐
sented in a format that is understandable by the type of nameservice
serving that domain. In the case of NIS+ domains, this is the same as
the name that can be composed using the zo_name and zo_domain members.
For other name services, this name will be a name that they understand.
For example, if this were a directory object describing an X.500 names‐
pace that is ``under'' the NIS+ directory eng.sun.com., this name
might contain ``/C=US, /O=Sun Microsystems, /OU=Engineering/''. The
type of nameservice that is being described is determined by the value
of the member do_type.
The do_servers structure contains two members. do_servers_val is an
array of nis_server structures; do_servers_len is the number of cells
in the array. The nis_server structure is designed to contain enough
information such that machines on the network providing name services
can be contacted without having to use a name service. In the case of
NIS+ servers, this information is the name of the machine in name, its
public key for authentication in pkey, and a variable length array of
endpoints, each of which describes the network endpoint for the rpcbind
daemon on the named machine. The client library uses the addresses to
contact the server using a transport that both the client and server
can communicate on and then queries the rpcbind daemon to get the
actual transport address that the server is using.
Note that the first server in the do_servers list is always the master
server for the directory.
The key_type field describes the type of key stored in the pkey netobj
(see /usr/include/rpc/xdr.h for a definition of the network object
structure). Currently supported types are NIS_PK_NONE for no public
key, NIS_PK_DH for a Diffie-Hellman type public key, and NIS_PK_DHEXT
for an extended Diffie-Hellman public key.
The do_ttl member contains a copy of the zo_ttl member from the common
attributes. This is the duplicated because the cache manager only
caches the variant part of the directory object.
The do_armask structure contains two members. do_armask_val is an array
of oar_mask structures; do_armask_len is the number of cells in the
array. The oar_mask structure contains two members: oa_rights specifies
the access rights allowed for objects of type oa_otype. These access
rights are used for objects of the given type in the directory when
they are present in this array.
The granting of access rights for objects contained within a directory
is actually two-tiered. If the directory object itself grants a given
access right (using the zo_access member in the nis_object structure
representing the directory), then all objects within the directory are
allowed that access. Otherwise, the do_armask structure is examined to
see if the access is allowed specifically for that type of structure.
This allows the administrator of a namespace to set separate policies
for different object types, for example, one policy for the creation of
tables and another policy for the creation of other directories. See
NIS+(1) for more details.
Link Objects
Link objects provide a means of providing aliases or symbolic links
within the namespace. Their variant part is defined as follows.
struct link_obj {
zotypes li_rtype;
struct {
uint_t li_attrs_len;
nis_attr *li_attrs_val;
} li_attrs;
nis_name li_name;
}
The li_rtype member contains the object type of the object pointed to
by the link. This is only a hint, since the object which the link
points to may have changed or been removed. The fully qualified name of
the object (table or otherwise) is specified in the member li_name.
NIS+ links can point to either other objects within the NIS+ namespace,
or to entries within a NIS+ table. If the object pointed to by the link
is a table and the member li_attrs has a nonzero number of attributes
(index name/value pairs) specified, the table is searched when this
link is followed. All entries which match the specified search pattern
are returned. Note, that unless the flag FOLLOW_LINKS is specified,
the nis_lookup(3NSL) function will always return non-entry objects.
Group Objects
Group objects contain a membership list of NIS+ principals. The group
objects' variant part is defined as follows.
struct group_obj {
uint_t gr_flags;
struct {
uint_t gr_members_len;
nis_name *gr_members_val;
} gr_members;
}
The gr_flags member contains flags that are currently unused. The
gr_members structure contains the list of principals. For a complete
description of how group objects are manipulated see nis_groups(3NSL).
Table Objects
The NIS+ table object is analogous to a YP map. The differences stem
from the access controls, and the variable schemas that NIS+ allows.
The table objects data structure is defined as follows:
#define TA_BINARY 1
#define TA_CRYPT 2
#define TA_XDR 4
#define TA_SEARCHABLE 8
#define TA_CASE 16
#define TA_MODIFIED 32
struct table_col {
char *tc_name;
uint_t tc_flags;
uint_t tc_rights;
}
typedef struct table_col table_col;
struct table_obj {
char *ta_type;
uint_t ta_maxcol;
uchar_t ta_sep;
struct {
uint_t ta_cols_len;
table_col *ta_cols_val;
} ta_cols;
char *ta_path;
}
The ta_type member contains a string that identifies the type of
entries in this table. NIS+ does not enforce any policies as to the
contents of this string. However, when entries are added to the table,
the NIS+ service will check to see that they have the same ``type'' as
the table as specified by this member.
The structure ta_cols contains two members. ta_cols_val is an array of
table_col structures. The length of the array depends on the number of
columns in the table; it is defined when the table is created and is
stored in ta_cols_len. ta_maxcol also contains the number of columns in
the table and always has the same value as ta_cols_len. Once the table
is created, this length field cannot be changed.
The ta_sep character is used by client applications that wish to print
out an entry from the table. Typically this is either space (`` '') or
colon (``:'').
The ta_path string defines a concatenation path for tables. This string
contains an ordered list of fully qualified table names, separated by
colons, that are to be searched if a search on this table fails to
match any entries. This path is only used with the flag FOLLOW_PATH
with a nis_list() call. See nis_tables(3NSL) for information on these
flags.
In addition to checking the type, the service will check that the
number of columns in an entry is the same as those in the table before
allowing that entry to be added.
Each column has associated with it a name in tc_name, a set of flags in
tc_flags, and a set of access rights in tc_rights. The name should be
indicative of the contents of that column.
The TA_BINARY flag indicates that data in the column is binary (rather
than text). Columns that are searchable cannot contain binary data. The
TA_CRYPT flag specifies that the information in this column should be
encrypted prior to sending it over the network. This flag has no effect
in the export version of NIS+. The TA_XDR flag is used to tell the
client application that the data in this column is encoded using the
XDR protocol. The TA_BINARY flag must be specified with the XDR flag.
Further, by convention, the name of a column that has the TA_XDR flag
set is the name of the XDR function that will decode the data in that
column.
The TA_SEARCHABLE flag specifies that values in this column can be
searched. Searchable columns must contain textual data and must have a
name associated with them. The flag TA_CASE specifies that searches
involving this column ignore the case of the value in the column. At
least one of the columns in the table should be searchable. Also, the
combination of all searchable column values should uniquely select an
entry within the table. The TA_MODIFIED flag is set only when the table
column is modified. When TA_MODIFIED is set, and the object is modi‐
fied again, the modified access rights for the table column must be
copied, not the default access rights.
Entry Objects
Entry objects are stored in tables. The structure used to define the
entry data is as follows.
#define EN_BINARY 1
#define EN_CRYPT 2
#define EN_XDR 4
#define EN_MODIFIED 8
struct entry_col {
uint_t ec_flags;
struct {
uint_t ec_value_len;
char *ec_value_val;
} ec_value;
}
typedef struct entry_col entry_col;
struct entry_obj {
char *en_type;
struct {
uint_t en_cols_len;
entry_col *en_cols_val;
} en_cols;
}
The en_type member contains a string that specifies the type of data
this entry represents. The NIS+ server will compare this string to the
type string specified in the table object and disallow any updates or
modifications if they differ.
The en_cols structure contains two members: en_cols_len and
en_cols_val. en_cols_val is an array of entry_col structures.
en_cols_len contains a count of the number of cells in the en_cols_val
array and reflects the number of columns in the table -- it always con‐
tains the same value as the table_obj.ta_cols.ta_cols_len member from
the table which contains the entry.
The entry_col structure contains information about the entry's per-col‐
umn values. ec_value contains information about a particular value. It
has two members: ec_value_val, which is the value itself, and
ec_value_len, which is the length (in bytes) of the value. entry_col
also contains the member ec_flags, which contains a set of flags for
the entry.
The flags in ec_flags are primarily used when adding or modifying
entries in a table. All columns that have the flag EN_CRYPT set will be
encrypted prior to sending them over the network. Columns with
EN_BINARY set are presumed to contain binary data. The server will
ensure that the column in the table object specifies binary data prior
to allowing the entry to be added. When modifying entries in a table,
only those columns that have changed need be sent to the server. Those
columns should each have the EN_MODIFIED flag set to indicate this to
the server.
SEE ALSONIS+(1), nis_groups(3NSL), nis_names(3NSL), nis_server(3NSL),
nis_subr(3NSL), nis_tables(3NSL)NOTES
NIS+ might not be supported in future releases of the Solaris operating
system. Tools to aid the migration from NIS+ to LDAP are available in
the current Solaris release. For more information, visit
http://www.sun.com/directory/nisplus/transition.html.
SunOS 5.10 10 Nov 2005 nis_objects(3NSL)
