NSSSUnlockSecrets

This call unlocks the client's SecretStore after an administrative change of the client's eDirectory password has caused the user's SecretStore with enhanced protection secrets to become locked.

Syntax

    #include <nssscl.h> 
     
    SS_EXTERN_LIBCALL(int) NSSSUnlockSecrets 
    (
       SSS_CONTEXT_T     callerContext, 
       SS_OBJECT_DN_T   *targetObject, 
       unsigned long     ssFlags, 
       SS_PWORD_T       *password, 
       SS_EXT_T         *ext
    );

Parameters

callerContext
(IN) Specifies the 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. The caller should have at least READ/WRITE privileges over the target object.
ssFlags
(IN) Specifies the 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 instructs the API not to convert the return char strings to local code page as well. This is a feature of SSO client Version 1.1 and will not work on the older versions.

NSSS_REMOVE_LOCK_FROM_STORE_F

Causes SecretStore to delete all of the enhanced protected secrets that are locked and, therefore, remove the lock from SecretStore.

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_SET_TREE_NAME_F

Sets the tree name.

NSSS_DESTROY_CONTEXT_F

***
password
(IN) This points to the client's clear text password.
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.

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_INTERNAL_FAILURE

Some eDirectory operation has failed internally.

NSSS_E_INCOMPATIBLE_VERSION

Client SecretStore is not compatible with server SecretStore.

NSSS_E_UNLOCKING_FAILED

Verification of the old eDirectory password failed; therefore, unlocking the store failed.

NSSS_E_INVALID_TARGET_OBJECT

Target object is not the type designated for SecretStore attachment.

Remarks

NSSSUnlockSecrets the client's SecretStore after an administrative change of the client's eDirectory password. When administrator changes a eDirectory user's password, the SecretStore service is automatically locked. A prior call to NSSSReadSecret will fail with the NSSS_E_NDS_PWORD_CHANGED. Then the client should make a call to NSSSUnlockSecrets and supply the client's old eDirectory password to unlock the SecretStore.

If the service allows master password for users and the user has set a master password on their SecretStore prior to locking, then the user can use the master password to unlock the SecretStore. This helps for instances when the user forgets the eDirectory password.

If the password change has been due to a user forgetting the password and there is no master password, then SecretStore is not recoverable. Consequently, the locked SecretStore should be deleted and recreated by the client. eDirectory password changes by the user will not cause the SecretStore to be locked.

The owner of the SecretStore can use this function call with proper flags to remove the locked secrets or unlock the SecretStore with the previous eDirectory password or master password.

See Also