Novell Documentation: Novell SecretStore Developer Kit for C

1.5 Understanding SecretStore Functions

This section discusses the following specifications for SecretStore functions:

1.5.1 SecretStore Implementation

Novell SecretStore is a collection of hidden attributes on an object (User object by default) in eDirectory. These attributes are implemented through eDirectory schema extensions and encrypted on the server using Novell International Cryptographic Infrastructure (NICI) services.

The single-valued Key attribute holds the cryptographic data and is the repository for stores-related statistical information.
The multi-valued Secrets attribute holds encrypted secrets identified by secret IDs and is the repository for the secrets' statistical information (time stamps and so on).

NOTE:For more implementation information about NICI, see the NICI 2.x Administration Guide.

Hidden attributes, by definition, are not accessible from client operating systems through eDirectory common interfaces and utilities. These attributes can only be accessed by SecretStore interfaces that apply strict access control and security measures to their access, transport, and disclosure.

In addition to these hidden and encrypted attributes, which protect data against attacks directed to the server, SecretStore provides an optional Enhanced Protection (EP) mode to defend against administrative attacks by locking the user's SecretStore. EP also enables secure unlocking, either through user control or through an action involving two separate administrators.

In this two-administrator scheme, the eDirectory password or authentication credential are reset by a network administrator, but SecretStore can only be unlocked by a separate SecretStore Administrator. To provide full control over this high-security feature, audit information is recorded after each administrative unlocking of Novell SecretStore in EP mode.

1.5.2 SecretStore Architecture

The overall architecture of the SecretStore API includes:

Cross-platform functions that work on any platform supported by eDirectory (NetWare, Windows, Solaris, AIX, Linux, and HP-UX).
Cross-transport functions that support either NCP (only on Windows clients) or LDAP (on all eDirectory platforms).
Cross-language functions that can be accessed through any Java^* or C++ compatible programming language.
Two categories of operational functions for writing connectors:
- Raw Novell SecretStore functions
- Shared Secret functions
A set of raw management functions for writing utilities that:
- Are available across different platforms and can transmit data to and from SecretStore over encrypted transports.
- Can start and end “stateless” SecretStore sessions for enabled applications (see Improved API Performance).
- Can start and end “stateful” SecretStore sessions that expand over multiple operations, if necessary (see Improved API Performance).
- Can find services for the users on administratively-designated servers across the eDirectory tree using the SecretStore client's service location feature.
- Provide Enhanced Protection (EP) against possible administrative attacks (see Section 1.12, Enhanced Protection).
- Provide two-administrator recovery from EP locking of the SecretStore (see SecretStore Implementation).

1.5.3 SecretStore API General Information

All of the Novell SecretStore functions are capable of obtaining a context internally in NCP mode. They operate by setting up a session and tearing it down at the end of that call in each stateless API session.
Each of the SecretStore functions is capable of accepting a context (LDAP or NCP) from the caller that has been created outside the SecretStore client or inside it with a prior call to NSSSGetServiceInformation.
All of the Novell SecretStore functions default to set the target object's SecretStore Distinguished Name (DN) to be the same as the caller DN, unless specified otherwise by the calling application.
For a caller DN to be different than the SecretStore's target object DN, the caller DN must have administrative rights over the SecretStore’s target object DN or must be defined as SecretStore administrator through configuration.
In LDAP mode, the caller DN and the SecretStore target object DN should comply with LDAP form.
Each of the SecretStore C functions is capable of unbinding or destroying the context upon request.

1.5.4 Single Sign-on Methods

The SecretStore service uses two basic single sign-on methods:

NOTE:These methods require implementation of the Shared Secret functions described in this document to enable applications to share secrets stored by different services.

Application Connectors

Using application connectors (or “regular” connectors) was the original method that enabled individual applications to access SecretStore. Specific application connectors were created for a number of e-mail systems, database systems, enterprise in-house applications, etc.

One popular example of an application connector is the Connector for Lotus Notes, which was part of the now-obsolete Novell Single Sign-on product line. While SecretStore remains as the cornerstone enabling technology, application connectors have been a specialized way of enabling applications to perform single sign-on operations.

Connectors are the method of choice in network environments where home-grown applications are used and the source of the client component of a network application is available for modification. In this category, there are some very successful custom application connector implementations. For example, Novell GroupWise® and the Novell Client for Windows have built-in connectors that provide single sign-on when SecretStore is available.

This set of solutions provides cross-platform support for a wide range of applications.

Universal Connectors

Universal connectors are currently the most efficient, cost-effective, and preferred method to enable single sign-on to target services. However, their use is limited to applications operating on Windows and using the Windows GUI. Users interact with the GUI to provide secrets and IDs, which are then stored in SecretStore.

