SNMP monitoring agent

This appendix describes the Simple Network Management Protocol (SNMP) monitoring agent. The SNMP monitoring agent provides you with components that you can add to your (third-party) SNMP manager application.

SNMP was developed in 1988 and revised in 1996. It is currently regarded as the standard method of network management. It is widely supported and offers greater interoperability than traditional network management tools (for example, rsh or netstat). This makes it ideal for use for the large array of platforms that we support and also avoids the overhead of remote login and execution, helping to reduce network congestion and improve performance.

SNMP defines a collection of network management functions allowing management stations to gather information from, and transmit commands to, remote machines on the network. Agents running on the remote machines can take information gathered from the system and relay this information to the manager application. Such information is either requested from the underlying operating system or gained by interrogating the hardware.

Every SNMP manager adds monitor components differently. Consult the documentation supplied with your SNMP Manager application for details on how to add the MIB files.

SNMP defines the following SNMP messages:

Message Description

Message	Description
`get`	This message is sent by a manager to retrieve the value of an object at the agent.
`set`	This message is sent by a manager to set the value of an object at the agent.
`trap`	This message is sent by an agent to notify a management station of significant events.

get

This message is sent by a manager to retrieve the value of an object at the agent.

set

This message is sent by a manager to set the value of an object at the agent.

trap

This message is sent by an agent to notify a management station of significant events.

The SNMP monitoring agent is based on the open-source Net-SNMP project, version 5.7.3. More information on SNMP in general, and the data structures used to support SNMP installations, is available from the NET-SNMP project Web site: https://net-snmp.sourceforge.io/.

This site includes some support information and offers access to discussion e-mail lists. You can use the discussion lists to monitor subjects that might affect the operation or security of the SNMP agent or command-line utilities.

Discuss any enquiries arising from information on the NET-SNMP Web site with Support before posting potentially sensitive information to the NET-SNMP Web site.

Using the SNMP agent with a manager application

The nShield SNMP monitoring agent provides MIB files that can be added to your (third-party) SNMP manager application.

Manager configuration

The manager application is the interface through which the user is able to perform network management functions. A manager communicates with agents using SNMP primitives (get, set, trap) and is unaware of how data is retrieved from, and sent to, managed devices. This form of encapsulation creates the following:

The manager is hidden from all platform specific details
The manager can communicate with agents running on any IP-addressable machine.

As a consequence, manager applications are generic and can be bought off the shelf. You may already be running SNMP managers, and if so, you can use them to query the SNMP agent.

The manager is initially unaware of the MIB tree structure at a particular node. Managed objects can be retrieved or modified, but only if their location in the tree is known.

It is more useful if the manager can see the MIB tree present at each managed node. The MIB module descriptions for a particular node must be parsed by a manager-specific MIB compiler and converted to configuration files. These files are read by the manager application at run time.

The SNMP agent is designed to monitor all current nShield modules, working with all supported versions of nShield firmware (contact Support for details of supported firmware).

MIB module overview

A large proportion of the SNMP system is fully specified by the structure of the MIB; the behavior of the agent depends on relaying information according to the layout of the MIB.

The MIB module resides at a registered location in the MIB tree determined by the Internet Assigned Numbers Authority (IANA). The private enterprise number of 7682 designated by the IANA corresponds to the root of the branch, and by convention this (internal) node is the company name.

The MIB module groups logically related data together, organizing itself into a classification tree, with managed objects present at leaf nodes. The nC-series node (enterprises.nCipher.nC-series) is placed as a sub-tree of the root (enterprises.nCipher); this allows future product lines to be added as additional sub-trees. The structure of the tree underneath the registered location is vendor-defined, and this specification defines the structure chosen to represent Security World Software-specific data.

The MIB file can be found in the following location:

MIB functionality

The MIB module separates module information into the following categories:

Retrieval of status and information about installed nC-series modules
Retrieval of live statistics of performance of installed nC-series modules

These categories form the top-level nodes of the sub-tree; the functionality of the first category is in the administration sub-tree, and the second category is in the statistics sub-tree. The top-level tree also contains three items that it would be useful to check at-a-glance:

Node name R/W Type Remarks

Node name	R/W	Type	Remarks
`hardserverFailed`	R	TruthValue	`True` if the remote hardserver is not running. If the hardserver is not running, then most of the rest of the information is unreliable or missing.
`modulesFailed`	R	TruthValue	`True` if any modules have failed.
`load`	R	Unsigned32	Percentage of total available capacity currently utilized.

hardserverFailed

TruthValue

True if the remote hardserver is not running. If the hardserver is not running, then most of the rest of the information is unreliable or missing.

modulesFailed

TruthValue

True if any modules have failed.

load

Unsigned32

Percentage of total available capacity currently utilized.

Traps

The traps sub-tree (enterprises.nCipher.nC-series.nC-traps) contains traps that the SNMP agent sends when certain events occur. For details on configuring traps, see

The following table gives details of the individual traps:

Node name Description

Node name	Description
`hardserverAlert`	This trap is sent when the hardserver fails or is shut down.
`hardserverUnAlert`	This trap is sent when the hardserver restarts.
`moduleAlert`	This trap is sent when a module fails.
`moduleUnAlert`	This trap is sent when a module is restarted after a failure.
`psuAlert`	This trap is sent when a PSU fails.
`psuUnAlert`	This trap is sent when a previously-failed PSU is working again.
`fanfailureAlert`	This trap is sent when a fan fails.
`fanfailureUnAlert`	This trap is sent when a previously-failed fan is working again.
`memoryUsageHighAlert`	This trap is sent when the HSM memory usage high threshold has been reached or exceeded by an HSM. See section on Memory usage monitoring below for more details.
`memoryUsageOkAlert`	This trap is sent when the memory usage for an HSM falls below the HSM memory usage ok threshold. See section on Memory usage monitoring below for more details.

hardserverAlert

This trap is sent when the hardserver fails or is shut down.

hardserverUnAlert

This trap is sent when the hardserver restarts.

moduleAlert

This trap is sent when a module fails.

moduleUnAlert

