2.4 Writing Shared Application or Credential Secrets

  1. Call NSSSCreateSHSHandle for each application thread that is involved in the sharing of secrets. A void pointer is returned that provides a handle for passing subsequent calls.

  2. Call NSSSReadSharedSecret to pass in the handle created in Step 1 and a user-populated SS_SH_SECRET_ID_T structure that contains the shared secret type, name, and length.

    NOTE:You also pass in the populated SSS_CONTEXT_T and SS_OBJECT_DN_T structures; ssFlags; and the SS_PWORD_T, SSS_READEXT_T, and SS_EXT_T structures that are typically provided when calling NSSSReadSecret. Consequently, NSSRReadSharedSecret enables you to make calls to trees and user DNs outside of the primary connection.

  3. Internally, NSSSReadSharedSecret calls NSSSReadSecret to retrieve secret data stored on SecretStore.

    1. The secret data is parsed according to the shared secret format using the parsing library.

    2. Sequential internal calls are made to enter key and value data into a linked list.

  4. Call NSSSAddSHSEntry sequentially to enter key or value data into the linked list (that is, the list associated with the handle).

    NOTE:This function contains pointers to user-allocated key and value buffers and the unsigned long context flag member of the SSS_CONTEXT_T structure populated from calling NSSSGetServiceInformation.

  5. Call NSSSWriteSharedSecret to pass a handle to write a shared secret, as well as a user-populated SS_SH_SECRET_ID_T structure containing the share secret type, name, and length. This creates a secret ID according to the secret ID format using either the prefix SS_App or SS_CredSet.

    NOTE:You also pass in the populated SSS_CONTEXT_T and SS_OBJECT_DN_T structures, ssFlags, and the SS_PWORD and SS_EXT_T structures that are typically passed when calling NSSSWriteSecret. Consequently, NSSRWriteSharedSecret enables you to make calls to trees and user DNs outside of the primary connection.

  6. NSSSWriteSharedSecret makes sequential internal calls to populate an internal buffer with data retrieved from the linked list.

    1. The internal buffer is parsed according to the shared secret format using the parsing library.

    2. Parsed data is passed into the secret buffer, then passed to NSSSWriteSecret in the SecretStore client.

  7. Before exiting the application, call NSSSDestroySHSHandle to free memory associated with the handle of each shared secret thread.

    NOTE:A complete set of operations is demonstrated in sshtst.exe and lshtst.exe and related source files for these executables are available in the SDK. In addition to these executable programs, SSManager.exe can be used to create, test, and view shared and raw (non-shared) secrets.