VxWorks Reference Manual : Libraries
loginLib - user login/password subroutine library
loginInit( ) - initialize the login table
loginUserAdd( ) - add a user to the login table
loginUserDelete( ) - delete a user entry from the login table
loginUserVerify( ) - verify a user name and password in the login table
loginUserShow( ) - display the user login table
loginPrompt( ) - display a login prompt and validate a user entry
loginStringSet( ) - change the login string
loginEncryptInstall( ) - install an encryption routine
loginDefaultEncrypt( ) - default password encryption routine
This library provides a login/password facility for network access to the VxWorks shell. When installed, it requires a user name and password match to gain access to the VxWorks shell from rlogin or telnet. Therefore VxWorks can be used in secure environments where access must be restricted.
Routines are provided to prompt for the user name and password, and verify the response by looking up the name/password pair in a login user table. This table contains a list of user names and encrypted passwords that will be allowed to log in to the VxWorks shell remotely. Routines are provided to add, delete, and access the login user table. The list of user names can be displayed with loginUserShow( ).
The login security feature is initialized by the root task, usrRoot( ), in usrConfig.c, if the configuration macro INCLUDE_SECURITY is defined. Defining this macro also adds a single default user to the login table. The default user and password are defined as LOGIN_USER_NAME and LOGIN_PASSWORD. These can be set to any desired name and password. More users can be added by making additional calls to loginUserAdd( ). If INCLUDE_SECURITY is not defined, access to VxWorks will not be restricted and secure.
The name/password pairs are added to the table by calling loginUserAdd( ), which takes the name and an encrypted password as arguments. The VxWorks host tool vxencrypt is used to generate the encrypted form of a password. For example, to add a user name of "fred" and password of "flintstone", first run vxencrypt on the host to find the encryption of "flintstone" as follows:
% vxencrypt please enter password: flintstone encrypted password is ScebRezb9cThen invoke the routine loginUserAdd( ) in VxWorks:loginUserAdd ("fred", "ScebRezb9c");This can be done from the shell, a start-up script, or application code.
When the login security facility is installed, every attempt to rlogin or telnet to the VxWorks shell will first prompt for a user name and password.
% rlogin target VxWorks login: fred Password: flintstone ->The delay in prompting between unsuccessful logins is increased linearly with the number of attempts, in order to slow down password-guessing programs.
This library provides a simple default encryption routine, loginDefaultEncrypt( ). This algorithm requires that passwords be at least 8 characters and no more than 40 characters.
The routine loginEncryptInstall( ) allows a user-specified encryption function to be used instead of the default.
loginLib.h
loginLib, shellLib, vxencrypt, VxWorks Programmer's Guide: Shell
loginInit( ) - initialize the login table
void loginInit (void)
This routine must be called to initialize the login data structure used by routines throughout this module. If the configuration macro INCLUDE_SECURITY is defined, it is called by usrRoot( ) in usrConfig.c, before any other routines in this module.
N/A
loginUserAdd( ) - add a user to the login table
STATUS loginUserAdd ( char name[MAX_LOGIN_NAME_LEN+1], /* user name */ char passwd[80] /* user password */ )
This routine adds a user name and password entry to the login table. Note that what is saved in the login table is the user name and the address of passwd, not the actual password.
The length of user names should not exceed MAX_LOGIN_NAME_LEN, while the length of passwords depends on the encryption routine used. For the default encryption routine, passwords should be at least 8 characters long and no more than 40 characters.
The procedure for adding a new user to login table is as follows:
- (1)
- Generate the encrypted password by invoking vxencrypt in host/hostOs/bin.
- (2)
- Add a user by invoking loginUserAdd( ) in the VxWorks shell with the user name and the encrypted password.
The password of a user can be changed by first deleting the user entry, then adding the user entry again with the new encrypted password.
-> loginUserAdd "peter", "RRdRd9Qbyz" value = 0 = 0x0 -> loginUserAdd "robin", "bSzyydqbSb" value = 0 = 0x0 -> loginUserShow User Name ========= peter robin value = 0 = 0x0 ->
OK, or ERROR if the user name has already been entered.
loginLib, vxencrypt
loginUserDelete( ) - delete a user entry from the login table
STATUS loginUserDelete ( char * name, /* user name */ char * passwd /* user password */ )
This routine deletes an entry in the login table. Both the user name and password must be specified to remove an entry from the login table.
OK, or ERROR if the specified user or password is incorrect.
loginUserVerify( ) - verify a user name and password in the login table
STATUS loginUserVerify ( char * name, /* name of user */ char * passwd /* password of user */ )
This routine verifies a user entry in the login table.
OK, or ERROR if the user name or password is not found.
loginUserShow( ) - display the user login table
void loginUserShow (void)
This routine displays valid user names.
-> loginUserShow () User Name ========= peter robin value = 0 = 0x0
N/A
loginPrompt( ) - display a login prompt and validate a user entry
STATUS loginPrompt ( char * userName /* user name, ask if NULL or not provided */ )
This routine displays a login prompt and validates a user entry. If both user name and password match with an entry in the login table, the user is then given access to the VxWorks system. Otherwise, it prompts the user again.
All control characters are disabled during authentication except CTRL-D, which will terminate the remote login session.
OK if the name and password are valid, or ERROR if there is an EOF or the routine times out.
loginStringSet( ) - change the login string
void loginStringSet ( char * newString /* string to become new login prompt */ )
This routine changes the login prompt string to newString. The maximum string length is 80 characters.
N/A
loginEncryptInstall( ) - install an encryption routine
void loginEncryptInstall ( FUNCPTR rtn, /* function pointer to encryption routine */ int var /* argument to the encryption routine (unused) */ )
This routine allows the user to install a custom encryption routine. The custom routine rtn must be of the following form:
STATUS encryptRoutine ( char *password, /* string to encrypt */ char *encryptedPassword /* resulting encryption */ )When a custom encryption routine is installed, a host version of this routine must be written to replace the tool vxencrypt in host/hostOs/bin.
The custom example above could be installed as follows:
#ifdef INCLUDE_SECURITY loginInit (); /* initialize login table */ shellLoginInstall (loginPrompt, NULL); /* install shell security */ loginEncryptInstall (encryptRoutine, NULL); /* install encrypt. routine */ #endif
N/A
loginLib, loginDefaultEncrypt( ), vxencrypt
loginDefaultEncrypt( ) - default password encryption routine
STATUS loginDefaultEncrypt ( char * in, /* input string */ char * out /* encrypted string */ )
This routine provides default encryption for login passwords. It employs a simple encryption algorithm. It takes as arguments a string in and a pointer to a buffer out. The encrypted string is then stored in the buffer.
The input strings must be at least 8 characters and no more than 40 characters.
If a more sophisticated encryption algorithm is needed, this routine can be replaced, as long as the new encryption routine retains the same declarations as the default routine. The routine vxencrypt in host/hostOs/bin should also be replaced by a host version of encryptionRoutine. For more information, see the manual entry for loginEncryptInstall( ).
OK, or ERROR if the password is invalid.
loginLib, loginEncryptInstall( ), vxencrypt