This trap is sent when a module is restarted after a failure.

psuAlert

This trap is sent when a PSU fails.

psuUnAlert

This trap is sent when a previously-failed PSU is working again.

fanfailureAlert

This trap is sent when a fan fails.

fanfailureUnAlert

This trap is sent when a previously-failed fan is working again.

memoryUsageHighAlert

This trap is sent when the HSM memory usage high threshold has been reached or exceeded by an HSM. See section on Memory usage monitoring below for more details.

memoryUsageOkAlert

This trap is sent when the memory usage for an HSM falls below the HSM memory usage ok threshold. See section on Memory usage monitoring below for more details.

Some traps can take up to five minutes to be received.

Other generic Net-SNMP traps may also be received. These include the two below, see Net-SNMP project website for more details.

Net-SNMP trap name Description

Net-SNMP trap name	Description
`SNMPv2-MIB::coldStart`	This trap is sent when the SNMP agent is started
`NET-SNMP-AGENT-MIB::nsNotifyShutdown`	This trap is sent when the SNMP agent is stopped

SNMPv2-MIB::coldStart

This trap is sent when the SNMP agent is started

NET-SNMP-AGENT-MIB::nsNotifyShutdown

This trap is sent when the SNMP agent is stopped

Memory usage monitoring

The HSM memory usage thresholds and memory usage traps provide a mechanism to monitor HSM memory usage for HSMs in which the SNMP agent’s client computer are enrolled.

With memory usage monitoring enabled, there will be a memoryUsageHighAlert trap sent each time the currently in-use memoryUsageHighThreshold is reached or exceeded by an HSM.

With memory usage monitoring enabled, a memoryUsageHighAlert trap is also sent:

If the SNMP agent starts up and recognises that there are HSMs in a high memory usage state or,
If HSMs in a high memory usage state are enrolled or,
If the SNMP agent loses and then re-gains contact with the local hardserver which is connected to HSMs in a high memory usage state or,
If failed HSMs in a high memory usage state then recover.

For each of the four scenarios above, one memoryUsageHighAlert trap will be sent for each HSM in a high memory usage state.

With memory usage monitoring enabled, there will be a memoryUsageOkAlert trap sent each time the memory usage for an HSM falls below the currently in-use memoryUsageOkThreshold.

The value for memoryUsageOkThreshold is read from the snmpd.conf file on starting the SNMP agent and is used provided it contains an integer value in the range 0 to 100 (inclusive); otherwise, the default value of 0 is used. The value for memoryUsageHighThreshold is processed in the same way.

Memory usage monitoring is enabled unless the in-use values for memoryUsageOkThreshold and memoryUsageHighThreshold are both 0 or the in-use values are such that memoryUsageOkThreshold > memoryUsageHighThreshold.

For example, in snmpd.conf, if memoryUsageOkThreshold is assigned an invalid value and memoryUsageHighThreshold is assigned a valid value of say 75%, then memory usage monitoring will be enabled and the values 0% and 75% will be used respectively.

An example of memory usage monitoring by an SNMP agent on a client computer enrolled with 2 HSMs is given below:

Administration sub-tree overview

The administration sub-tree (enterprises.nCipher.nC-series.administration) contains information about the permanent state of the hardserver and the connected modules. It is likely that most of the information in this branch rarely changes over time, unlike the statistics branch. The information given in the administration sub-tree is mostly acquired by the NewEnquiry command and is supplied both per-module and (where appropriate) aggregated over all modules.

The following table gives details of the individual nodes in the administration sub-tree:

Node name R/W Type Remarks

Node name	R/W	Type	Remarks
`hardserverRunning`	R	Enum 1: Running 2: NotRunning	This variable reflects the current state of the hardserver (`Running` or `NotRunning`).
`noOfModules`	R	Gauge32	Number of nC-series modules.
`hsVersion`	R	DisplayString	Hardserver version string.
`globalSpeedIndex`	R	Gauge32	Number of 1024-bit signatures each second.
`globalminQ`	R	Gauge32	Minimum recommended queue.
`globalmaxQ`	R	Gauge32	Maximum recommended queue.
`SecurityWorld`	R	TruthValue	`True` if a Security World is installed and operational.
`swState`	R	DisplayString	Security World display flags, as reported by `nfkminfo`.
`listKeys`	R/W	Integer 1: none 2: all 3: query 4: resetquery	Controls the behavior of the key table (switch off, display all keys, enable individual attribute queries, clear the query fields). Displaying all keys can result in a very long list.
`serverFlags`	R	DisplayString	Supported hardserver facilities (the `NewEnquiry` level 4 flags).
`remoteServerPort`	R	Gauge32	TCP port on which the hardserver is listening.
`swGenTime`	R	DisplayString	Security World’s generation time.
`swGeneratingESN`	R	DisplayString	ESN of the module that generated the Security World.

hardserverRunning

Enum

1: Running

2: NotRunning

This variable reflects the current state of the hardserver (Running or NotRunning).

noOfModules

Gauge32

Number of nC-series modules.

hsVersion

DisplayString

Hardserver version string.

globalSpeedIndex

Gauge32

Number of 1024-bit signatures each second.

globalminQ

Gauge32

Minimum recommended queue.

globalmaxQ

Gauge32

Maximum recommended queue.

SecurityWorld

TruthValue

True if a Security World is installed and operational.

swState

DisplayString

Security World display flags, as reported by nfkminfo.

listKeys

R/W

Integer

1: none

2: all

3: query

4: resetquery

Controls the behavior of the key table (switch off, display all keys, enable individual attribute queries, clear the query fields). Displaying all keys can result in a very long list.

serverFlags

DisplayString

Supported hardserver facilities (the NewEnquiry level 4 flags).

remoteServerPort

Gauge32

TCP port on which the hardserver is listening.

swGenTime

DisplayString

Security World’s generation time.

swGeneratingESN

DisplayString

ESN of the module that generated the Security World.

listKeys can be preset using the keytable config directive in snmpd.conf file

Security World hash sub-tree

The following table gives details of the nodes in the Security World hash sub-tree (enterprises.nCipher.nC-series.administration.swHashes):

