ModuleInterfaces

This is a draft

Physical Ports

The NSS cryptographic module is a software-only implementation. All keys, encrypted data, and control information are exchanged through calls to library functions (logical interfaces). The physical ports; physical covers, doors, or openings; manual controls; and physical status indicators of the NSS cryptographic module are those of the general purpose computer it runs on.

Logical Interfaces

The following four logical interfaces have been designed within the NSS cryptographic module.

Data input interface: function input arguments that specify plaintext data; ciphertext or signed data; cryptographic keys (plaintext or encrypted) and initialization vectors; and passwords that are to be input to and processed by the NSS cryptographic module.
Data output interface: function output arguments that receive plaintext data; ciphertext data and digital signatures; and cryptographic keys (plaintext or encrypted) and initialization vectors from the NSS cryptographic module.
Control input interface: function calls, or input arguments that specify commands and control data (e.g., algorithms, algorithm modes, or module settings) used to control the operation of the NSS cryptographic module
Status output interface: function return codes, error codes, or output arguments that receive status information used to indicate the status of the NSS cryptographic module

The NSS cryptographic module uses different function arguments for input and output to distinguish between data and control for input and data and status for output, and to disconnect the logical paths followed by data/control entering the module and data/status exiting the module. The NSS cryptographic module doesn't use the same buffer for input and output. After the NSS cryptographic module is done with an input buffer that holds security-related information, it always zeroizes the buffer so that if the memory is later reused as an output buffer, no sensitive information may be inadvertently leaked.

PKCS #11

The logical interfaces of the NSS cryptpgraphic module consist of the PKCS #11 (Cryptoki) API. The API itself defines the cryptographic boundary, i.e., all access to the cryptographic module is through this API. The module has three PKCS #11 tokens: two tokens that implement the non-FIPS Approved mode of operation, and one token that implements the FIPS Approved mode of operation. The FIPS PKCS #11 token is designed specifically for FIPS 140-2, and allows applications using the NSS cryptographic module to operate in a strictly FIPS mode.

The functions in the PKCS #11 API are listed in Table II of the Security Policy.

Inhibition of Data Output

All data output via the data output interface is inhibited when the NSS cryptographic module is in the Error state or performing self-tests.

In Error State

The boolean global variable sftk_fatalError tracks whether the NSS cryptographic module is in the Error state. Most PKCS #11 functions, including all the functions that output data via the data output interface, check the sftk_fatalError state variable on entry, and if it is true, return the CKR_DEVICE_ERROR error code immediately. Only the functions that shut down and restart the module, reinitialize the module, or output status information can be invoked in the Error state: FC_GetFunctionList, FC_Initialize, FC_Finalize, FC_GetInfo, FC_GetSlotList, FC_GetSlotInfo, FC_GetTokenInfo, FC_InitToken, FC_CloseSession, FC_CloseAllSessions, and FC_WaitForSlotEvent.

During Self-Tests

The NSS cryptographic module performs power-up self-tests in FC_Initialize and FC_Login.

No PKCS #11 function (except FC_GetFunctionList) works before the NSS cryptographic module is "powered up" (i.e., before FC_Initialize is called), so all data output via the data output interface is inhibited while FC_Initialize is performing the self-tests. When FC_Initialize is successful a global boolean variable is set to true. When FC_Login is successful a second global boolean, isLoggedIn, is set to true.

All functions that use secret or private cryptographic keys, including those that output data via the data output interface, check the global isLoggedIn boolean and, if it is false return the CKR_USER_NOT_LOGGED_IN error code immediately. Only the following functions may be called when the user is not logged in to the NSS cryptographic module: FC_GetFunctionList, FC_Finalize, FC_GetInfo, FC_GetSlotList, FC_GetSlotInfo, FC_GetTokenInfo, FC_GetMechanismList, FC_GetMechanismInfo, FC_InitToken, FC_InitPIN, FC_OpenSession, FC_CloseSession, FC_CloseAllSessions, FC_GetSessionInfo, FC_Login, FC_DigestInit, FC_Digest, FC_DigestUpdate, FC_DigestFinal, FC_SeedRandom, FC_GenerateRandom, FC_GetOperationState, FC_SetOperationState, and FC_WaitForSlotEvent.

Notes: FC_InitPIN may be called initially with the null password, after that the existing password must be supplied. FC_SeedRandom adds entropy data to the seed. It does not replace the seed.

Disconnecting the Output Data Path From the Key Processes

During key generation and key zeroization, the NSS cryptographic module doesn't execute any "printf" or logging statement that outputs sensitive information. Audit logging is performed as requested, but the entry does not contain cryptographically sensitive information. The NSS cryptographic module doesn't return the function output arguments until key generation or key zeroization is finished. Therefore, the logical paths used by output data exiting the module are logically disconnected from the processes/threads performing key generation and key zeroization.