Skip to main content
Version: 2.0.x

nevisCred nevisCred

Welcome to the nevisCred documentation.

Operating systems

The nevisCred package can be used on the following operating systems:

  • Red Hat Enterprise Linux x86 / x86_64 (RHEL), version 5 6, and 7
  • SUSE Linux Enterprise Server x86 / x86_64 (SLES), version 10, 11, and 12
  • nevisAppliance (pre-installed)

Concept Description and Technical Architecture

Architecture Overview

Introduction

This chapter provides a high-level, feature-oriented view of the nevisCred components and gives information about the context in which nevisCred can be used.

Background and Motivation

Passwords and keys (i.e. credentials) are an essential component in today's computer security not only for the end user but also for IT operation. Remembering long passwords is difficult and administrators who should have memorized the passwords are not always available. This may cause trouble if a sudden restart of services or whole servers (i.e.in the middle of the night) is required and nobody is around to enter the required password. Also, when starting multiple services on a server or when one service requires different passwords from within different unrelated components it is usually not feasible to have a person enter all these credentials.

To address these issues, many applications store the required passwords and keys as plain text or slightly obfuscated in their configuration files so as to protect them with the help of file permissions. For various reasons, this approach is not applicable for systems with high end security requirements.

nevisCred Design Goals

nevisCred was designed in line with the following design goals:

  • Minimal setup and runtime requirements on a single server
  • Close integration with the operating system and its security
  • Source code as platform independent as possible
  • Simple command line interface for administration
  • Ease of integration with client applications and services

nevisCred Feature Overview