Node name R/W Type Remarks

Node name	R/W	Type	Remarks
`hashKNSO`	R	MHash	Hash of the Security Officer’s key.
`hashKM`	R	MHash	Hash of the Security World key.
`hashKRA`	R	MHash	Hash of the recovery authorization key.
`hashKRE`	R	MHash	Hash of the recovery key pair.
`hashKFIPS`	R	MHash	Hash of the FIPS authorization key.
`hashKMC`	R	MHash	Hash of the module certification key.
`hashKP`	R	MHash	Hash of the passphrase replacement key.
`hashKNV`	R	MHash	Hash of the nonvolatile memory (NVRAM) authorization key.
`hashKRTC`	R	MHash	Hash of the Real Time Clock authorization key.
`hashKDSEE`	R	MHash	Hash of the SEE Debugging authorization key.
`hashKFTO`	R	MHash	Hash of the Foreign Token Open authorization key.

hashKNSO

MHash

Hash of the Security Officer’s key.

hashKM

MHash

Hash of the Security World key.

hashKRA

MHash

Hash of the recovery authorization key.

hashKRE

MHash

Hash of the recovery key pair.

hashKFIPS

MHash

Hash of the FIPS authorization key.

hashKMC

MHash

Hash of the module certification key.

hashKP

MHash

Hash of the passphrase replacement key.

hashKNV

MHash

Hash of the nonvolatile memory (NVRAM) authorization key.

hashKRTC

MHash

Hash of the Real Time Clock authorization key.

hashKDSEE

MHash

Hash of the SEE Debugging authorization key.

hashKFTO

MHash

Hash of the Foreign Token Open authorization key.

Security World quorums sub-tree

The following table gives details of the nodes in the Security World quorums sub-tree (enterprises.nCipher.nC-series.administration.swQuorums):

Node name R/W Type Remarks

Node name	R/W	Type	Remarks
`adminQuorumK`	R	Gauge32	The default quorum of Administrator cards.
`adminQuorumN`	R	Gauge32	The total number of cards in the ACS.
`adminQuorumM`	R	Gauge32	The quorum required for module reprogramming.
`adminQuorumR`	R	Gauge32	The quorum required to transfer keys for OCS replacement.
`adminQuorumP`	R	Gauge32	The quorum required to recover the passphrase for an Operator card.
`adminQuorumNV`	R	Gauge32	The quorum required to access nonvolatile memory (NVRAM).
`adminQuorumRTC`	R	Gauge32	The quorum required to update the Real Time Clock.
`adminQuorumDSEE`	R	Gauge32	The quorum required to view full SEE debug information.
`adminQuorumFTO`	R	Gauge32	The quorum required to use a Foreign Token Open Delegate Key.

adminQuorumK

Gauge32

The default quorum of Administrator cards.

adminQuorumN

Gauge32

The total number of cards in the ACS.

adminQuorumM

Gauge32

The quorum required for module reprogramming.

adminQuorumR

Gauge32

The quorum required to transfer keys for OCS replacement.

adminQuorumP

Gauge32

The quorum required to recover the passphrase for an Operator card.

adminQuorumNV

Gauge32

The quorum required to access nonvolatile memory (NVRAM).

adminQuorumRTC

Gauge32

The quorum required to update the Real Time Clock.

adminQuorumDSEE

Gauge32

The quorum required to view full SEE debug information.

adminQuorumFTO

Gauge32

The quorum required to use a Foreign Token Open Delegate Key.

Module administration table

The following table gives details of the nodes in the module administration table (enterprises.nCipher.nC-series.administration.moduleAdminTable):

Node name R/W Type Remarks

Node name	R/W	Type	Remarks
`moduleAdminIndex`	R	Gauge32	Module number of this row in the table.
`mode`	R	Integer 1: Operational 2: Pre-init 3: Init 4: Pre-maint 5: Maint 6: AccelOnly 7: Failed 8: Unknown	Current module state.
`fwVersion`	R	DisplayString	Firmware version string.
`speedIndex`	R	Gauge32	Speed index (approximate number of 1024-bit modulo exponentiation operations possible per second) of module
`minQ`	R	Gauge32	Module minimum recommended queue length
`maxQ`	R	Gauge32	Module maximum recommended queue length
`serialNumber`	R	DisplayString	Module Electronic Serial Number (ESN).
`productName`	R	DisplayString
`hwPosInfo`	R	DisplayString	Hardware bus/slot info (such as PCI slot number).
`moduleSecurityWorld`	R	TruthValue	Indicates whether or not the module is in the current SW.
`smartcardState`	R	DisplayString	Description of smart card in slot (empty, unknown card, admin/operator card from current SW, failed). N/A for acceleration only modules.
`moduleSWState`	R	Integer 1: Unknown 2: Usable 3: MaintMode 4: Uninitialized 5: Factory 6: Foreign 7: AccelOnly 8: Failed 9: Unchecked 10: InitMode 11: PreInitMode 12: Unverified 13: UnusedTableEntry	Current module and Security World state.
`moduleSWFlags`	R	DisplayString	Security World flags for this module.
`hashKML`	R	MHash	Hash of the module’s secret key.
`moduleFeatures`	R	DisplayString	Features enabled on this module.
`moduleFlags`	R	DisplayString	Like `serverFlags`, but for each module.
`versionSerial`	R	Gauge32	Firmware Version Security Number (VSN); see Version Security Number (VSN).
`hashKNETI`	R	MHash	K_NETI hash, if present.
`longQ`	R	Gauge32	Max. rec. long queue.
`connectionStatus`	R	DisplayString	Connection status (for imported modules).
`connectionInfo`	R	DisplayString	Connection information (for imported modules).
`machineTypeSEE`	R	DisplayString	SEE machine type.

moduleAdminIndex

Gauge32

Module number of this row in the table.

mode

Integer

1: Operational

2: Pre-init

3: Init

4: Pre-maint

5: Maint

6: AccelOnly

7: Failed

8: Unknown

Current module state.

fwVersion

DisplayString

Firmware version string.

speedIndex

