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.
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.
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:
| Codes | Explanation | Code generated by |
|---|---|---|
NC_RV_OK | Everything ok – password value received. | client, Success Code |
NC_RV_ILLEGAL_REQUEST | The 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_ERROR | Some error occurred while preparing request (no attempt to send request to server). | client, ErrorCode |
NC_RV_CONNECTION_FAILED | Preparing 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_RESPONSE | Server response received, but client is unable to understand (deserialize) server response. | client, ErrorCode |
NC_RV_SERVER_SIDE_ERROR | Some 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_UNKNOWN | Server could not find the pwdID in its database – unable to reply with pwd value. | server, ErrorCode |
NC_RV_PERMISSION_DENIED | The client application is not authorized to get this password/key. | server, ErrorCode |
NC_RV_USER_UNKNOWN | The user name for the client application's UID could not be found on the system. | server, ErrorCode |
NC_RV_SERVER_STOPPED | The nevisCred server is shutting down and no longer accepts client requests. | server, ErrorCode |
NC_RV_ILLEGAL_ID | The provided Id is not a valid nevisCred Id. | client, ErrorCode |
NC_RV_UNKNOWN_REQUEST | The 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:
| Permission | user(of entry) | admin(of entry) | super-user(all entries) | super-admin(all entries) |
|---|---|---|---|---|
| read credential | OK | |||
| list entry | OK | OK | OK | OK |
| add new entry | OK | OK | ||
| modify entry | OK | OK | ||
| remove entry | OK | OK |
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:
| Level | Severity | Description |
|---|---|---|
3 | error | initial error messages |
4 | errdesc | follow-up error messages |
5 | notice | items administrators should know |
6 | info | normal information level |
7 | debug | debug information |
In the configuration, the following tracing properties and TraceGroups are defined, also see the chapter on Configuration below.
| Name | Type | Component | Description |
|---|---|---|---|
ThresholdBase | 0 - 10 | The threshold base for all TraceGroups. | |
MaxLogFileVersions | integer | The number of rotated log files that will be written. | |
MaxLogFileSize | integer | The maximum size of a log file. | |
TimeFormat | ( ctime | detailed | time0 ) | The time format traced in the log file. | |
LogDir | string | The directory to which the log file shall be written | |
LogFile | string | The file (including the path) to which log messages shall be written | |
DebugProfile.cbc | 0 - 10 | CBC | C base component library |
DebugProfile.nc | 0 - 10 | nc | all nevisCred components |
DebugProfile.nc.adm | 0 - 10 | nc admin | the nevisCred admin tool |
DebugProfile.nc.core | 0 - 10 | nc core | the nevisCred core |
DebugProfile.nc.op | 0 - 10 | nc core | the nevisCred IPC operations |
DebugProfile.nc.srv | 0 - 10 | nc server | the 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.
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.
| Attribute | Type, Usage Constraints, Defaults | Description |
|---|---|---|
AdminIpcUrl | string, mandatory | IPC Url for admin requests |
The following table lists the configuration attributes that are recognized by both the server and the client.
| Attribute | Type, Usage Constraints, Defaults | Description |
|---|---|---|
ClientIpcUrl | string, mandatory | IPC Url for client requests, for example, ncGetPassword |
The following table lists the configuration attributes that are recognized only by the server.
| Attribute | Type, Usage Constraints, Defaults | Description |
|---|---|---|
PwdFilePath | string, mandatory | Path of file that contains the credentials |
MasterKeyFilePath | string, mandatory | Path of file that contains the master key value (if KeyMode is set to automatic) |
KeyMode | enumeration: automatic, manual; mandatory | manual: 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 |
PidFile | string, optional, default: /var/opt/neviscred/default/run/ncserver.pid | The 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.