NSSSReadSecret

Reads the secrets from the SecretStore service for an authenticated user of a SecretStore-enabled application.

Syntax

    #include <nssscl.h> 
     
    SS_EXTERN_LIBCALL(int) NSSSReadSecret 
    (
       SSS_CONTEXT_T     callerContext, 
       SS_OBJECT_DN_T   *targetObject, 
       unsigned long     ssFlags,
       SS_PWORD_T        epPassword 
       SSS_READEXT_T     readInfo, 
       SS_SECRET_ID_T   *secretID, 
       SS_SECRET_T      *secretValue, 
       SS_EXT_T         *ext
    );

Parameters

callerContext
(IN) Specifies an optional structure that 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) Points to 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) Specifies a set of flags for initializing secrets.

Value

Description

NSSS_ALL_STRINGS_UNICODE_F

This flag 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 instructs the API not to convert the return char strings to local code page as well. This is a feature of SSO client v1.1 and does not work on the older versions.

NSSS_ENHANCED_PROTECTION_F

Enhanced Protection indicator flag for Read and Write.

NSSS_EP_MASTER_PWORD_USED_F

Enables the user to supply the EP master password to unlock the SecretStore in place of the previous eDirectory password.

NSSS_REPAIR_THE_STORE_F

Request all possible repairs on damaged store.

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.
epPassword
(IN) Specifies an optional field to pass in the Master Password or the Enhanced Protection Password for reading a secret. When neither one of the passwords are present, you can pass in a NULL.
readInfo
(OUT) Specifies the structure that returns the status information coming back from reading a secret.
secretID
(IN) Points to a unique secret identifier chosen by the application that should be supplied to locate the application secret values in the user’s secrets, preferably in the Novell conventional format described earlier in this document.
secretValue
(OUT) Points to a buffer that the client allocates for the returned secret value. A call with "secretValue->len=0" returns the required buffer size in "secretValue->size".
ext
(OUT) If present, points to 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 attribute 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_PWORD_CHANGE

Admin has changed the user password and as a result the client's SecretStore is locked (non-repudiation).

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.

NSSS_E_EP_ACCESS_DENIED

Enhanced Protection password validation failed.

Remarks

This SecretStore call accesses the service on behalf of a logged in and authenticated user. It returns to the client component of the application a clear copy of the application's secrets stored in SecretStore.

The unique secretID that was chosen for this application when the user’s SecretStore was being populated is passed in as input. As a result, the object is located in the tree and the SecretStore is read until the secretID is located. When the proper secret is located in the SecretStore, it is decrypted and returned in the secretValue buffer allocated for the purpose. Since the actual required size of the secret buffer is returned regardless of the success or failure of this call, the client can make a second call with the proper buffer size if the original request failed due to insufficient buffer size.

If the targetObject is of the "User" type in eDirectory, then the callerContext and the targetObject should match. In other words, only the owner of the SecretStore can read the secrets. If the targetObject is not a User, the call that has proper access rights can read SecretStore on a non-User object type in eDirectory.

The SecretCount field can return the count of secrets in the SecretStore if the client is talking to a Version 2.0 SecretStore on the server.

NOTE:sssinit.exe enables an administrator to extend the schema on a non-user object for SecretStore. This tool and the SecretStore product installation by default extends schema on a non-user object.

See Also