Gauge32

Speed index (approximate number of 1024-bit modulo exponentiation operations possible per second) of module

minQ

Gauge32

Module minimum recommended queue length

maxQ

Gauge32

Module maximum recommended queue length

serialNumber

DisplayString

Module Electronic Serial Number (ESN).

productName

DisplayString

hwPosInfo

DisplayString

Hardware bus/slot info (such as PCI slot number).

moduleSecurityWorld

TruthValue

Indicates whether or not the module is in the current SW.

smartcardState

DisplayString

Description of smart card in slot (empty, unknown card, admin/operator card from current SW, failed). N/A for acceleration only modules.

moduleSWState

Integer

1: Unknown

2: Usable

3: MaintMode

4: Uninitialized

5: Factory

6: Foreign

7: AccelOnly

8: Failed

9: Unchecked

10: InitMode

11: PreInitMode

12: Unverified

13: UnusedTableEntry

Current module and Security World state.

moduleSWFlags

DisplayString

Security World flags for this module.

hashKML

MHash

Hash of the module’s secret key.

moduleFeatures

DisplayString

Features enabled on this module.

moduleFlags

DisplayString

Like serverFlags, but for each module.

versionSerial

Gauge32

Firmware Version Security Number (VSN); see Version Security Number (VSN).

hashKNETI

MHash

K_NETI hash, if present.

longQ

Gauge32

Max. rec. long queue.

connectionStatus

DisplayString

Connection status (for imported modules).

connectionInfo

DisplayString

Connection information (for imported modules).

machineTypeSEE

DisplayString

SEE machine type.

Slot administration table

The following table gives details of the nodes in the slot administration table (enterprises.nCipher.nC-series.administration.slotAdminTable):

Node name R/W Type Remarks

Node name	R/W	Type	Remarks
`slotAdminModuleIndex`	R	Integer32	Module number of the module containing the slot.
`slotAdminSlotIndex`	R	Integer32	Slot number (1-based, unlike nCore which is 0-based).
`slotType`	R	Integer 1: Datakey 2: Smart card 3: Emulated 4: Soft token 5: Unconnected 6: Out of range 7: Unknown	Slot type.
`slotFlags`	R	DisplayString	Flags referring to the contents of the slot (from `slotinfo`).
`slotState`	R	Integer 1: Unused 2: Empty 3: Blank 4: Administrator 5: Operator 6: Unidentified 7: Read error 8: Partial 9: Out of range	`Partial` refers to cards in a partially-created card set.
`slotListFlags`	R	DisplayString	Flags referring to attributes of the slot (from `getslotlist`).
`slotShareNumber`	R	Gauge32	Share number of card currently in slot, if present.
`slotSharesPresent`	R	DisplayString	Names of shares present in card currently in slot.

slotAdminModuleIndex

Integer32

Module number of the module containing the slot.

slotAdminSlotIndex

Integer32

Slot number (1-based, unlike nCore which is 0-based).

slotType

Integer

1: Datakey

2: Smart card

3: Emulated

4: Soft token

5: Unconnected

6: Out of range

7: Unknown

Slot type.

slotFlags

DisplayString

Flags referring to the contents of the slot (from slotinfo).

slotState

Integer

1: Unused

2: Empty

3: Blank

4: Administrator

5: Operator

6: Unidentified

7: Read error

8: Partial

9: Out of range

Partial refers to cards in a partially-created card set.

slotListFlags

DisplayString

Flags referring to attributes of the slot (from getslotlist).

slotShareNumber

Gauge32

Share number of card currently in slot, if present.

slotSharesPresent

DisplayString

Names of shares present in card currently in slot.

Card set administration table

The following table gives details of the nodes in the card set administration table (enterprises.nCipher.nC-series.administration.cardsetAdminTable):

Node name R/W Type Remarks

Node name	R/W	Type	Remarks
`hashKLTU`	R	MHash	Hash of the token protected by the card set.
`cardsetName`	R	DisplayString
`cardsetK`	R	Gauge32	Required number of cards in the card set.
`cardsetN`	R	Gauge32	Total number of cards in the card set.
`cardsetFlags`	R	DisplayString	Other attributes of the card set.
`cardsetNames`	R	DisplayString	Names of individual cards, if set.
`cardsetTimeout`	R	Gauge32	Token time-out period, in seconds, or 0 if none.
`cardsetGenTime`	R	DisplayString	Generation time of card set.

hashKLTU

MHash

Hash of the token protected by the card set.

cardsetName

DisplayString

cardsetK

Gauge32

Required number of cards in the card set.

cardsetN

Gauge32

Total number of cards in the card set.

cardsetFlags

DisplayString

Other attributes of the card set.

cardsetNames

DisplayString

Names of individual cards, if set.

cardsetTimeout

Gauge32

Token time-out period, in seconds, or 0 if none.

cardsetGenTime

DisplayString

Generation time of card set.

Key administration table

The key administration table is visible as long as the listKeys node in the administration sub-tree is set to a value other than none.

The following table gives details of the nodes in the key administration table (enterprises.nCipher.nC-series.administration.keyAdminTable):

Node name R/W Type Remarks

Node name	R/W	Type	Remarks
`keyAppname`	R	DisplayString	Application name.
`keyIdent`	R	DisplayString	Name of key, as generated by the application.
`keyHash`	R	MHash
`keyRecovery`	R	Integer 1: Enabled 2: Disabled 3: No key 4: Unknown 5: Invalid 6: Unset	The value `unset` is never returned by the key table. If you set the value `unset`, the keys are not filtered based on any of the attributes.
`keyProtection`	R	Integer 1: Module 2: Cardset 3: No key 4: Unknown 5: Invalid 6: Unset	The value `unset` is never returned by the key table. If you set the value `unset`, the keys are not filtered based on any of the attributes.
`keyCardsetHash`	R	MHash	Hash of the card set protecting the key, if applicable.
`keyFlags`	R	DisplayString	Certificate and public key flags.
`keyExtraEntries`	R	Gauge32	Number of extra key attributes.
`keySEEInteg`	R	DisplayString	SEE integrity key, if present.
`keyGeneratingESN`	R	DisplayString	ESN of the module that generated the key, if present.
`keyTimeLimit`	R	Gauge32	Time limit for the key, if set.
`keyPerAuthUseLimit`	R	Gauge32	Per-authentication use limit for the key.

