ct_labels

Description

Define a security label or clear security labels for a connection.

Syntax

CS_RETCODE ct_labels(connection, action,
                  labelname, namelen, labelvalue,
                  valuelen, outlen)
 
 CS_CONNECTION     *connection;
 CS_INT                       action;
 CS_CHAR                   *labelname;
 CS_INT                       namelen;
 CS_CHAR                   *labelvalue;
 CS_INT                       valuelen;
 CS_INT                       *outlen;

Parameters

connection

A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/server connection.

*connection must represent a closed connection.

action

One of the following symbolic values:

Value of action	Result
CS_SET	Sets a security label
CS_CLEAR	Clears all security labels previously specified for this connection

labelname

If action is CS_SET, labelname points to the name of the security label being set.

If action is CS_CLEAR, labelname must be NULL.

namelen

The length, in bytes, of *labelname. If *labelname is null-terminated, pass namelen as CS_NULLTERM.

Security label names must be at least 1 byte long and no more than CS_MAX_NAME bytes long.

If action is CS_CLEAR, pass namelen as CS_UNUSED.

labelvalue

If action is CS_SET, labelvalue points to the value of the security label being set.

If action is CS_CLEAR, labelvalue must be NULL.

valuelen

The length, in bytes, of *labelvalue. If *labelvalue is null-terminated, pass valuelen as CS_NULLTERM.

Security label values must be at least 1-byte long.

If action is CS_CLEAR, pass valuelen as CS_UNUSED.

outlen: This parameter is currently unused and must be passed as NULL.

Returns

ct_labels returns the following values:

Return value	Meaning
CS_SUCCEED	The routine completed successfully.
CS_FAIL	The routine failed.
CS_BUSY	An asynchronous operation is already pending for this connection. See “Asynchronous programming”.

Usage

An application needs to define security labels if it will be connecting to a server that uses trusted-user security handshakes.
There are two ways for an application to define security labels. An application can use either, or both, of these methods:
- The application can call ct_labels one time for each label it wants to define.
- The application can call ct_callback to install a user-supplied negotiation callback to generate security labels. At connection time, Client-Library automatically triggers the callback in response to a request for security labels.
If an application uses both methods, the labels defined using ct_labels and the labels generated by the negotiation callback are sent to the server at the same time.
A connection that will be participating in trusted-user security handshakes must set the CS_SEC_NEGOTIATE property to CS_TRUE.
There is no limit on the number of security labels that can be defined for a connection.
ct_labels does not perform any type of checking on security labels, but simply passes the label name and label value combinations on to the server.

For example, ct_labels does not raise an error if an application supplies two label values for the same label name.