These stored credentials are then passed to the application on subsequent invocations. The passed credentials authenticate the user without active interaction. This also allows for populating SecretStore for known applications beforehand. The greatest benefit of universal connectors is that they can often provide single sign-on to an application without requiring modifications to the application code itself.

Novell SecureLogin (NSL) is an advanced example of a universal connector. NSL relies on the architecture and methods of operation in the Windows operating system, browsers, and terminal emulators to recognize the prompts for authentication. The user or the administrator uses the built-in wizards or scripting language capability of the product to enable NSL to recognize the target applications, browsers, and service authentication dialogs.

Proxy Portals

Proxy portals are another category of universal connectors. Using these, a trusted, secure service can do the following:

Act as a connector to authenticate the user to the applications and services
Allow for populating users' SecretStores ahead of time so that the users can subsequently access applications

1.5.5 SecretStore Vault Service

SecretStore can be used as a secure vault to store user or application secrets of any kind. SecretStore by default is installed on an eDirectory user object by extending schema extensions. However, by using the management utilities supplied with SecretStore, you can extend schema on other object types, which allows applications to use SecretStore as a vault for storing secrets.

When SecretStore is enabled on a user object, the service guarantees that the read operation is only available when the requestor owns the SecretStore. This means that the DN of the requestor on the connection is the same as the target object containing the SecretStore. Consequently, if the administrator is the requestor, the service allows all of the operations to be performed for management and administration of the target store except reading of the user's secrets.

For non-user object based stores, since the store is used as a vault for applications, requestors with administrative rights also are allowed to read the secrets and perform necessary operations on behalf of the service owning the vault.

1.5.6 SecretStore Encrypted Attribute Service

SecretStore also provides the Encrypted Attribute Service, which allows requestors to store data in an encrypted secure form in eDirectory. As described in the previous items, access control on the stored data is a function of the type of object used for the target SecretStore.

1.5.7 Connector Interfaces

The interfaces for the administrative utilities and SecretStore connectors are based on SecretStore NCP-92 and/or LDAP extensions on Windows workstations. Client applications running on NetWare and UNIX platforms (HP-UX, Linux, Solaris, and AIX) are only LDAP-based extensions. NCP-92 is SecretStore's encrypted transport for secure transmission of data between a client and a server.

The NCP-92 transport utilizes NICI for encrypting inbound and outbound data to and from SecretStore. For more information, see Section 1.10, NICI and SecretStore .

This strong encryption is based on the common algorithm and strongest session key that is negotiated between NICI running on the client and server. The key and algorithm are negotiated at the end of the user's successful Novell Client authentication to eDirectory. At the end of each session the keys are destroyed. Each session with a different server has its own keys.

An LDAP extensions-based connection can be established through an SSL LDAP bind with the server. The bind can be done by the application prior to calling SecretStore, or by SecretStore if the application provides the appropriate credentials when calling the SecretStore interface. If a connection over LDAP is not SSL-based, SecretStore rejects it. The strength of encryption on the wire is dependent on the SSL-negotiated algorithm for the session.

Figure 1-1 illustrates the client NCP and LDAP protocol stacks on a client workstation.

Figure 1-1 Novell SecretStore C Server Architecture

NOTE:The NCP-92 stack is available only on clients running Windows operating systems, when the Novell Client is installed.

Figure 1-2 illustrates the server NCP and LDAP protocol stacks on a server platform.

Figure 1-2 Novell SecretStore C Server Architecture

NOTE:The NCP-92 stack is available only on NetWare server operating systems.

Operational Functions for Connectors

This section describes the operational functions used by connectors:

Function	Description
NSSSGetServiceInformation	Enables binding and unbinding over LDAP or creating and destroying eDirectory contexts over NCP to a target SecretStore server. It returns the following statistical information regarding a user's SecretStore: Number of secrets Cryptographic algorithm ID used on that SecretStore Cryptographic strength of the server Cryptographic strength of the client Caller's DN Target SecretStore's DN Master Password Hint DN of the last SecretStore administrator that unlocked the SecretStore In addition to the user (owner), the administrator is allowed to perform this operation on the user's SecretStore (except for the return of the Master Password hint).
NSSSWriteSecret	Enables populating SecretStore with secrets identified by uniquely-supplied secret IDs. It also enables the creation of new secrets (with the optional ability to overwrite existing secrets), checking for secret ID collision, and creating the secret for the first time by using special flags. Creating the first secret in a user's Novell SecretStore causes the creation of the Key and Secret hidden attribute pair for that user. In addition to the user (owner), the administrator is allowed to perform this operation on the user's Novell SecretStore.
NSSSReadSecret	Enables reading a secret identified by the supplied secret ID. It also enables the repair and synchronization of the SecretStore upon request by using a special flag.The first read operation after a write initiates a background synchronization and repair of the SecretStore. This function returns secret-related statistical information such as creation time stamp, last modified time stamp, and last accessed time stamp, in addition to the secret value. If the SecretStore configuration enables the Last Access Time Stamp option (which is optional due to the performance penalty involved), that time stamp is returned on the read. If Enhanced Protection is turned on, every read on an EP-flagged secret causes a check to see if there has been an administrative eDirectory login credential change. If so, the user's Novell SecretStore is locked. Only the owner is allowed to perform this operation on his or her SecretStore.
NSSSRemoveSecret	Enables removing a secret identified by the supplied secret ID. Removing the last secret in the user's SecretStore results in complete removal of the SecretStore from the object (removal of the Key and Secrets attribute pair). This functions returns secret-related statistical information such as creation time stamp, last modified time stamp, and last accessed time stamp, in addition to the secret value. If the SecretStore configuration enables the Last Access Time Stamp option (which is optional due to the performance penalty involved), then that time stamp is returned on the read. In addition to the user (owner), the administrator is allowed to perform this operation on the user's SecretStore.

Sample Code

SecretStore sample code is available as part of the SecretStore component of the NDK. Here are the samples that demonstrate the use of the operational functions described above:

Source Code	Sample Program	Description
sstst.c	SSTST.EXE	Demonstrates the use of the functions for connectors over the NCP transport.
lstst.c	LSTST.EXE	Demonstrates the use of the functions over the LDAP transport.
shtst.c	SHTST.EXE	Demonstrates the use of the Shared Secret functions over NCP.
lshtst.c	LSHTST.EXE	Demonstrates the use of the Shared Secret functions over LDAP.
nbstst.c	NBSTST.EXE	Demonstrates the use of the functions over LDAP when the bind is made by the application outside SecretStore and the context passed by the application is used to access the store.

1.5.8 SecretStore Management Utilities

The API also includes the following utilities to configure and manage a user's SecretStore.

SSManager is a Windows^*-based utility that allows users to manage their Novell SecretStores. SSManager.exe is included in the SecretStore Client install for Windows (...\ndk\ssocomp\SecStore\Client\Windows) and is accessible from the program files menu.
SSStatus is a Windows-based “light” version of SSManager that allows users to turn on Enhanced Protection, set the Master Password, and unlock the SecretStore when necessary. The SSStatus.exe tool is included in the SecretStore Client install (...\ndk\ssocomp\SecStore\Client\Windows).
ConsoleOne, with the appropriate snap-ins installed, is the all-purpose administrative utility for managing users' SecretStores, in addition to configuring and deploying the service in an eDirectory environment. The snapin SSSnapin.zip is included in the SDK in the \SecStore\Client\ folder.
SSSINIT.EXE enables administrators to extend the schema on a tree without performing a full installation of SecretStore on the server in that tree. The same utility also is used to remove schema extensions from the tree if the extensions are not used by any objects.
LDAPINIT.EXE enables administrators to add SecretStore extensions to a target server in the tree, which enables SecretStore LDAP operations against the SecretStore on that server. The same utility is used to remove the extensions from the server.

Management Functions for Utilities

SecretStore uses the following management functions for writing utilities:

Function	Description
NSSSEnumerateSecretIDs	Enables you to get a list of the secret IDs for secrets stored in the user's SecretStore. In addition to the administrator, the user is allowed to perform this operation on their Novell SecretStore.
NSSSSetEPMasterPassword	(NSSSSetMasterPassword) Enables the owner to set a Master Password and related hint on their SecretStore for the first time, if setting of Master Passwords is allowed through configuration on the server. The Master Password is used for unlocking the SecretStore and should be set before locking occurs. Only the owner is allowed to perform this operation on his or her SecretStore.
NSSSUnlockSecrets	Enables the removal of the lock from a user's locked store by using one of the following methods: Deleting all of the locked secrets Providing the last eDirectory password set by the user (only for eDirectory password changes, not other kinds of credentials) Using the Master Password (if one was set prior to locking that can be used to unlock in any form of administrative credential change) In addition to the user (owner), a designated and configured SecretStore administrator can unlock the user's SecretStore. If the two-administrator password reset scheme is not being used, the owner must use one of the methods listed above to unlock the SecretStore.
NSSSRemoveSecretStore	Enables the complete removal of the Novell SecretStore from the target object. Both the user and administrator are allowed to perform this operation on SecretStore.