NSSSEnumerateSecretIDs

Enables the administrator or user to list the secret identifiers (secret IDs) for secrets stored in the user's SecretStore.

Syntax

    #include <nssscl.h> 
     
    SS_EXTERN_LIBCALL(int) NSSSEnumerateSecretIDs 
    (
       SSS_CONTEXT_T    *callerContext, 
       SS_OBJECT_DN_T   *targetObject, 
       unsigned long     ssFlags, 
       char             *searchString, 
       unsigned long    *count 
       SS_SECRET_T      *secretIDList, 
       SS_EXT_T         *ext
    );

Parameters

callerContext
(IN) This optional structure can be initialized by making a call to NSSSGetServiceInformation prior to use here. The flags field of the structure can take on the following values to indicate the type of context used.NSSS_NCP_CTX_F—Directory Service API context indicator flagNSSS_LDAP_CTX_F—LDAP context indicator flag <reserved>
targetObject
(IN) This is the optional RDN (relative distinguished name or "short name") of the target object that contains the user's secrets. You should have at least READ/WRITE privileges over the target object.
ssFlags
(IN) This is a set of flags for initializing secrets:

Value

Description

NSSS_ALL_STRINGS_UNICODE_F

Indicates that all applicable char strings (such as targetObject, secretID, etc.) are already in Unicode and the API does not need to perform conversion from local code page to Unicode. This flag also instructs the API not to convert the return char strings to local code page.

NOTE:This is a feature of SSO client Version 1.1 and will not work on the older versions.

NSSS_SET_TREE_NAME_F

Sets the tree name.

NSSS_DESTROY_CONTEXT_F

Internally destroys the DS context passed in. This flag can be used on the last call to SecretStore to destroy the context that was used.
searchString
(IN) Set to *, NULL, or "" if all entries are desired in the search. Use the asterisk "*" as delimiter to search for specific entries with known prefixes, such as "MYAppSecretNumber_*".
count
(OUT) The number of secret identifiers stored for the user.
secretIDList
(OUT) An asterisk "*" separated list of secret identifiers matching the search string.
ext
(OUT) If present, this structure can return a set of applicable future extensions for the secrets.

Return Values

These are common return values for this function; see Section 4.0, Return Values for more information.

Value

Description

NSSS_SUCCESS

The operation succeeded.

NSSS_E_SYSTEM_FAILURE

Some internal operation failed due to some failure such as memory allocation.

NSSS_E_CORRUPTED_STORE

This indicates data corruption in SecretStore.

NSSS_E_NICI_FAILURE

NICI failure detected.

NSSS_E_INVALID_SECRET_ID

Secret ID is not in the SecretStore.

NSSS_E_ACCESS_DENIED

eDirectory denied access to an object or attributed related to the SecretStore.

NSSS_E_STORE_NOT_FOUND

Client does not have a SecretStore or the schema is not extended to begin with.

NSSS_E_NDS_INTERNAL_FAILURE

Some eDirectory operation has failed internally.

NSSS_E_INCOMPATIBLE_VERSION

Client SecretStore is not compatible with server SecretStore.

NSSS_E_INVALID_TARGET_OBJECT

Target object is not the type designated for SecretStore attachment.

Remarks

The memory allocated for the secretIDBuffer should be set to NSSS_ENUM_BUFFER_GUESS. This should be enough memory for most applications.

If this call returns NSSS_ERR_MORE_DATA (not a fatal error), call it again with a buffer the size of returned secretIDList->len. If the buffer is too small for all of the data in the SecretStore, the returned buffered from the server is stuffed as much as it has room. search string can be used to change the scope of the search when buffer size is a constraint.

See Also