BatchLogin (2.0) Configuration Specification

[Back] First a little history. The BatchLogin program is a toolkit to allow a user with access credentials to document just where those credentials are good, how to get there and finally allow easy execution of small scripts in the a complex network environment. Since a lot of secure enterprise network environments are extremely complex and showing no signs of getting simpler, this is no small feat.

More information on the whys and hows of BatchLogin can be obtained by reading the FAQ.

BatchLogin 1.0 was some 1500 lines of shell code and some 700 or so lines of expect. Due to the method of conception, the program had inherent limitations that were obvious to the users.

BatchLogin 1.0 allowed a user to do the following:

Maintain an MD4 encrypted password list and connection method
Easily run a simple shell script across all of these servers
Easily run expect sessions through a loop of servers
Handle weird termservers, even ones that prompt for RSA authentication. (in development, currently)
Batch Login Terminal (BLT), which allowed easy login into one (or many) server(s) in a users' config file.
GROUP_group.txt -- BLT subgrouping external to a password configuration file.

Unfortunately, BatchLogin 1 had issues:

It didn't handle failure very well.
Config files were a mess (already mentioned).
Data was replicated throughout the configuration.
Configuration files were monolithic entities that could not easily be shared with another user due to user-specific configuration being contained within the file.
The authentication and configuration was inflexible, requiring major rewriting of the core code to address simple situations like differing environments or strange accessibility situations.
Groups were only applicable to the command-line terminal (blt).
There was no easy way to execute multiple scripts across an environment, and no easy way to select multiple password lists for execution.

The original BatchLogin program used a completely different configuration syntax for specifying a login or connection method. It went something like this:

[server] [gateway] "Bunch,of_connection,Junk" [password]

Yeah, it was a mess.

Anyway, it was decided after banging around with this, and more or less making it fit just about any authentication/login strategy, that a completely different approach was needed.

BatchLogin needed a major rewrite anyway, as it had grown to some 650 lines of code, some of which was pretty good, and some that wasn't fit for /dev/null ...

BatchLogin 2.0 was created to address these limitations. A more or less total rewrite was in order, as the programs theoretical limitations were strongly ingrained in the way the solution was conceived.

The new program is mostly a rewrite, although the look and feel of the interface is similar enough that familiar users will find very little in the way of functional differences. BatchLogin 2 comprises approximately 3000 lines of shell code, around 1200 lines of Java (Swing) and over 3000 lines of expect.

BatchLogin 2.0 brings the following features:

Human-readable, consistent configuration file format.
Blowfish-encrypted configuration files.
Authentication traversal (try passwords till a good one is found).
Password healing upon authentication failure (update to newest password).
User credential abstraction.
Improved BLT functionality.
Improved GROUP functionality.
Ability to run multiple scripts in a session (using the Java UI)
Multiple password lists in a session.
Easy password change on encrypted files.
Encrypted log files using a public key encryption key set.
Ability to transfer (either way) files using uuencode/uudecode
Ability to have a passlist "tree" (one list can pull in another)
Cyber-ark connectivity: passlists can reference cyber-ark to pull passwords, in other words.
BLT passlist caching. BLT now "remembers" the last place it found a label, and only prompts the user for the matching passlist one time.
Java/swing configurator (point and click expect, an abomination!) (in development)

Configuration Specification

In general, a BatchLogin configuration specification takes the following form:

LABEL:
ORIGIN:
METHOD
SERVER
USER (or reference LABEL:)
PASSWORD (or reference LABEL:)

The label specification: LABEL:

The LABEL: is a marker for the configuration line itself. Labels are meant to be human-readable and are case insensitive.

The label origin specification: ORIGIN:

This is the place from which BatchLogin starts the connection session for the specified line. If the label is the special label "START:" (case insensitive), then BatchLogin starts from the actual machine where the session is running. If the label references another label in the configuration, then BatchLogin starts there, and once authenticated at that level, executes the configuration.

Note that with this methodology several things occur. It's possible to describe just about any series of hops to get to a server, including multiple hops through gateways with as many id/password combinations as is possible along the way.

The METHOD: configuration specification

Note that the method used is kind of a misnomer. In most cases it will be secure shell (ssh), but in some cases it may be a user switch context (su). Telnet and termservers are supported as well. From there, however, the method gets more complex.

The "auth" method isn't a connection method at all -- it's a set of credentials describing a username/password combination. Here's an example "auth" configuration loop:

MYRACF:  RACFA:  auth  _ LOGNAME p4ssw0rd
RACFA:   RACFB:  auth  _ LOGNAME OlDp4swd
RACFB:   RACFC:  auth  _ LOGNAME P4wd2mth
RACFC:   RACFD:  auth  _ LOGNAME P3mth0ld

Note that the way to read this is as follows: When a configuration line calls the "myracf:" auth credential set, it tries the first password (in this case "p4ssw0rd"). If it fails to authenticate with that set, it tries the second set of credentials in the loop (referenced at the racfa: label, in this case OlDp4swd is tried), and so on until it either authenticates, or runs out of credentials, in which case the subroutine attempting authentication returns an error.