keyAppname

DisplayString

Application name.

keyIdent

DisplayString

Name of key, as generated by the application.

keyHash

MHash

keyRecovery

Integer

1: Enabled

2: Disabled

3: No key

4: Unknown

5: Invalid

6: Unset

The value unset is never returned by the key table. If you set the value unset, the keys are not filtered based on any of the attributes.

keyProtection

Integer

1: Module

2: Cardset

3: No key

4: Unknown

5: Invalid

6: Unset

The value unset is never returned by the key table. If you set the value unset, the keys are not filtered based on any of the attributes.

keyCardsetHash

MHash

Hash of the card set protecting the key, if applicable.

keyFlags

DisplayString

Certificate and public key flags.

keyExtraEntries

Gauge32

Number of extra key attributes.

keySEEInteg

DisplayString

SEE integrity key, if present.

keyGeneratingESN

DisplayString

ESN of the module that generated the key, if present.

keyTimeLimit

Gauge32

Time limit for the key, if set.

keyPerAuthUseLimit

Gauge32

Per-authentication use limit for the key.

Key query sub-tree

The key query sub-tree is used if the listKeys node in the administration sub-tree is set to query.

If these values are set, they are taken as required attributes for filtering the list of available keys; if multiple attributes are set, the filters are combined (AND rather than OR).

The following table gives details of the nodes in the key query sub-tree (enterprises.nCipher.nC-series.administration.keyQuery):

Node name R/W Type Remarks

Node name	R/W	Type	Remarks
`keyQueryAppname`	R/W	DisplayString	Application name.
`keyQueryIdent`	R/W	DisplayString	Name of key, as generated by the application.
`keyQueryHash`	R/W	DisplayString
`keyQueryRecovery`	R/W	Integer 1: Enabled 2: Disabled 3: No key 4: Unknown 5: Invalid 6: Unset	The value `unset` is never returned by the key table. If you set the value `unset`, the keys are not filtered based on any of the attributes.
`keyQueryProtection`	R/W	Integer 1: Module 2: Cardset 3: No key 4: Unknown 5: Invalid 6: Unset	The value `unset` is never returned by the key table. If you set the value `unset`, the keys are not filtered based on any of the attributes.
`keyQueryCardsetHash`	R/W	DisplayString	Hash of the card set protecting the key, if applicable.
`keyQueryFlags`	R/W	DisplayString	Certificate and public key flags.
`keyQueryExtraEntries`	R/W	Gauge32	Number of extra key attributes.
`keyQuerySEEInteg`	R/W	DisplayString	SEE integrity key, if present.
`keyQueryGeneratingESN`	R/W	DisplayString	ESN of the module that generated the key, if present.
`keyQueryTimeLimit`	R/W	Gauge32	Time limit for the key, if set (0 for no limit).
`keyQueryPerAuthUseLimit`	R/W	Gauge32	Per-authentication use limit for the key (0 for no limit).

keyQueryAppname

R/W

DisplayString

Application name.

keyQueryIdent

R/W

DisplayString

Name of key, as generated by the application.

keyQueryHash

R/W

DisplayString

keyQueryRecovery

R/W

Integer

1: Enabled

2: Disabled

3: No key

4: Unknown

5: Invalid

6: Unset

The value unset is never returned by the key table. If you set the value unset, the keys are not filtered based on any of the attributes.

keyQueryProtection

R/W

Integer

1: Module

2: Cardset

3: No key

4: Unknown

5: Invalid

6: Unset

The value unset is never returned by the key table. If you set the value unset, the keys are not filtered based on any of the attributes.

keyQueryCardsetHash

R/W

DisplayString

Hash of the card set protecting the key, if applicable.

keyQueryFlags

R/W

DisplayString

Certificate and public key flags.

keyQueryExtraEntries

R/W

Gauge32

Number of extra key attributes.

keyQuerySEEInteg

R/W

DisplayString

SEE integrity key, if present.

keyQueryGeneratingESN

R/W

DisplayString

ESN of the module that generated the key, if present.

keyQueryTimeLimit

R/W

Gauge32

Time limit for the key, if set (0 for no limit).

keyQueryPerAuthUseLimit

R/W

Gauge32

Per-authentication use limit for the key (0 for no limit).

Statistics sub-tree overview

The statistics sub-tree (enterprises.nCipher.nC-series.statistics) contains rapidly changing information about such topics as the state of the nShield modules, the work they are doing, and the commands being submitted.

Do not rely on information returned from the agent to change instantaneously on re-reading the value. To avoid loading the nShield module with multiple time-consuming statistics commands, the agent can choose to cache the values over a specified period. You can configure this period in the agent configuration file see

Statistics sub-tree

The following table gives details of the nodes in the statistics sub-tree, and the module statistics table (enterprises.nCipher.nC-series.statistics.moduleStatsTable):

Node name R/W Type Remarks

Node name	R/W	Type	Remarks
`moduleStatsIndex`	R	Integer	Module number of this row (for `moduleStatsTable`).
`hsuptime`	R	Counter32	Uptime of the hardserver.
`cmdCountAll`	R	Counter32	Returned aggregated for all modules and all commands.
`cmdBytesAll`	R	Counter32
`cmdErrorsAll`	R	Counter32	Returned as for `cmdCount`, returned value is combined module errors added to hardserver marshalling/unmarshalling errors.
`replyCountAll`	R	Counter32
`replyBytesAll`	R	Counter32
`replyErrorsAll`	R	Counter32	See notes above for `cmdErrors`.
`clientCount`	R	Gauge32
`maxClients`	R	Counter32
`deviceFails`	R	Counter32
`deviceRestarts`	R	Counter32
`outstandingCmds`	R	Counter32	Total number of outstanding commands over all modules.
`load[All]`	R	Counter32

moduleStatsIndex

Integer

