1.7 Shared Secret Functions

The Shared Secret functions are built on top of the raw SecretStore functions, so they inherently comply with the SecretStore specifications (see Shared Secret Format). Connectors use these functions to create Shared Secret (SHS) compliant secret IDs and secrets.

This section discusses the following specifications for Shared Secret functions:

1.7.1 Operational Functions

The Shared Secret operational functions operate on SecretStore and require that you set up the context to the SecretStore using regular SecretStore functions before using these function. These calls use SecretIDs that comply with SHS format (see Shared Secret Format):

Function

Description

NSSSReadSharedSecret

Enables a secret in the SHS format to be read out of the SecretStore and assigned to a handle previously created with a Create Handle call to be used by these calls.

NSSSWriteSharedSecret

Enables a secret in the SHS format that is previously assigned to a handle to be written to the SecretStore.

NSSSRemoveSharedSecret

Enables a secret in the SHS format to be removed from the SecretStore. The SecretID is assigned to a previously initialized handle. These operational APIs are created and formed using the Processing APIs listed below.

1.7.2 Processing Functions

Here are the processing functions that operate on the secret buffers returned by the Shared Secret Operational functions:

Function

Description

NSSSCreateSHSHandle

Enables the creation of a handle for an SHS buffer for the first time to populate and process an SHS format compliant secret that is formed as a list of components.

NSSSDestroySHSHandle

Enables the destruction of an SHS secret buffer signified by a handle in memory after the completion of the target operations.

NSSSGetNextSHSEntry

Enables moving through the SHS buffer components (key/value pairs) of the Shared Secret signified by the handle.

NSSSAddSHSEntry

Enables inserting a component (key/value pair) into the Shared Secret buffer signified by the handle at the current position of the Shared Secret.

NSSSRemoveSHSEntry

Enables removing a component (key/value pair) from the Shared Secret buffer signified by the handle passed in at the current position of the Shared Secret.

NOTE:As explained in Section 1.6.2, Shared Secret Format, Shared Secret components are on key/value paired structures formed as a list that are used by the processing functions. Operational functions can consume SHS buffers (list of components) signified by a handle and convert them to and from raw secret format for raw read and write operations to and from SecretStore.

1.7.3 Sequence of Shared Application or Credential Set Secret Operations

To help you implement the Shared Secret functions, you should understand the sequence of events when reading, writing, and removing a shared Application or Credential Set secret. Follow the procedures outlined in the following sections:

Keep in mind the following points about the connector:

  • For each thread in a connector operating on shared secrets, a call to NSSSCreateSHSHandle is needed to return a handle that is used for passing to subsequent calls.
  • All of these calls require a SecretStore context handle that has previously been initialized through calls to NSSSGetServiceInformation.
  • All of these calls require the handle as a well as a user-populated SS_SH_SECRET_ID_T structure containing the shared secret type, name, and length to be passed to them.
  • All of these calls create a SecretID according to the SecretID format using either SS_App or SS_CredSet as the prefix.

1.7.4 Sample Code

As with the SecretStore raw APIs, a complete collection of Shared Secret sample code is available on Novell's Developer Web site as a component of the Novell NDK. The following sample code can be downloaded and used as template that completely demonstrates the use of SecretStore APIs:

  • sshtst.c is the source code for the SSHTST.EXE program that demonstrates the use of the shared Secret APIs over the NCP transport.
  • lshtst.c is the source code for the LSHTXT.EXE program that demonstrates the use of the shared Secret APIs over LDAP.

All of the API prototypes, flags, structures, and error codes are defined in the ssshs.h file.