If the session authenticates with the new password, it continues as usual. If the session authenticates with any one of the old ones, the user will be given the chance to update their password on that machine, or the password for the id in question, if it's an SU event to a non-human or root id, for example.

The user has a limited time to respond to this question. There are variables that can be set to control all of the aspects of this portion of the program. It's possible, for example, to tell BatchLogin to wait for 60 seconds if it encounters such a question, and if the user has not responded, go on without a password reset. Or, the desirable behavior may be to update automatically.

These options essentially automate the drudgery of having to keep credentials consistent across multiple servers.

A configuration line that utilizes the above authentication loop might look like this:

server: start: ssh  server  myracf:  myracf:

The username and password have been "abstracted" into a totally different set of configuration lines this way. Possibly even a different file, because BL2 has the ability to include passlists in other passlists, and the user has the ability (at run time) to specify multiple passlists in general.

He's a sample configuration line for a server called, myserver:

myserver: START: ssh myserver LOGNAME El33th4x0r

Using these features and the concept of "hops" (multiple configuration lines that reference a gateway server for connections into the iDMZ, it's possible to bounce through as many servers as need be to arrive at a destination.

The above configuration is read as "To connect to myserver: (note that this is the user's name for the connection, and not the domain name of the server itself), the program initializes the ssh program from wherever BatchLogin is running from (hence the "START:" label, which is a special label -- the rest are up to user's own naming convention), and uses the ssh protocol to connect to myserver. Note that this is the domain/hostname or even the ip address of the actual machine. The line specifies that a login name of "LOGNAME" (which maps to the users login name at run-time) will be used. It is possible to hard-code user names, but LOGNAME provides for portability.

It is possible to make BL2 ask the user at runtime for the password for a connection. Here's a sample configuration line:

FERRIPI: PROMPT: AUTH * LOGNAME _

Note that the reference label (PROMPT:) is ignored, and shown here as "PROMPT:" simply to make it easier to understand. In this case, it knows the server that it's attempting to log onto, but it doesn't know the password.

Asterisks (*) are utilized in the configuration to signify items that BL2 should ignore.

Underscores (_) are utilized in the configuration to signify items that BL2 should ask for. It's entirely possible to configure a generic ssh hop like this:

SSHEXAMP: START: SSH  _  _  _

This would tell BL2 to ask the user for the machine to secure shell to, the username and the password (all of them, in other words):

Enter hostname or IP for connection: company06someplace
Enter username for connection label SSHEXAMP:: ferripi
Enter password for connection label SSHEXAMP:: [password]

The password will be "cached" during the running of the session. In other words, if other servers utilize the AUTH credential set labeled "FERRIPI:", the password will not be asked for again. Instead the program will remember that this password was asked for, and use it again. This is only good for the running of the session. End the program and the memory of this password dies along with it.

A more complex example

In the access manager environment, it's necessary to log into a remote server via an ssh gateway. The following two lines illustrate how this might be easily configured:

SSHGW1: START: ssh GW04 FERRIPI: FERRIPI:
ambox1: SSHGW1: ssh ambox1 LOGNAME "myk3ypw1"

Note that the login to this box may still require one password (the AUTH credential might prompt for one, or possibly the credentials will be a loop labeled by FERRIPI:) The final piece, switching to root, is accomplished with another line like this one:

ambox1_su: ambox1: su * root "myr00tpw"

Also note that it's possible to have BatchLogin prompt for a password at this point as well, but that that would more or less make it a glorified method connection program. In any case, even that might be more desirable than having to memorize machine locations and convoluted hops through gateways.

Supported methods of connection and interface events

Currently, BatchLogin supports the following connection methods:

SSH (openssh, or ssh2) Secure shell.
TELNETStandard (insecure) Unix telnet access (See also: Termserver Support).
SU Not really a connection method, a switch user function.
AUTH Documents a credential set (username/password).
PASSLIST A reference to another password list.

Note that the SU, AUTH and PASSLIST methods are not in effect connection methods. The SU Method executes a Unix "su" and the AUTH and PASSLIST methods document login and password credentials.

Termserver Support Under the Telnet Connection Method.

Termservers accessed via telnet can be coded via alternate "NODENAME" specifiers. Since BatchLogin is sensitive to what node it is connected to (Several features check this value agains "uname -n"), it's important that a termserver connection matches.

The syntax uses commas' as a delimiter, and looks like this:

LABEL: ORIGIN: TELNET nodename,TSTYPE,TSVALUE1,TSVALUE2,...,TSVALUEN,END USERNAME PASSWORD

So, for example, a typical term servers that accesses a node foobar, which is available on ts6, port 2001:

ts_foobar: start: TELNET foobar,TS1,ts6,2001,END root cyber_foobar:

Other termserver types, besides type 1, mentioned above, will be added.

An AUTH configuration line has the following components:

LABLE: REF:   AUTH * [username] [password]

Note the asterisk (*) in the configuration. AUTH configuration lines do not use this field, so the (*) is a place-holder only. The username and password are pretty self-explanatory, but what's the "REF:" label for?

AUTH configuration lines "chain" in a similar fashion to connection method configurations, only in reverse. The determining factor is the validity of the credentials, and not the success of connection. In other words, a connection loop is a series of successive hops, each one executed on the success of the prior hop. An authorization loop is the reverse -- a series of successive login tries, each one executed on the failure of the prior try.

This allows a user to set a new password into the chain, succeeding the prior passwords, and by simply logging into the servers where the passwords are managed, the user is given the ability to update to a new password without all the fuss of cutting, pasting or getting the password key-in correct each time. A PASSLIST configuration line has the following components:

LABLE: EXT:  PASSLIST [LOCAL|CYBERARK] [FILE] [password]

The reference label is completely unused. A recommendation is to always put the abbreviation "EXT:" in the reference column, since it points outside of the bounds of the configuration file (it's the only type of label to do so.

The forth parameter is one of:

LOCAL
Another passlist:
The passlist is in the users ~/.batch2/passlists directory. The complete filename with the extension needs to be specified.
CYBERARK
A passlist stored in a cyberark safe:
In this case, the FILE reference will specify the cyberark safe and the full path to the file. For example, somenode in the USOscratch safe would be referenced like this: USOscratch:somenode.blf

The password column is the password needed to decrypt the file. This column may also utilize an underscore so that the user can be prompted for the password at run-time.

Cyberark Passlist Configuration Specification

LABEL: REF: PASSLIST CYBERARK [SAFE:PATH] *

This is an alternate PASSLIST configuration line that utilizes cyber-ark. At run-time, when BatchLogin encounters such a line, it will connect to the cyber-ark vault (asking for login credentials, and your RSA Token passcode and number, if it's the first time in the session), open the particular safe:file, and compose a password authentication loop consisting of the passwords in that safe denoted by password/date (two parameters per line).

These credentials are substituted in the labels as appropriate at that point, essentially creating an authentication loop for the run-time session as needed. The behavior is important, as it's possible that BatchLogin may (unlikely, but it deserves mention) collide the on-the fly credential loop with a pre-existing one. It chooses a naming convention, based upon the primary label that is calling the AUTH reference. BatchLogin appends pw_ to the beginning of the label, and _00, _01 (etc) to each "loop" credential reference.

This means that a user can reference a root password with a call to BatchLogin, thus avoiding embedding root passwords in encrypted passlists. Here's an example for node someserver2:

racf_someserver2:   start:   SSH     someserver2  LOGNAME  racfpass:
root_someserver2:   racf_someserver2:  SU         *  root  cyber_someserver2:
cyber_someserver2:  end:   PASSLIST    CYBERARK   WSE:someserver2.txt  *

Note that in the above example, racfpass: is a label that documents the password for a human login to node someserver2 and is not shown. The connection to cyber-ark will require the RSA token password and number to be entered at run-time as an authentication mechanism, therefore avoiding any passwords encrypted into the BatchLogin configuration. When the cyberark passlist expands the label names in the above case would be pw_someserver2 ... pw_someserver2_nn, where nn indicates the n-1 number of passwords.

Also note that the safe and text file names are extremely case sensitive, and the path to the file is exact (with extension, .txt, included). Failure to correctly include these items will result in a failed connection to cyber-ark, and therefore a failure to connect to the node in question. To aid in the discovery of these safe names, select the "CYBERARK_MENU" function from the main BatchLogin menu, and drill down to the particular safe/file that represents the authentication passwords for the credentials. The name on the safe:file corresponds to the text needed to reference the password.

Additional, easy safe configuration can be expedited by utilizing the safe2passlist.sh shell script, which will dump a generic configuration for a cyberark safe (assumes ssh to all hosts, and su to the root user, which may not be totally desirable). Gateway hops are ignored by this configuration utility -- it's mainly provided as a jumping off point to more complex server configurations.

Finally, note that with the above configuration, only a user authentication loop is missing, and the rest documents no sensitive data. In other words, this entire sequence can now be saved (sans the racfpass: labels, which are not shown) and communicated to other users without fear of leaking sensitive password data.

To better aid in that kind of mechanism, a special password keyword is available. There are three potential configurations for the "LOCAL" PASSLIST type:

An actual password, used to unlock a blf passlist.
An underscore (_), used to prompt the user at run-time.
The special keyword "PASSWORD" (which would be an extremely bad candidate for a password anyway) which designates the password used to unlock the first passlist. In other words, use the same password as the list on the passlist calling out the secondary file.

Summing it all up. What's all this good for?

It should be apparent that just about any connection to any machine can be implemented this way. Passwords on a user level can be contained in one location and propagated throughout the servers affected. Setup is the hardest part. Passwords are encrypted with the blowfish encryption algorithm.

A note on encrypted files: They're only as good as the passwords you supply, and only then as good as the screen protection employed by the underlying operating system. It does very little good to have your password list on the screen, and your Xhost setting to + (all hosts can connect), for example.

The underlying file format is text based, as described in this document, and encrypted through blowfish (implemented with the openssl command line). The menu available at the launch of BatchLogin allows for editing this file with vi, but in order to do this, the session will have to unencrypt the file to a protected (From everybody but the root user of the machine and yourself) location.

[Back]