Module number of this row (for moduleStatsTable).

hsuptime

Counter32

Uptime of the hardserver.

cmdCountAll

Counter32

Returned aggregated for all modules and all commands.

cmdBytesAll

Counter32

cmdErrorsAll

Counter32

Returned as for cmdCount, returned value is combined module errors added to hardserver marshalling/unmarshalling errors.

replyCountAll

Counter32

replyBytesAll

Counter32

replyErrorsAll

Counter32

See notes above for cmdErrors.

clientCount

Gauge32

maxClients

Counter32

deviceFails

Counter32

deviceRestarts

Counter32

outstandingCmds

Counter32

Total number of outstanding commands over all modules.

load[All]

Counter32

Module statistics table

The following table gives details of the nodes in the module statistics table (enterprises.nCipher.nC-series.statistics.moduleStatsTable):

Node name R/W Type Remarks

Node name	R/W	Type	Remarks
`moduleStatsIndex`	R	Integer	Module number of this row (for `moduleStatsTable`).
`uptime`	R	Counter32	Uptime of the module.
`cmdCount`	R	Counter32	Returned aggregated for all commands.
`cmdBytes`	R	Counter32
`cmdErrors`	R	Counter32	Returned as for `cmdCount` all the different error states aggregated into one counter.
`replyCount`	R	Counter32
`replyBytes`	R	Counter32
`replyErrors`	R	Counter32	See notes above for `cmdErrors`.
`loadModule`	R	Counter32
`loadModule`	R	Counter32
`objectCount`	R	Gauge32
`clock`	R	DisplayString	Depending on the module settings, this can require K_NSO permissions to read (and therefore depend on the installation parameters of the agent).
`nvRAMInUse`	R	Gauge32
`volatileRAMInUse`	R	Gauge32
`tempSP`	R	DisplayString
`currentCPUTemp1`	R	DisplayString
`currentCPUTemp2`	R	DisplayString
`currentFanSpeed`	R	DisplayString
`currentFanDuty`	R	DisplayString
`CPUVoltage1`	R	DisplayString
`CPUVoltage2`	R	DisplayString
`CPUVoltage3`	R	DisplayString
`CPUVoltage4`	R	DisplayString
`CPUVoltage5`	R	DisplayString
`CPUVoltage6`	R	DisplayString
`CPUVoltage7`	R	DisplayString
`CPUVoltage8`	R	DisplayString
`CPUVoltage8`	R	DisplayString
`CPUVoltage9`	R	DisplayString
`CPUVoltage10`	R	DisplayString
`CPUVoltage11`	R	DisplayString
`nvmFreeSpace`	R	Counter32	Free space available on the HSM’s NVRAM, in bytes
`nvmWearLevel`	R	DisplayString	Wear level of the HSM’s NVRAM
`nvmWornBlocks`	R	DisplayString	Worn blocks in the HSM’s NVRAM

moduleStatsIndex

Integer

Module number of this row (for moduleStatsTable).

uptime

Counter32

Uptime of the module.

cmdCount

Counter32

Returned aggregated for all commands.

cmdBytes

Counter32

cmdErrors

Counter32

Returned as for cmdCount all the different error states aggregated into one counter.

replyCount

Counter32

replyBytes

Counter32

replyErrors

Counter32

See notes above for cmdErrors.

loadModule

Counter32

loadModule

Counter32

objectCount

Gauge32

clock

DisplayString

Depending on the module settings, this can require K_NSO permissions to read (and therefore depend on the installation parameters of the agent).

nvRAMInUse

Gauge32

volatileRAMInUse

Gauge32

tempSP

DisplayString

currentCPUTemp1

DisplayString

currentCPUTemp2

DisplayString

currentFanSpeed

DisplayString

currentFanDuty

DisplayString

CPUVoltage1

DisplayString

CPUVoltage2

DisplayString

CPUVoltage3

DisplayString

CPUVoltage4

DisplayString

CPUVoltage5

DisplayString

CPUVoltage6

DisplayString

CPUVoltage7

DisplayString

CPUVoltage8

DisplayString

CPUVoltage8

DisplayString

CPUVoltage9

DisplayString

CPUVoltage10

DisplayString

CPUVoltage11

DisplayString

nvmFreeSpace

Counter32

Free space available on the HSM’s NVRAM, in bytes

nvmWearLevel

DisplayString

Wear level of the HSM’s NVRAM

nvmWornBlocks

DisplayString

Worn blocks in the HSM’s NVRAM

nShield HSM statistics table

The following table gives details of the nodes in the nShield HSM statistics table (enterprises.nCipher.nC-series.statistics.netHSMStatsTable):

Node name R/W Type Remarks

Node name	R/W	Type	Remarks
`netHSMStatsIndex`	R	Integer	Table index (not module number).
`netHSMUptime`	R	Counter32	Host system uptime.
`netHSMCPUUsage`	R	Gauge32	CPU usage of unit host processor.
`netHSMUserMem`	R	Gauge32	Total user memory of unit.
`netHSMKernelMem`	R	Gauge32	Total kernel memory of unit.
`netHSMCurrentTemp`	R	DisplayString	Internal unit temperature (sensor 1).
`netHSMMaxTemp`	R	DisplayString	Maximum recorded temperature (sensor 1).
`netHSMCurrentTemp2`	R	DisplayString	Internal unit temperature (sensor 2).
`netHSMMaxTemp2`	R	DisplayString	Maximum recorded temperature (sensor 2).
`netHSMVoltage5V`	R	DisplayString	unit 5V power reading.
`netHSMVoltage12V`	R	DisplayString	unit 12V power reading.
`netHSMFan1Speed`	R	Gauge32	Fan 1 speed (RPM).
`netHSMFan2Speed`	R	Gauge32	Fan 2 speed (RPM).
`netHSMFan3Speed`	R	Gauge32	Fan 3 speed (RPM).
`netHSMIPAddress`	R	IpAddress	IP address of unit.
`netHSMDescription`	R	DisplayString	Textual description of module (for example, `Local module 3`).
`netHSMFan4Speed`	R	Gauge32	Fan 4 speed (RPM).
`netHSMVoltage3p3V`	R	DisplayString	3.3V Supply Rail Voltage
`netHSMCurrent3p3V`	R	DisplayString	3.3V Supply Rail Current
`netHSMCurrent5V`	R	DisplayString	5V Supply Rail Current
`netHSMCurrent12V`	R	DisplayString	12V Supply Rail Current
`netHSMVoltage5VSB`	R	DisplayString	5V Supply Rail Voltage (Standby)
`netHSMCurrent5VSB`	R	DisplayString	5V Supply Rail Current (Standby)
`netHSMTamperBattery1`	R	DisplayString	Voltage of Tamper Battery 1
`netHSMTamperBattery2`	R	DisplayString	Voltage of Tamper Battery 2
`netHSMPSUfailure`	R	TruthValue	Power Supply failure status

