Authenticates a connection with NSS to establish the first key for use with subsequent requests.
#include <zPublics.h> STATUS zRootKey( NINT connectionID, Key_t *retRootKey);
(IN) Specifies the connection that you want to authenticate with NSS. If you want to mask the eDirectory connection number, use 0xFFFF with the connection handle. If you are using the real connection number, you do not need to mask any of the bits.
(OUT) Points to the authentication key, which can be used with other interfaces to get additional keys and access NSS objects like directories, files, and search maps. When you are finished with the key, release it by calling zClose. When the connection key is closed, the NSS resources and keys associated with that connection are released.
|
zOK |
The operation completed successfully. |
|
non-0 |
An error occurred (see Section 4.1, Return Values for a description). |
The key returned by zRootKey represents the connection to NSS. This key has a different set of legal operations from a file system object key. For example, zGetInfo is not supported for root keys.
When the key is closed, all the NSS resources associated with the connection are released. Because this key can be used to obtained other keys, those keys are also automatically closed when this key is closed.
The strength of the authentication largely determines how secure the rest of the zAPIs are.
If an error occurs, the connection is not authenticated and no key is returned.