Define a security label or clear security labels for a connection.
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;
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.
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 |
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.
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.
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.
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.
This parameter is currently unused and must be passed as NULL.
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”. |
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.