nevisCred is a credential manager designed to solve the mentioned issues in a secure way by providing a service (or daemon) that runs permanently on the host, and supplies all applications with credentials whenever needed. nevisCred solves the given bootstrap problem in a secure manner and can be configured to start automatically after server reboot without the need of an administrator or with manual password input. nevisCred offers the following functionality:

  • nevisCred server running as a daemon guarding a set of credential entries
  • Access to credentials restricted to processes running on the local host
  • Single credential entry as granularity for the assignment of access rights
  • 4 roles authorization concept:
    • regular user (per entry)
    • administrator (per entry)
    • super-user (may add new entries)
    • super-administrator (may assign roles)
  • File based persistency (credential store 'pwdfile')
  • AES encryption of credentials (256-bit keys)
  • Keys for password encryption constructed from 3 different sources (MasterKey, HardCodedKey, PwdID)
    • Key is different for every credential entry in pwdfile
    • Same credential values look different in pwdfile
    • If one credential value is compromised, this doesn't compromise whole file
    • Customer can choose the master key value
    • Even if the master key and the hardcoded key are both compromised, an attacker would still need access to the binary or source code to access the passwords
  • The MasterKey is read from a master key file but can also be entered manually at startup
  • The pwdfile containing the credential entries is only needed during nevisCred service startup
    • Passwords are kept in memory in encrypted form
  • MasterKey and HardCodedKey are kept obfuscated in memory
    • De-obfuscation of MasterKey/HardCodedKey and decryption of a password only takes place if a password is requested
    • After processing a request, all key material is removed from memory
  • Possibility to store the pwd file on a USB memory stick, which can be removed and locked away after server startup (as long as passwords don't change)
  • Client application interface is simple and easy to use
  • AdminTool (command line tool) for managing the entries and their access rights sends admin requests to running service
  • Permission checks based on OS user names. Access control list is saved together with encrypted password values in pwdfile
  • Secure IPC between the clients and the nevisCred service to enable authentication that is based on the OS user of the client process
  • Special entry in password database for master key validation at startup time

Technical Architecture

This chapter provides a high-level view of the nevisCred architecture including a coarse-grained view of component internals as well as a detailed description of the concepts implemented.

Software Architecture

The following figure shows the overall architecture of nevisCred. It consists of a simple client server model restricted to local communication. The server runs like a daemon process and is intended to be started at boot time. Thus it is comparable to other daemons or local servers which are controlled by the operating system.

In addition to the regular „password-requesting" clients, an administration tool provides a command line interface for nevisCred administrator(s). The tool communicates with the daemon process using a separate channel.

nevisCred architecture overview

Software Layering and Implementation

nevisCred is implemented in C, primarily for the following reasons:

  • runtime size (compared to a virtual machine or an interpreter)
  • explicit use of operating system features (e.g. IPC and security)
  • portability

For portability and software quality reasons, the implementation is based on the AdNovum C Base Components library (CBC) which contains the Netscape Portable Runtime (NSPR) and has been successfully used in various projects including the Nevis SecStack. The CBC provides for an abstraction of the underlying operating system platform.

The common core of all nevisCred components sits on top of the CBC which is then used by the respective implementation of the three main parts: client, server and admintool.

Security

nevisCred security is based on two main mechanisms:

  • operating system security (OS users and their permissions)
  • encryption

Operating system security features are used for the identification and authentication of the users (clients) of the nevisCred server. A client that is required to retrieve credentials from the nevisCred server can do this based on its process identity because nevisCred uses a secure IPC mechanism for communication between client and server. This mechanism enables the server to verify the identity of each caller.

After the successful authentication, authorization to read or write credential records is granted by employing the built in authorization mechanism.

Encryption is used for protecting the credential data from unauthorized use and modification. This holds for credential data being stored in the so called pwdfile as well as for credential data held in memory by the nevisCred server. For encryption purposes, the respective algorithms from the OpenSSL library are used.

Installation and Integration

Installation

Prerequisites

The following requirements need to be fulfilled to install nevisCred on a Linux x86 machine:

  • ~10 MB of free space in the installation directory (usually /opt)
  • ~20 MB of free space in the spool directory (usually /var/opt)

Installation of nevisCred

Proceed as follows to install the package and start the server:

  • Install the package:
rpm -ivh neviscred-<version>-1.x86_64.rpm
  • If nevisCred was already installed, you may have to erase it first, or use -U to upgrade / --force to downgrade.
  • When doing an initial installation, perform the handover to create the default instance and start the server:
## neviscred handover

Software Upgrade

Proceed as follows to upgrade to a new software version without changing the configuration:

  • Deinstall the old package, see Deinstallation.
  • Install the new package, see chapter Installation.

We currently advise against usage of the upgrade flag on Linux platforms, as in rpm –U..

Deinstallation

Proceed as follows to remove the package:

rpm -e neviscred

Integration

Usage Patterns

nevisCred can be used in various contexts. The following figure provides some examples. To summarize: if an application needs any kind of credential, e.g., a password or a key to access a database or to unlock a certificate, this credential can be managed by nevisCred. Retrieval of the credential at runtime can be achieved by integrating the nevisCred client into the application and having it request the required credential from the nevisCred server. This way, credentials are stored in a secure manner and applications running on the same host can access the credentials anytime.

Example usage patterns
Client Example Usage Pattern

The ncclient command which is part of the nevisCred distribution can be used to retrieve credentials from within a UNIX shell by passing the ID of the requested credential as a command line argument:

ncclient mySpecialCredentialID | openssl genrsa -des3 -passout stdin

In this example, nccclient connects to the nevisCred server, retrieves the password and pipes it to another application (OpenSSL). No traces of the password are left behind. The password cannot be found in any file or environment variable, etc.

If ncclient cannot be found, try using its full path: /opt/neviscred/bin/ncclient.

Java Integration Usage Pattern

Java lacks the support for IPC mechanisms and OS security (file permission). Therefore, a simple possibility for integrating the nevisCred client within a Java virtual machine (e.g., into a Java EE container) consists of using Runtime.exec() for executing the ncclient command. When doing this, it is important to make sure that the environment is set up correctly if anything other than the default value is used:

  • NCCLIENT_CFG_FILE, see the chapter Client Configuration.
  • LD_LIBRARY_PATH

Be aware that when using Runtime.exec() from within a Java VM, there exists the potential problem of a large amount of memory (process image) being copied, as a result of the execution of a fork() system call. Howerver, this behaviour depends on the implementation of the Java VM on the respective platform. On Linux there are no known issues related to this topic.

The nevisCred C Client API

Functions

The ncClient Lib only exports two password getter functions and hides all other symbols.

char* nc_getPassword(constchar* pwdID, PRInt32* rc);
PRInt32 nc_getKey(const char* pwdID, char** keyBuf, PRInt32* keyLen);

getPassword: The first function assumes that the requested credential is a well-formed string (doesn't contain null values). It sets the error code in „rc" and returns null in case of an error.

getKey: The second function (getKey) is more general and can also handle binary credential values. It returns a detailed error code. Possible success/error codes of the functions are explained in the [table] below, Success/error codes of the getKey function.

Return Values

The table below lists the possible success/error codes of the getPassword and getKey functions:

CodesExplanationCode generated by
NC_RV_OKEverything ok – password value received.client, Success Code
NC_RV_ILLEGAL_REQUESTThe client could not create (serialize) a well-formed server-message or the server was unable to understand (deserialize) it or the server could not get the client application's user info.client, server, ErrorCode
NC_RV_CLIENT_SIDE_ERRORSome error occurred while preparing request (no attempt to send request to server).client, ErrorCode
NC_RV_CONNECTION_FAILEDPreparing request ok, but could not connect to server (server might not be running; might have stopped (shutdown init) or wrong IPC URL in configuration file).client, ErrorCode
NC_RV_BAD_RESPONSEServer response received, but client is unable to understand (deserialize) server response.client, ErrorCode
NC_RV_SERVER_SIDE_ERRORSome error on server side (this means that the request was sent by client and received by server – server response was a generic error code or empty).client, ErrorCode
NC_RV_PWD_ID_UNKNOWNServer could not find the pwdID in its database – unable to reply with pwd value.server, ErrorCode
NC_RV_PERMISSION_DENIEDThe client application is not authorized to get this password/key.server, ErrorCode
NC_RV_USER_UNKNOWNThe user name for the client application's UID could not be found on the system.server, ErrorCode
NC_RV_SERVER_STOPPEDThe nevisCred server is shutting down and no longer accepts client requests.server, ErrorCode
NC_RV_ILLEGAL_IDThe provided Id is not a valid nevisCred Id.client, ErrorCode
NC_RV_UNKNOWN_REQUESTThe server received a message of an unknown type.server, ErrorCode
Client Code Example
####include "neviscred/corefuncs/client.h"
/*-----------------------nc_getPassword() example ---------------------*/
{
char* password = NULL;
PRInt32 rc = 0;
password = nc_getPassword(ncIPCT_parameter, &rc);
if (password != NULL) {
/* do something useful with pwd ... */
deleteValue(password, PL_strlen(password));
PR_FREEIF(password);
}
}
/-----------------------nc_getKey() example ---------------------/
{
char* key = NULL;
PRInt32 keyLen = 0;
PRInt32 responseCode = 0;
char* responseString = NULL;
responseCode = nc_getKey(ncIPCT_parameter,
&key, &keyLen);
responseString = ncCore_codeToString(responseCode);
if (responseCode == NC_RV_OK) {
/* do somthing useful with key ... */
deleteValue(key, keyLen);
PR_FREEIF(key);
}
}

Sample Configuration

nevisCred Server

This is an example for a server configuration exactly as it would appear in the file: ncserver.ini in /var/opt/neviscred/default/server/conf:

SchemaDirs = /opt/neviscred/schema

########### NC SERVER ########

[NcServer]
PwdFilePath = "/var/opt/neviscred/default/pwdFile"
MasterKeyFilePath = "/var/opt/neviscred/default/server/.masterKeyFile"
ClientIpcUrl = "unix:///var/opt/neviscred/default/client/neviscred_client_socket"
AdminIpcUrl = "unix:///var/opt/neviscred/default/neviscred_admin_socket"
KeyMode = "automatic"
PidFile = /var/opt/neviscred/default/log/ncserver.pid

[TraceChannel.NcServer]
FileConsumers = NcServer
TimeFormat = detailed
ThresholdBase = 5
DebugProfile.cbc = 0
DebugProfile.nc = 0
DebugProfile.nc.srv = 0

[FileConsumer.NcServer]
LogFile = /var/opt/neviscred/default/log/ncserver.log
MaxLogFileVersions = 10
MaxLogFileSize = 10000000
nevisCred Client

This is an example of a client configuration taken exactly as it appears in the file ncclient.ini in /var/opt/neviscred/default/client/conf:

SchemaDirs = /opt/neviscred/schema

########### NC CLIENT ########

[NcClient]
IpcUrl = "unix:///var/opt/neviscred/default/client/neviscred_client_socket"

[TraceChannel.NcClient]
FileConsumers = NcClient
TimeFormat = detailed
ThresholdBase = 5
DebugProfile.cbc = 0
DebugProfile.nc = 0
DebugProfile.nc.core = 0
DebugProfile.nc.op = 0

[FileConsumer.NcClient]
LogDir = /tmp
MaxLogFileVersions = 2
MaxLogFileSize = 5000000

Operation and Administration

The nevisCred Command Line Interface

The nevisCred server is managed via the command interface neviscred. Enter neviscred to display a list of available commands:

For security and operational reasons, the neviscred command interface is usually invoked via a wrapper (sudo or op depending on the platform and the policies of the customer). This means that all instance related commands mentioned below need to be prefixed with either sudo or op. The admin commands will not be executed as root, since neviscred will check user permissions based on its own access control data.

usage:
neviscred # get this usage

neviscred server:
neviscred [instance] start # start nevis credential server
neviscred [instance] stop # shutdown nevis credential server
neviscred [instance] restart # shutdown and start nevis credential
server
neviscred [instance] status # show state of nevis credential server


neviscred admin: # nevis credential administration
neviscred [instance] admin [-v] add -id <id> -user <user> -admin <admin>
[-user <user> | -admin <admin>]* [-cred <cred>]
neviscred [instance] admin [-v] remove -id <id>
neviscred [instance] admin [-v] modify -id <id> [-user <user> | -admin <admin>]
[-xuser <user> | -xadmin <admin>]* [-cred <cred>]
neviscred [instance] admin [-v] list [-id <id>]*

administration:
neviscred [instance] config # configure server
neviscred [instance] config server # configure server
neviscred [instance] config client # configure client
neviscred [instance] config admin # configure admin
neviscred [instance] config env # edit startup arguments
neviscred [instance] config export # export configurations
neviscred [instance] config import <tarfile> # import configurations from <tarfile>
neviscred [instance] config backup # backup actual configurations
neviscred [instance] config restore # restore last backup

neviscred [instance] log # display list of logfiles
neviscred [instance] log err [all|<logname>] # display errors in logfiles (default: all)
neviscred [instance] log show [all|<logname>] # display logfiles (default: all)
neviscred [instance] log tail [<logname>] # start tailing logfile (default: server)

neviscred [instance] analyse [all] # collect support info from servers and host

neviscred handover [-user <user>]* # create default instance and start server

neviscred inst # list all instances
neviscred inst create <name> [1] # create an instance
neviscred inst remove <name> # remove an instance
neviscred pkg # show installed package versions
neviscred pkg activate <version> # activate specified version of package


[1] specifies an optional setup.conf or a list of VAR=VALUE arguments
'neviscred inst create test help' displays

Server Handling

Starting and Stopping the Server

neviscred start

neviscred start is used for starting the nevisCred server process. If you are using the manual mode (instead of automatic), you will be asked for the passphrase.

Example
svnc# neviscred start
neviscred [MESSAGE]: default>> Starting server 'ncserver'....
-------------------------------------------------------------------------
Status : UP
Component : neviscred / 1.0.1.0
Instance : default
Process : ncserver
Ownership : ncuser / ncgroup
Filedescriptors : 4096
Process ID : 8013
Logfile(s) : /var/opt/neviscred/default/log/ncserver.log
-------------------------------------------------------------------------
neviscred stop

neviscred stop is used to shutdown the nevisCred server process.

Example
svnc# neviscred stop
neviscred [MESSAGE]: default>> Shutting down server on pid 8013....
neviscred [MESSAGE]: default>> Server processes 'ncserver' terminated.
-------------------------------------------------------------------------
Status : DOWN
Component : neviscred / 1.0.1.0
Instance : default
Process : ncserver
Ownership : ncuser / ncgroup
Filedescriptors : 4096
Logfile(s) : /var/opt/neviscred/default/log/ncserver.log
-------------------------------------------------------------------------
neviscred restart

neviscred restart stops nevisCred, and then starts it again.

Example
svnc# neviscred restart
neviscred [MESSAGE]: default>> Shutting down server on pid 8461....
neviscred [MESSAGE]: default>> Server processes 'ncserver' terminated.
neviscred [MESSAGE]: default>> Starting server 'ncserver'....
-------------------------------------------------------------------------
Status : UP
Component : neviscred / 1.0.1.0
Instance : default
Process : ncserver
Ownership : ncuser / ncgroup
Filedescriptors : 4096
Process ID : 8734
Logfile(s) : /var/opt/neviscred/default/log/ncserver.log
-------------------------------------------------------------------------

Retrieving Status Information

neviscred status

neviscred status provides runtime information on the server, i.e., the process id, the number of file descriptors configured, the nevisCred version being used and the log files that are written.

Example
svnc# neviscred status
-------------------------------------------------------------------------
Status : UP
Component : neviscred / 1.0.1.0
Instance : default
Process : ncserver
Ownership : ncuser / ncgroup
Filedescriptors : 4096
Process ID : 8734
Logfile(s) : /var/opt/neviscred/default/log/ncserver.log
-------------------------------------------------------------------------

nevisCred Admin Tool

Entries managed by the nevisCred server are referenced by unique identifiers referred to as 'id'. For authorization handling each entry contains a list of 'users' (those who are allowed to read the entry, i.e., the decrypted credential stored in the entry) and 'administrators' (those who are allowed to modify the entry). For the user and admin parameters only existing UNIX users on the actual system should be selected. For 'global' permissions, such as adding new entries to the credential store, there exists an entry with the id '0'. The users and admins defined in the 'entry 0 ACL' are termed 'super-user' and 'super-admin' in the table:

Permissionuser(of entry)admin(of entry)super-user(all entries)super-admin(all entries)
read credentialOK
list entryOKOKOKOK
add new entryOKOK
modify entryOKOK
remove entryOKOK

Credential Modification

neviscred admin add

neviscred admin add can be used to add a new credential entry to the nevisCred server. Only a system user with super-administrator or super-user rights for nevisCred can add an entry (Chapter 1.4.2.1, neviscred admin modify -id=0).

Example
svnc# neviscred admin add -id myFirstEntry -user user1 -admin sysadmin\
-cred Huf87bqe43be

In this example the UNIX user user1 will be able to retrieve the credential with id myFirstEntry, whereas the UNIX user sysadmin can modify it.

Note that using neviscred admin add as shown in the example above there might be traces of the credential passed on the command line in places like the shell history (e.g., $HOME/.bash_history) or the syslog (e.g., when using sudo).

For this reason a mode for interactive credential input exists which can be triggered by omitting the -cred command line argument.

Example
svnc# neviscred admin add -id myFirstEntry -user user1 -admin sysadmin
Enter credential/password for id 'myFirstEntry':
Verifying - Enter credential/password for id 'myFirstEntry':

neviscred admin remove

neviscred admin remove can be used to remove a credential entry from the nevisCred server. Only a system user with admin rights for the respective entry or a super-admin can remove the entry.

Example
svnc# neviscred admin remove -id myFirstEntry

neviscred admin modify

neviscred admin modify can be used to modify an existing credential entry on the nevisCred server. The given access role arguments will be merged with the existing entry, the credential value will be overwritten. Only a system user with admin rights for the respective entry or a super-admin can modify the entry.

Example
svnc# neviscred admin modify -id myFirstEntry -user user1 -admin sysadmin \
-admin root -cred Huf87bqe43be222
svnc# neviscred admin modify -id myFirstEntry -xadmin root

Other Commands

neviscred admin modify -id=0

neviscred admin modify can also be used to modify the list of super-administrators and super-users on the nevisCred server by specifing the special id "0". As described above, only the super-administrators (listed as 'admins' of id "0") are allowed to change this entry.

Example
svnc# neviscred admin modify -id=0 -admin user1 -user sysadm -user credadm

In this example the UNIX user user1 is added as super-adminstrator of the neviscred pwdFile whereas the UNIX users sysadm and credadm can create new entries in it.

neviscred admin list

neviscred admin list can be used to print a listing of the entries for which the caller has either user or admin rights. The credential value is not printed.

Examples
svnc# neviscred admin list
0 [root]: root
myId [user1,root]: user1
test [user1]: user1
svnc# neviscred admin list -id mySecondEntry
mySecondEntry ERROR 'Id not found'

Configuration Files

Command overview

The nevisCred command interface offers the following commands for configuration:

  • neviscred config neviscred config server# edit server configuration (ncserver.ini)
  • neviscred config client# edit client configuration (ncclient.ini)
  • neviscred config admin# edit admin configuration (ncadmin.ini)

All of these commands open the respective configuration files in rvi (restricted vi). You therefore need to know vi commands to be able to edit the file. If you don't, enter :q! for quitting the editor without any changes.

ncserver.ini

The configuration file for the nevisCred server. For a detailed description of the recognized config attributes, see the chapter Server Configuration.

ncclient.ini

The configuration file used by clients for credential retrieval. For a detailed description of the recognized config attributes see the chapter Client Configuration.

ncadmin.ini

The configuration file used by the nevisCred admin tool, see the chapter nevisCred Admin Tool. For a detailed description of the recognized config attributes see the chapter Admin Configuration.

Remember to restart your nevisCred server with neviscred restart if you change the server configuration.

Backup and Restore

neviscred config backup

neviscred config backup creates a tar archive of the current configuration and stores it in /var/opt/neviscred/default/backup/conf.${TIMESTAMP}.tar.

Example
svnc# neviscred config backup
neviscred [MESSAGE]: Backup existing configuration.
neviscred [MESSAGE]: Exporting configuration to
/var/opt/neviscred/default/backup/conf.2006-12-31-17:24:07.tar....
neviscred [MESSAGE]: Export done.
neviscred [MESSAGE]: Backup done.

neviscred config restore

neviscred config restore restores the last backup.

Remember to restart your nevisCred server with neviscred restart if you change the server configuration.

Viewing Log Files

nevisCred writes the following log files:

  • /var/opt/neviscred/default/log/ncserver.log This file contains the nevisCred log and tracing messages.
  • /var/opt/neviscred/default/log/ncadmin.log This file contains the log and tracing messages of the nevisCred admin tool.

neviscred log

neviscred log prints the list of available log files.

Example
svnc# neviscred log
server: /var/opt/neviscred/default/log/ncserver.log
admin : /var/opt/neviscred/default/log/ncadmin.log

neviscred log err

neviscred log err prints the error entries in the respective log file.

Example
svnc# neviscred log err server
root@adnwsrs10:/var/opt/neviscred> neviscred log err server
-------------------------------------------------------------------------
File: /var/opt/neviscred/default/log/ncserver.log
Host: adnwsrs10
Date: Sun Dec 31 17:34:35 CET 2006
Filter: rror|ERROR
-------------------------------------------------------------------------
2006 12 31 16:27:19.961 ncserver cbc.ipc 08734.7904 3-ERROR :
cbcIpc_ClientInfo_ruidIsSet: ruid is not supported
2006 12 31 16:27:19.963 ncserver cbc.ipc 08734.7904 3-ERROR :
cbcIpc_ClientInfo_rgidIsSet: rgid is not supported

neviscred log show

neviscred log show prints the the respective log file.

Example
svnc# neviscred log show server
-------------------------------------------------------------------------
File: /var/opt/neviscred/default/log/ncserver.log
Host: adnwsrs10
Date: Sun Dec 31 17:37:10 CET 2006
-------------------------------------------------------------------------
2006 12 29 19:34:46.116 ncserver nc.srv 00966.9472 5-NOTICE: main:
Server config file was successfully internalized.
2006 12 29 19:34:46.116 ncserver nc.core 00966.9472 5-NOTICE:
ncCore_new_ServerCtx: Server Config stucture was successfully initialized.
2006 12 29 19:34:46.116 ncserver nc.core 00966.9472 5-NOTICE:
ncCore_new_ServerCtx: caching password file successful.
2006 12 29 19:34:46.117 ncserver nc.srv 00966.9472 5-NOTICE:
main: Starting nevisCred Server...

neviscred log tail

neviscred log tail starts tailing the respective log file.

Logging and Tracing

nevisCred uses a logging subsystem from the CBC library which has some similarities to the syslog facility. Each of the components has its own logging configuration in respective sections of the configuration file(s).

Log messages contain a severity and are written to trace groups. For each tracegroup, one of the threshold levels listed below (which is actually a message) is written to the consumer and can be defined.

For the mapping between the level of TraceGroups and the severity printed into the log file, see the following table:

LevelSeverityDescription
3errorinitial error messages
4errdescfollow-up error messages
5noticeitems administrators should know
6infonormal information level
7debugdebug information

In the configuration, the following tracing properties and TraceGroups are defined, also see the chapter on Configuration below.

NameTypeComponentDescription
ThresholdBase0 - 10The threshold base for all TraceGroups.
MaxLogFileVersionsintegerThe number of rotated log files that will be written.
MaxLogFileSizeintegerThe maximum size of a log file.
TimeFormat( ctime | detailed | time0 )The time format traced in the log file.
LogDirstringThe directory to which the log file shall be written
LogFilestringThe file (including the path) to which log messages shall be written
DebugProfile.cbc0 - 10CBCC base component library
DebugProfile.nc0 - 10ncall nevisCred components
DebugProfile.nc.adm0 - 10nc adminthe nevisCred admin tool
DebugProfile.nc.core0 - 10nc corethe nevisCred core
DebugProfile.nc.op0 - 10nc corethe nevisCred IPC operations
DebugProfile.nc.srv0 - 10nc serverthe nevisCred server

Configuration

A configuration is defined per channel (in a TraceChannel.<name> section) where in the case of nevisCred a channel refers to exactly one component.

Trace Channel Configuration

The following example of the admin tool illustrates the configuration of a trace channel which writes output to a file:

[TraceChannel.NcAdmin]
FileConsumers = NcAdmin
TimeFormat = detailed
ThresholdBase = 5
DebugProfile.cbc = 0
DebugProfile.nc = 0
DebugProfile.nc.adm = 0

File Consumer Configuration

The following example of the AdminTool illustrates the configuration of a file consumer which complements the configuration section shown in the chapter Trace Channel Configuration:

[FileConsumer.NcAdmin]
LogFile = /var/opt/neviscred/default/log/ncadmin.log
MaxLogFileVersions = 10
MaxLogFileSize = 10000000

Configuration

Components

Overview

This figure shows all the nevisCred components and their interactions.

nevisCred components

Server

The nevisCred server is the centerpiece of a nevisCred installation and runs as a single process comparable to a daemon on the host machine. nevisCred is responsible for safeguarding the credentials and providing them to its clients depending on the results of authorization checks which are performed for each request handled by the server.

For communication purposes the server provides an IPC channel for both the regular clients and the admin client. The type of this IPC channel depends on the platform beneath:

  • Linux: UNIX Domain Sockets
Server Configuration

The server configuration is placed in the NcServer section of the respective ini file. The location of the server ini file can be configured by setting the environment variable NCSERVER_CFG_FILE or by using the -NC_CFGfile command line argument of the ncserver executable. As a default, the server configuration is loaded from /var/opt/neviscred/default/server/conf/ncserver.ini. However, for the normal use of the nevisCred server, the adressing of the server config file is done by the wrapper script. Thus it is transparent to the user.

For more details about configuration files see the chapter Configuration Files.

The following table lists the configuration attributes that are recognized by both the server and the admin tool.

AttributeType, Usage Constraints, DefaultsDescription
AdminIpcUrlstring, mandatoryIPC Url for admin requests

The following table lists the configuration attributes that are recognized by both the server and the client.

AttributeType, Usage Constraints, DefaultsDescription
ClientIpcUrlstring, mandatoryIPC Url for client requests, for example, ncGetPassword

The following table lists the configuration attributes that are recognized only by the server.

AttributeType, Usage Constraints, DefaultsDescription
PwdFilePathstring, mandatoryPath of file that contains the credentials
MasterKeyFilePathstring, mandatoryPath of file that contains the master key value (if KeyMode is set to automatic)
KeyModeenumeration: automatic, manual; mandatorymanual: the master key has to be entered during startup of the server or the AdminTool, automatic: nevisCred reads the password from the file specified using the MasterKeyFilePath entry
PidFilestring, optional, default: /var/opt/neviscred/default/run/ncserver.pidThe file to which the process id of the nevisCred server is written at startup

Client

The nevisCred client is provided in three characteristics:

  • a command line client: ncclient
  • a C client library offering a public API
  • a Java client library offering a public API

where the command line client and the Java client library are built upon the C client library. Client integration aspects are described in the chapter Integration.

Client Configuration

The client configuration is placed in the NcClient section of the respective ini file. The location of the client ini file can be configured by setting the environment variable NCCLIENT_CFG_FILE. As a default the client configuration is loaded from /var/opt/neviscred/default/client/conf/ncclient.ini.

For more details about configuration files see the chapter Configuration Files.

Client configuration parameters that are shared with the server are listed in the table Server and client configuration above.

AdminTool

As depicted in the figure nevisCred component above, the AdminTool communicates with the server (using the admin IPC channel), which then writes the pwdFile. For this purpose, it uses the functionality and structures provided by the ncCore library. The server is responsible for writing any modifications to the file.

Admin Configuration

The admin configuration is placed in the NcAdmin section of the respective ini file. The location of the admin ini file can be configured by setting the environment variable NCADMIN_CFG_FILE. As a default, the client configuration is loaded from /var/opt/neviscred/default/admin-conf/ncadmin.ini.

For more details about configuration files see the chapter Configuration Files.

Admin configuration parameters that are shared with the server are listed in the table Server and AdminTool configuration above.

Upgrading from nevisCred 1.x.x.x to 2.x.x.x

Migrating from a nevisCred setup with a major version 1 to a nevisCred setup with a major version 2 is straight forward. Simply uninstall the old version keeping its configuration files and install the new version. Refer to the appropriate guidelines for your platform in the nevisCred Reference Guide on how to install/remove nevisCred and where the configuration files (spool) are located. You need to pay attention to the super-admin and super-user of the previous installation, as well as to with which user the previous installation was running:

  • To find out the runtime user of nevisCred, execute "neviscred status" and take note of the line "Ownership", e.g.:
--------------------------------------------------------------------------------
Status : UP
Component : neviscred/ 2.0.9.0
Instance : default
Process : ncserver
Ownership : bin / bin
Filedescriptors : 4096
Process ID : 14023
Logfile(s) : /var/opt/neviscred/default/server/log/ncserver.log
--------------------------------------------------------------------------------

  • To find out which users make up the super-user/super-admin, you can execute neviscred admin list –id=0. If you don't get an entry, you may need to switch to the runtime user of the ncserver process.

  • The super-admin(s) will be listed within square brackets.

  • The super-user(s) will be listed after the colon.

Only the current super-admin(s) and super-user(s) will be allowed to add new entries after the migration.