netHSMStatsIndex

Integer

Table index (not module number).

netHSMUptime

Counter32

Host system uptime.

netHSMCPUUsage

Gauge32

CPU usage of unit host processor.

netHSMUserMem

Gauge32

Total user memory of unit.

netHSMKernelMem

Gauge32

Total kernel memory of unit.

netHSMCurrentTemp

DisplayString

Internal unit temperature (sensor 1).

netHSMMaxTemp

DisplayString

Maximum recorded temperature (sensor 1).

netHSMCurrentTemp2

DisplayString

Internal unit temperature (sensor 2).

netHSMMaxTemp2

DisplayString

Maximum recorded temperature (sensor 2).

netHSMVoltage5V

DisplayString

unit 5V power reading.

netHSMVoltage12V

DisplayString

unit 12V power reading.

netHSMFan1Speed

Gauge32

Fan 1 speed (RPM).

netHSMFan2Speed

Gauge32

Fan 2 speed (RPM).

netHSMFan3Speed

Gauge32

Fan 3 speed (RPM).

netHSMIPAddress

IpAddress

IP address of unit.

netHSMDescription

DisplayString

Textual description of module (for example, Local module 3).

netHSMFan4Speed

Gauge32

Fan 4 speed (RPM).

netHSMVoltage3p3V

DisplayString

3.3V Supply Rail Voltage

netHSMCurrent3p3V

DisplayString

3.3V Supply Rail Current

netHSMCurrent5V

DisplayString

5V Supply Rail Current

netHSMCurrent12V

DisplayString

12V Supply Rail Current

netHSMVoltage5VSB

DisplayString

5V Supply Rail Voltage (Standby)

netHSMCurrent5VSB

DisplayString

5V Supply Rail Current (Standby)

netHSMTamperBattery1

DisplayString

Voltage of Tamper Battery 1

netHSMTamperBattery2

DisplayString

Voltage of Tamper Battery 2

netHSMPSUfailure

TruthValue

Power Supply failure status

Per connection statistics table

The following table gives details of the nodes in the per connection statistics table (enterprises.nCipher.nC-series.statistics.connStatsTable):

Node name R/W Type Remarks

Node name	R/W	Type	Remarks
`connStatsIndex`	R	Integer32	Index of this entry.
`connNumber`	R	Integer32	Hardserver connection number.
`connUptime`	R	Counter32	Uptime of the connection.
`connCmdCount`	R	Counter32	Number of commands submitted through this connection.
`connCmdBytes`	R	Counter32	Number of bytes submitted through this connection.
`connCmdErrors`	R	Counter32	Number of marshalling errors on commands through this connection.
`connReplyCount`	R	Counter32	Number of replies received by this connection.
`connReplyBytes`	R	Counter32	Number of bytes received by this connection.
`connReplyErrors`	R	Counter32	Number of marshalling errors on replies through this connection.
`connDevOutstanding`	R	Gauge32	Number of commands outstanding on this connection.
`connQOutstanding`	R	Gauge32	Number of commands outstanding in the hardserver queue.
`connLongOutstanding`	R	Gauge32	Number of long jobs outstanding for this connection.
`connRemoteIPAddress`	R	IpAddress	IP Address of connection client.
`connProcessID`	R	Integer32	Process identifier reported by connection client.
`connProcessName`	R	DisplayString	Process name reported by connection client.
`connObjectTotal`	R	Gauge32	The total object count for a connection

connStatsIndex

Integer32

Index of this entry.

connNumber

Integer32

Hardserver connection number.

connUptime

Counter32

Uptime of the connection.

connCmdCount

Counter32

Number of commands submitted through this connection.

connCmdBytes

Counter32

Number of bytes submitted through this connection.

connCmdErrors

Counter32

Number of marshalling errors on commands through this connection.

connReplyCount

Counter32

Number of replies received by this connection.

connReplyBytes

Counter32

Number of bytes received by this connection.

connReplyErrors

Counter32

Number of marshalling errors on replies through this connection.

connDevOutstanding

Gauge32

Number of commands outstanding on this connection.

connQOutstanding

Gauge32

Number of commands outstanding in the hardserver queue.

connLongOutstanding

Gauge32

Number of long jobs outstanding for this connection.

connRemoteIPAddress

IpAddress

IP Address of connection client.

connProcessID

Integer32

Process identifier reported by connection client.

connProcessName

DisplayString

Process name reported by connection client.

connObjectTotal

Gauge32

The total object count for a connection

Module/connection statistics table

The following table gives details of the nodes in the per module, per connection statistics table (enterprises.nCipher.nC-series.statistics.connModuleStatsTable).

Node name R/W Type Remarks

Node name	R/W	Type	Remarks
`connModuleStatsConnId`	R	Integer	Identity of this connection
`connModuleStatsModuleIndex`	R	Integer	Index of the module entry
`connModuleStatsObjectCount`	R	Gauge32	The object count on this module for this connection

connModuleStatsConnId

Integer

Identity of this connection

connModuleStatsModuleIndex

Integer

Index of the module entry

connModuleStatsObjectCount

Gauge32

The object count on this module for this connection

Fan table

The fan table provides the speeds of each fan on the remote module (HSM). The following table gives details of the nodes in the fan table (enterprises.nCipher.softwareVersions.netHSMFanTable):

