Syntax

    #include <nssscl.h> 
     
    SS_EXTERN_LIBCALL(int) NSSSWriteSecret 
    (
       SSS_Context_T     callerContext, 
       SS_OBJECT_DN_T   *targetObject, 
       unsigned long     ssFlags 
       SS_PWORD_T       *epPassword, 
       SS_SECRET_ID_T   *secretID, 
       SS_SECRET_T      *secretValue,
       SS_EXT_F         *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_ENHANCED_PROTECTION_F	Sets the enhanced protection ON for this secret.
NSSS_EP_PASSWORD_USED_F	If Enhanced Protection is turned on (using the NSSS_ENHANCED_PROTECTION flag), this optional flag specifies the use of the password supplied through the SS_WRITEEXT_T and SS_EXT_T structures.
NSSS_CHECK_SID_FOR_COLISION_F	Forces the NSSSWriteSecret to check for the existance fo the secret in the SecretStore to prevent from overwriting a secret by returning the appropriate error.
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 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.

epPassword

(IN) This is an optional field to pass in the Master Password or the Enhanced Protection Password for writing a secret. When neither one of the passwords are present, you can pass in a NULL.

secretID

(IN) This is a unique secret identifier chosen by the application that should be supplied to locate the application secret values in the user's SecretStore.

secretValue

(IN) This is a buffer that the client allocates for the application secret value and encodes the secret within it.

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.

Remarks

The NSSSWriteSecret call begins a session with SecretStore to populate it with a new secret. This function call takes the clear copy of the application's secret from the application, encrypts it, and stores it in the user's SecretStore in eDirectory. The user of the application must be logged in and authenticated to eDirectory in order for this call to succeed.

The unique secret ID that was chosen for this application when installing the user's SecretStore is passed in as input. As a result, the object is located in the tree and the SecretStore is populated by adding the application secret values to it. Once the proper attribute value is located in the SecretStore, it is populated or overwritten with the application secret value in the incoming buffer. The application secret is encrypted and written to the user's secret associated with the target application. This call overwrites the existing value if present. This call by default creates and writes the secret and if the secret identified by the secret ID is found it will overwrite it.

The NSSS_CHECK_SID_FOR_COLLISION_F flag is used to force a check for existing secret identified by the secret ID in the SecretStore to prevent collision. The owner and other persons with proper access rights can use this function.

See Also

• NSSSReadSecret