Node name R/W Type Remarks

Node name	R/W	Type	Remarks
`netHSMModuleIndex`	R	Integer32	Module number
`netHSMFanIndex`	R	Integer32	Fan number
`netHSMFanSpeed`	R	Gauge32	Fan speed (RPM)

netHSMModuleIndex

Integer32

Module number

netHSMFanIndex

Integer32

Fan number

netHSMFanSpeed

Gauge32

Fan speed (RPM)

Software versions table

The following table gives details of the nodes in the software versions table (enterprises.nCipher.softwareVersions.softwareVersionsTable):

Node name R/W Type Remarks

Node name	R/W	Type	Remarks
`compIndex`	R	Integer	Table index.
`compName`	R	DisplayString	Component name.
`compOutput`	R	Component output name	Component name.
`compMajorVersion`	R	Gauge
`compMinorVersion`	R	Gauge
`compPatchVersion`	R	Gauge
`compRepository`	R	DisplayString	Repository name.
`compBuildNumber`	R	Gauge

compIndex

Integer

Table index.

compName

DisplayString

Component name.

compOutput

Component output name

Component name.

compMajorVersion

Gauge

compMinorVersion

Gauge

compPatchVersion

Gauge

compRepository

DisplayString

Repository name.

compBuildNumber

Gauge

SNMP agent command-line

SNMP agent (snmpd) switches

The SNMP agent that binds to a port and awaits requests from SNMP management software is snmpd. Upon receiving a request, snmpd processes the request, collects the requested information and/or performs the requested operation(s) and returns the information to the sender.

The SNMP agent supports a limited subset of command line switches that can be specified when starting the agent.

Usage

snmpd [-h] [-v] [-f] [-a] [-d] [-V] [-P PIDFILE):] [-q] [-D] [-p NUM] [-L] [-l LOGFILE] [-r]

This command can take the following options:

Option Description

Option	Description
`-h`	This option displays a usage message.
`-H`	This option displays the configuration file directives that the agent understands.
`-v`	This option displays version information.
`-f`	This option specifies not forking from the calling shell.
`-a`	This option specifies logging addresses.
`-A`	This option specifies that warnings and messages should be appended to the log file rather than truncating it.
`-d`	This option specifies the dumping of sent and received UDP SNMP packets.
`-V`	This option specifies verbose display.
`-P`	PIDFILE This option specifies the use of a file (PIDFILE) to store the process ID.
`-q`	This option specifies that information be printed in a more easily parsed format (quick print).
`-D`	This option turns on debugging output.
`-p`	NUM This option specifies running on port NUM instead of the default: 161.
`-c`	CONFFILE This option specifies reading CONFFILE as a configuration file.
`-C`	This option specifies that the default configuration files not be read.
`-L`	This option prints warnings and messages to stdout and err.
`-s`	This option logs warnings/messages to syslog.
`-r`	This option specifies not exiting if root-only accessible files cannot be opened.
`-I`	[-]INITLIST This option specifies a list of MIB modules to initialize (or not). Run `snmpd` with the `-Dmib_init` option for a list.
`-l`	LOGFILE This option prints warnings/messages to a file LOGFILE (by default, `LOGFILE=log/snmpd.log`).

-h

This option displays a usage message.

-H

This option displays the configuration file directives that the agent understands.

-v

This option displays version information.

-f

This option specifies not forking from the calling shell.

-a

This option specifies logging addresses.

-A

This option specifies that warnings and messages should be appended to the log file rather than truncating it.

-d

This option specifies the dumping of sent and received UDP SNMP packets.

-V

This option specifies verbose display.

-P

PIDFILE This option specifies the use of a file (PIDFILE) to store the process ID.

-q

This option specifies that information be printed in a more easily parsed format (quick print).

-D

This option turns on debugging output.

-p

NUM This option specifies running on port NUM instead of the default: 161.

-c

CONFFILE This option specifies reading CONFFILE as a configuration file.

-C

This option specifies that the default configuration files not be read.

-L

This option prints warnings and messages to stdout and err.

-s

This option logs warnings/messages to syslog.

-r

This option specifies not exiting if root-only accessible files cannot be opened.

-I

[-]INITLIST This option specifies a list of MIB modules to initialize (or not). Run snmpd with the -Dmib_init option for a list.

-l

LOGFILE This option prints warnings/messages to a file LOGFILE (by default, LOGFILE=log/snmpd.log).

Using the SNMP command-line utilities

As an alternative to using an SNMP manager application, we supply several command-line utilities to test your SNMP installation and enable you to obtain information about your nShield module from the SNMP agent. These utilities support the -h (display a usage message) as described in the table above.

Utility Description

Utility	Description
`snmptest`	This utility monitors and manages SNMP information.
`snmpget`	This utility runs a single GET request to query for SNMP information on a network entity.
`snmpset`	This utility runs a single SET request to set SNMP information on a network entity.
`snmpgetnext`	This utility runs a single GET NEXT request to query for SNMP information on a network entity.
`snmptable`	This utility obtains and prints an SNMP table.
`snmptranslate`	This utility translates SNMP object specifications into human-readable descriptions.
`snmpwalk`	This utility communicates with a network entity using repeated GET NEXT requests.
`snmpbulkwalk`	This utility communicates with a network entity using BULK requests.

snmptest

This utility monitors and manages SNMP information.

snmpget

This utility runs a single GET request to query for SNMP information on a network entity.

snmpset

This utility runs a single SET request to set SNMP information on a network entity.

snmpgetnext

This utility runs a single GET NEXT request to query for SNMP information on a network entity.

snmptable

This utility obtains and prints an SNMP table.

snmptranslate

This utility translates SNMP object specifications into human-readable descriptions.

snmpwalk

This utility communicates with a network entity using repeated GET NEXT requests.

snmpbulkwalk

This utility communicates with a network entity using BULK requests.

These tools are general purpose SNMP utilities and are configurable for use with other SNMP agents. For more information on configuring and using these tools, refer to the NET-SNMP project Web site: http://net-snmp.sourceforge.net/.