## TCPware V5.7 Management Guide

- SSH1 and SSH2 Differences
  - Restrictions:
  - Understanding the TCPware Secure Shell Server
  - Servers and Clients
  - Expired Password Handling
  - Break-In and Intrusion Detection
- Configuring SSHD Master
  - SSH2 Configuration File
    - HostSpecificConfig Notes:
    - UserSpecificConfig Notes:
    - KEYBOARD-INTERACTIVE Notes:
    - ForwardACL Notes
    - MappingFileFormat
- Starting the SSH Server for the First Time
  - Configuring the SSH2 Server on a VMScluster with a Common System Disk
  - Changing SSH2 Configuration File After Enabling SSH2
  - Connection and Login Process
    - FILES
  - SSH2 AUTHORIZATION File Format
  - SSH2 Logicals
  - SSH daemon Files

Chapter 26

Configuring the Secure Shell (SSH) V2 Server

This chapter describes how to configure and maintain the TCPware Secure Shell (SSH) server v2.

This is the server side of the software that allows secure interactive connections to other computers in the manner of rlogin/rshell/telnet. The SSH server has been developed to discriminate between SSH v1 and SSH v2 protocols, so the two protocols can coexist simultaneously on the same system.

# SSH1 and SSH2 Differences

SSH1 and SSH2 are different, and incompatible, protocols. The TCPware SSH1 implementation is based on the version 1.3.7 protocol, and the TCPware SSH2 implementation is based on the version 3.2.0 protocol. While SSH2 is generally regarded to be more secure than SSH1, both protocols are offered by TCPware, and although they are incompatible, they may exist simultaneously on a TCPware system. The TCPware server front-end identifies what protocol a client desires to use, and will create an appropriate server for that client

The cryptographic library used by TCPware SSH2 (this does not apply to SSH1 sessions) is compiled from unaltered source code from F-Secure which is FIPS 140-2 level 2 compliant, as determined by the Computer Security Division of the National Institute of Science and Technology (NIST).

Note! You must install the DEC C 6.0 backport library on all OpenVMS VAX v6.0 and earlier systems prior to using SSH. This is the AACRT060.A file. You can find the ECO on the TCPware CD in the following directory: VAX55_DECC_RTL.DIR.

## Restrictions:

When using SSH2 to connect to a VMS server, if the VMS account is set up with a secondary password, SSH2 does not prompt the user for the secondary password. If the VMS primary password entered is valid, the user is logged in, bypassing the secondary password.

When using SSH2 to execute single commands (in the same manner as RSHELL), some keystrokes like CTRL/Y are ignored. In addition, some interactive programs such as HELP may not function as expected. This is a restriction of SSH2. If this behavior poses a problem, log into the remote system using SSH2 in interactive mode to execute the program.

## Understanding the TCPware Secure Shell Server

Secure Shell daemon (SSHD) is the daemon program for SSH2 that listens for connections from clients. The server program replaces rshell and telnet programs. The server/client programs provide secure encrypted communications between two untrusted hosts over an insecure network. A new daemon is created for each incoming connection. These daemons handle key exchange, encryption, authentication, command execution, and data exchange.

## Servers and Clients

A TCPware SSH server is an OpenVMS system that acts as a host for executing interactive commands or for conducting an interactive session. The server software consists of two pieces of software (for future reference, "SSHD" will refer to both SSHD_MASTER and SSHD, unless otherwise specified):

• SSHD_MASTER, recognizes the differences between SSH v1 and SSH v2 and starts the appropriate server. If the request is for SSH v1, then the existing SSH v1 server is run; if the request is for SSH v2, then the SSH v2 server is run.

• SSHD, a copy of which is spawned for each connection instance. SSHD handles all the interaction with the SSH client.

A client is any system that accesses the server. A client program (SSH) is provided with TCPware, but any SSH client that uses SSH version 2 protocol may be used to access the server. Examples of such programs are MultiNet SSH2 for OpenVMS; SecureCRT®, and F-Secure SSH Client for Windows®, MacSSH for Macintosh® systems, and other SSH programs on UNIX-based systems.

Each host has a key using DSA encryption and is usually 1024 bits long (although, the user may create a different-sized key, if desired). The same key may be used on multiple machines. For example, each machine in a VMScluster could use the same key.

When a client connects to the SSHD daemon:

• The client and server together, using the Diffie-Hellman key-exchange method, determine a 256-bit random number to use as the "session key". This key is used to encrypt all further communications in the session.

Note that this key may be renegotiated between the client and the server on a periodic basis by including the RekeyIntervalSeconds keyword in the server configuration file (SSH2_DIR:SSHD2_CONFIG). This is desireable because during long sessions, the more data that is exchanged using the same encryption key, the more likely it is that an attacker who is watching the encrypted traffic could deduce the session key.

• The server informs the client which encryption methods it supports. Currently, AES (the default), Twofish, Blowfish, CAST-128, 3DES and ARCFOUR are supported.

• The client selects the encryption algorithm from those offered by the server.

• The client and the server then enter a user authentication dialog. The server informs the client which authentication methods it supports, and the client then attempts to authenticate the user by using some or all of the authentication methods. The following authentication algorithms are supported:

– public-key (DSA keys)

– hostbased

– password keyboard-interactive

– Kerberos V5 (password, kerberos-tgt, kerberos-1, kerberos-tgt-1, kerberos-2, kerberos-tgt-2)

– Certificate

System security is not improved unless the RLOGIN and RSHELL services are disabled.

If the client authenticates itself successfully, a dialog is entered for preparing the session. At this time the client may request things like:

• forwarding X11 connections

• forwarding TCP/IP connections

• forwarding the authentication agent connection over the secure channel

Finally, the client either requests an interactive session or execution of a command. The client and the server enter session mode. In this mode, either the client or the server may send data at any time, and such data is forwarded to/from the virtual terminal or command on the server side, and the user terminal in the client side. When the user program terminates and all forwarded X11 and other connections have been closed, the server sends command exit status to the client, and both sides exit.

## Expired Password Handling

The SSH2 server supports expired password changing for interactiveaccounts without the CAPTIVE or RESTRICTED flags set and, via the DCL SET PASSWORD command. When an expired password is detected, the server will behave as if a SET PASSWORD command was specified by the user as a remotely-executed command (e.g., $ ssh foo set password), and theuser will be logged out after changing the password. The user may then log in again using the changed password.

For CAPTIVE or RESTRICTED accounts, or for those accounts where LGICMD is set in the UAF record, the scenario is different. In these cases, theserver can't directly execute SET PASSWORD command, because the command procedure specified in the LGICMD field of the UAF record will override the SSH server attempting to do a SET PASSWORD command. For these types of accounts, the system manager and/or user can use the value of the LOGIN_FLAGS for the process (normal interactive sessions may also examine these flags). For SSH logins, these flags will reflect:

• new mail has been received (JPI$M_NEW_MAIL_AT_LOGIN)

• the password is about to expire (JPI$M_PASSWORD_WARNING)

• the password has expired (JPI$M_PASSWORD_EXPIRED)

The DCL lexical function F$GETJPI may be used to examine these flags, as can the $GETJPI(W) system service or LIB$GETJPI RTL function. When an expired password value is detected, the user may then execute a SET PASSWORD command in the command procedure run for the account.

For example:

$!
$! Login_flags:
$! 1 = new mail messages waiting (JPI$M_NEW_MAIL_AT_LOGIN)
$! 4 = password expired during login (JPI$M_PASSWORD_EXPIRED)
$! 5 = password expires within 5 days (JPI$M_PASSWORD_WARNING)
$!
$ flags = f$getjpi("", "LOGIN_FLAGS")
$ new_flags = (flags/2)*2
$ if new_flags .ne. flags then write sys$output "New mail waiting"
$!
$! Note - new_flags is used below because it has the NEW_MAIL_AT_LOGIN$
$! bit stripped. The rest of the possible values are all
$! discrete; i.e., you can't have combinations of them at the
$! same time.

$!
$ if new_flags .eq. 4 then write sys$output "Password expired during login"
$ if new_flags .eq. 5 then write sys$output "Password expires within 5 days"

$!

## B reak-In and Intrusion Detection

Care must be exercised when configuring the SSH clients and server to minimize problems due to intrusion records created by OpenVMS security auditing. The SSH user should consult the system manager to determine the authentication methods offered by the SSH server. The client should then be configured to not attempt any authentication method that is not offered by the server.

If a client attempts authentication methods not offered by the server, the OpenVMS security auditing system may log several intrusion records for each attempt to create a session to that server. The result being that the user could be locked out and prevented from accessing the server system without intervention from the server's system manager.

The authentication methods to be offered by the server are determined by the configuration keywords AllowedAuthentications and RequiredAuthentications. The number of intrusion records to be logged for any attempted SSH session is determined by the StrictIntrusionLogging configuration keyword.

When StrictIntrusionLogging is set to YES (the default), each method that is tried and fails causes an intrusion record to be logged. The following rules apply:

• When HostBased or PublicKey authentications are attempted and fail, one intrusion record is logged for each failed method.

• When password authentication is attempted, one intrusion record is logged for each failed password.

Example 1:

The server is set up to allow HostBased and password authentication; also, up to three password attempts are allowed. If all methods fail, four intrusion records are logged:

1 for the failed HostBased
3 for the failed password attempts, one per attempt

When StrictIntrusionLogging is set to NO, it has the effect of relaxing the number of intrusions logged. Overall failure of all authentication methods simply counts as a single failure, except for password authentication. The following rules apply:

• When password authentication is attempted, one intrusion record is logged for each failed password.

• When any of HostBased or PublicKey authentication fails, and password authentication is not attempted, exactly one intrusion record is logged, as opposed to one for each failed method.

• When any of HostBased or PublicKey authentication fails, but password authentication is attempted and succeeds, the only intrusion record(s) logged is one for each failed password attempt.

Example 2:

The server is set up to allow HostBased and password authentication; also, up to three password attempts are allowed. If all methods fail, three intrusion records are logged:

0 for the failed HostBased
3 for the failed password attempts, one per attempt

Example 3:

The server is set up to allow HostBased and password authentication; also, up to three password attempts are allowed. HostBased and RSA fail, but password authentication is successful after 1 failed password. Therefore, one intrusion record is logged:

0 for the failed HostBased
1 for the failed password attempt

Example 4:

The server is set up to allow HostBased and PublicKey authentication, but not password authentication. If all methods fail, one intrusion record is logged.

Example 5:

The server is set up to allow HostBased and PublicKey authentication, but not password authentication. HostBased authentication fails, but PublicKey succeeds. No intrusion records are logged.

# Configuring SSHD Master

SSHD Master is configured using the TCPware CNFNET command procedure (@TCPWARE:CNFNET SSH). When CNFNET is used to make changes to the SSHD Master configuration, SSH must be restarted via @TCPWARE:RESTART SSH.

## SSH2 Configuration File

SSHD reads configuration data from its configuration file. By default, this file is SSH2_DIR:SSHD2_CONFIG; however, it may be modified by executing @TCPWARE:CNFNET SSH and setting the alternate SSH2 configuration file. A default configuration is supplied in the file SSH2_DIR:SSHD_CONFIG.TEMPLATE. Lines starting with # and empty lines are interpreted as comments. The following keywords are possible. Keywords are case insensitive.

Table 26-1 SSH2 C onfiguration File Keywords [SSHD 2_CONFIG] (Continued)

Keyword | Value | Default | Description
AllowShosts | Host list |  | Access control by hostname
AllowTcpForwarding | Y/N | Y | Enable TCP port forwarding
AllowTcpForwardingForUsers | User list |  | Per-User forwarding
AllowTcpForwardingForGroups | Rights list |  | Per-Rightslist ID forwarding
AllowUsers | User list |  | Access control by username
AllowX11Forwarding | Y/N | Y | Enable X11 forwarding
AuthInteractiveFailureTimeout | Seconds | 2 | Delay, in seconds, that the server delays after a failed attempt to log in using keyboard-interactive and password authentication.
AuthKbdInt.NumOptional | Number | 0 | Specifies how many optional submethods must be passed before the authentication is considered a success. (Note that all reported submethods must always be passed.) See AuthKbdInt.Optional for specifying optional submethods, and AuthKbdInt.Required for required submethods. The default is 0, although if no required submethods are specified, the client must always pass at least one optional submethod.
AuthKbdint.Optional | List | None | Specifies the optional submethods keyboard-interactive will use. Currently only the submethod password is defined. AuthKbdInt.NumOption al specifies how many optional submethods must be passed. The keyboard-interactive authentication method is considered a success when the specified amount of optional submethods and all required submethods are passed.
AuthKbdInt.Required |  |  | Specifies the required submethods that must be passed before the keyboard-interactive authentication method can succeed.
AuthKbdInt.Retries | Number | 3 | Specifies how many times the user can retry keyboard-interactive.
AuthorizationFile | Filename | Authorization | Authorization file for publickey authentication.
AuthPublicKey.MaxSize | Number | 0 | Specifies the maximum size of a publickey that can be used to log in. Value of 0 disables the check.
AuthPublicKey.MinSize | Number | 0 | Specifies the minimum size of a publickey that can be used to log in. Value of 0.
Cert.RSA.Compat.HashScheme | md5 or sha | md5 | Previous clients and servers may use hashes in RSA certificates incoherently (sometimes SHA-1 and sometimes MD5). This specifies the hash used when a signature is sent to old versions during the initial key exchanges.
BannerMessageFile | Filename | SYS$ANNOUNCE | Message sent to the client before authentication begins.
CheckMail | Y/N | Y | Display information about new mail messages when logging in
Ciphers | Cipher list |  | Encryption ciphers offered
DenyGroups | Rights list |  | Deny access for UAF rightslist identifiers
DenyHosts | Host list |  | Deny access for hosts
DenySHosts | Host list |  | Deny access for hosts
DenyTcpForwardingForUsers | User list |  | Forbid forwarding for listed users
DenyTcpForwardingForGroups | Rights list |  | Forbid forwarding for listed rightslist names
DenyUsers | User list |  | Access control by username
FascistLogging | Y/N | Y | Verbose logging
ForwardACL | Pattern | None | With this option, you can have more fine-grained control over what the client is allowed to forward, and to where. See the ForwardACL Notes below.
ForwardAgent | Y/N | Y | Enable agent forwarding
HostCA | Certificate | None | Specifies the CA certificate (in binary or PEM (base64) format) to be used when authenticating remote hosts. The certificate received from the host must be issued by the specified CA and must contain a correct alternate name of type DNS (FQDN). If no CA certificates are specified in the configuration file, the protocol tries to do key exchange with ordinary public keys. Otherwise, certificates are preferred. Multiple CAs are permitted.
HostCANoCRLs | Certificate | None | Similar to HostCA, but disables CRL checking for the given ca-certificate.
HostCertificateFile | Filename | None | This keyword works very much like PublicHostKeyFile, except that the file is assumed to contain an X.509 certificate in binary format. The keyword must be paired with a corresponding HostKeyFile option. If multiple certificates with the same publickey type (DSS or RSA) are specified, only the first one is used.
HostbasedAuthForceClientHostnameDNSMatch | Y/N | N | Host name given by client.
Hostkeyfile | Filename | Hostkey | Host key filename
HostSpecificConfig | Pattern | None | Specifies a subconfiguration file for this server, based on the hostname of the client system.
IdentityFile | Filename | Identification | Identity filename
IdleTimeout | Time | 0 = none | Set idle timeout (in seconds)
IgnoreRhosts | Y/N | N | Ignore local rhosts
IgnoreRootRhosts | Y/N | Y | Ignore system rhosts
KeepAlive | Y/N | Y | Send keepalives
LdapServers | Server URL | None | Specified as ldap://server.domain-name:389 CRLs are automatically retrieved from the CRL distribution point defined in the certificate to be checked if the point exists. Otherwise, the comma-separated server list given by option LdapServers is used. If intermediate CA certificates are needed in certificate validity checking, this option must be used or retrieving the certificates will fail.
ListenAddress | IP address | 0.0.0.0 | Listen on given interface
Macs | Algorithm |  | Select MAC (Message Authentication Code) algorithm
MapFile | Filename | None | This keyword specifies a mapping file for the preceding Pki keyword. Multiple mapping files are permitted per one Pki keyword. The mapping file format is described below.
MaxBroadcastsPerSecond | #broadcasts | 0 | Listen for UDP broadcasts
NoDelay | Y/N | N | Enable Nagel Algorithm
PasswordAuthentication | Y/N | Y | Permit password authentication
PasswordGuesses | #guesses | 3 | Limit number of password tries to specified number
PermitEmptyPasswords | Y/N | N | Permit empty (blank) passwords
PermitRootLogin | Y/N | N | SYSTEM can log in
Pki | Filename | None | This keyword enables user authentication using certificates. Ca-certificate must be an X.509 certificate in binary format. This keyword must be followed by one or more MapFile keywords. The validity of a received certificate is checked separately using each of the defined Pki keywords in turn until they are exhausted (in which case the authentication fails), or a positive result is achieved. If the certificate is valid, the mapping files are examined to determine whether the certificate allows the user to log in. A correct signature generated by a matching private key is always required.
PkiDisableCrls | Y/N | Y | This keyword disables CRL checking for the Pki keyword, if argument is "Y".
PrintMotd | Y/N | Y | Display SYS$WELCOME when logging in
PublicHostKeyFile | Filename | Hostkey.pub | Host key file location
QuietMode | Y/N | N | Quiet mode
RandomSeedFile | Filename | Random_seed | Random seed file
RekeyIntervalSeconds | #seconds | 0 | Frequency of rekeying
RequiredAuthentication | Authentication list |  | Authentications client must support
RequireReverseMapping | Y/N | N | Remote IP address must map to hostname
ResolveClientHostName | Y/N | Y | Controls whether the server will try to resolve the client IP address at all, or not. This is useful when you know that the DNS cannot be reached, and the query would cause additional delay in logging in. Note that if you set this to "no", you should not set RequireReverseMapping to "yes".
RSAAuthentication | Y/N | Y | Enable RSA authentication
SendKeyGuess | Y/N | Y | This parameter controls whether the server will try to guess connection parameters during key exchange, or not. Some clients do not support key exchange guesses and may fail when they are present.
SftpSyslogFacility | Facility | None | Defines what log facility the sftp-server will use. By default, no logging is performed.
StrictIntrusionLogging | Y/N | Y | Determine how intrusion records are created by failed authentication attempts.
StrictModes | Y/N | N | Strict checking for directory and file protection.
SyslogFacility | Facility | AUTH | Defines what log facility to be used when logging server messages
UserConfigDirectory | Directory | SYS$LOGIN: | Location of user SSH2 directories
UserKnownHosts | Y/N | Y | Respect user [.ssh2] known hosts keys
UserSpecificConfig | Pattern | None | Specifies a subconfiguration file for this server, based on user logging in.
VerboseMode | Y/N | N | Verbose mode

The keywords /MAC and /CIPHER have discrete values, plus there are values that actually denote a grouping of 2 or more of the discrete values. Each of these values may be put in the configuration file (SSH2_DIR:SSHD2_CONFIG).

Table 26-2 MAC and Cipher Discrete Values (Continued)

M AC s | discrete values: hmac-sha1, hmac-sha1-96, hmac-md5, hmac-md5-96, hmac-sha256@ssh.com, hmac-sha256-96@ssh.com, hmac-ripemd160@ssh.com, hmac-ripemd160-96@ssh.com, hmac-tiger128@ssh.com, hmactiger128-96ssh.com, hmac-tiger160@ssh.com, hmac-tiger160-96@ssh.com, hmac-tiger192@ssh.com, hmac-tiger192-96@ssh.com
| group ANYMAC consists of: hmac-sha1, hmac-sha1-96, hmac-md5, hmac-md5-96, hmac-sha256@ssh.com, hmac-sha256-96@ssh.com, hmac-ripemd160@ssh.com, hmac-ripemd160-96@ssh.com, hmac-tiger128@ssh.com, hmactiger128-96ssh.com, hmac-tiger160@ssh.com, hmac-tiger160-96@ssh.com, hmac-tiger192@ssh.com, hmac-tiger192-96@ssh.com
| group ANY consists of: hmac-sha1, hmac-sha1-96, hmac-md5,hmac-md5-96, hmac-sha256@ssh.com, hmac-sha256-96@ssh.com, hmac-ripemd160@ssh.com, hmac-ripemd160-96@ssh.com, hmac-tiger128@ssh.com, hmac-tiger128-96@ssh.com, hmac-tiger160@ssh.com, hmac-tiger160-96@ssh.com, hmac-tiger192@ssh.com, hmac-tiger192-96@ssh.com, none
| group ANYSTD consists of: hmac-sha1, hmac-sha1-96, hmac-md5, hmac-md5-96, none
| group ANYSTDMAC consists of: hmac-sha1, hmac-sha1-96, hmac-md5, hmac-md5-96
Ciphers | discrete values: aes128-cbc, 3des-cbc, twofish128-cbc, cast128-cbc, twofish-cbc, blowfish-cbc, aes192-cbc, aes256-cbc, twofish192-cbc, twofish256-cbc, arcfour, des-cbc@ssh.com, rc2-cbc@ssh.com, none
| group ANYSTDCIPHER consists of: aes128-cbc, 3des-cbc, twofish128-cbc, cast128-cbc, twofish-cbc, blowfish-cbc, aes192-cbc, aes256-cbc, twofish192-cbc, twofish256-cbc, arcfour
| group ANY consists of: aes128-cbc, 3des-cbc, twofish128-cbc, cast128-cbc, twofish-cbc, blowfish-cbc, aes192-cbc, aes256-cbc, twofish256-cbc, arcfour, des@ssh.com, rc2-cbc@ssh.com, none
| group ANYCIPHER consists of: aes128-cbc, 3des-cbc, twofish128-cbc, cast128-cbc, twofish-cbc, blowfish-cbc, aes192-cbc, aes256-cbc, twofish192-cbc, twofish256-cbc, arcfour, des-cbc@ssh.com, rc2-cbc@ssh.com
| group ANYSTD consists of: aes128-cbc, 3des-cbc, twofish128-cbc, cast128-cbc, twofish-cbc, blowfish-cbc, aes192-cbc, aes256-cbc, twofish192-cbc, twofish256-cbc, arcfour, none

A discrete value or a group identifier may be used with MACS and CIPHERS. For example, in the configuration file, the following examples could be used:

Ciphers | ANYCIPHER
Ciphers | cast, des, twofish
MACs | ANYMAC
MACs | hmac-sha1

Aliases may be used for some standard ciphers:

Alias | Value
aes | aes128-cbc
3des | 3des-cbc
cast | cast128-cbc
twofish | twofish128-cbc
blowfish | blowfish-cbc
arcfour | arcfour

### HostSpecificConfig Notes:

The global server file (SSH_DIR:SSHD2_CONFIG) now can use the keyword HostSpecificConfig to allow the specification of a configuration file based on the client system. Thse lines are specified as:

HostSpecificConfig hostname subconfig-file

pattern will be used to match the client host, as specified under option AllowHosts. The file subconfig-file will then be read, and configuration data amended accordingly. The file is read before any actual protocol transactions begin, and you can specify most of the options allowed in the main configuration file. You can specify more than one subconfiguration file, in which case the patterns are matched and the files read in the order specified. Later defined values of configuration options will either override or amend the previous value, depending on which option it is. The effect of redefining an option is described in the documentation for that option. For example, setting Ciphers in the subconfiguration file will override the old value, but setting AllowUsers will amend the value.

The subconfig-file will be assumed by default to exist in the SSH2_DIR directory. However, this may be overridden by specifying a complete directory/file specification. For example:

HostSpecificConfig foo.bar.com dka0:[sshconfigs]fooconfig.dat

HostSpecificConfig lima.beans.com limaconfig.dat

In the first instance, an incoming connection from "foo.bar.com" will use the subconfig file dka0:[sshconfigs]fooconfig.dat. In the second example, an incoming connection from "lima.beans.com" will use ssh2_dir:limaconfig.dat.

Unlike ssh2_config, the subconfig files may have configuration blocks, or stanzas, in them. They are used per-host. The subconfiguration heading is interpreted identically to what is described above (i.e, with UserSpecificConfig, the pattern is of the format "hostname".)

Note! If the subconfig file cannot be found or cannot be parsed successfully for any reason, access to the system will be denied for the system to which the subconfig file applies.

### UserSpecificConfig Notes:

The global server file (SSH2_DIR:SSHD2_CONFIG) now can use the keyword UserSpecificConfig to allow the specification of a configuraiton file based ont he username of the user who’s logging into the server. These keywords are of the form:

UserSpecificConfig user[%group] [@host] subconfig-file

pattern will be used to match the username, as specified under the option AllowUsers. The file subconfig-file will then be read, and configuration data amended accordingly. The file is read before any actual protocol transactions begin, and you can specify most of the options allowed in the main configuration file. You can specify more than one subconfiguration file, in which case the patterns are matched and the files read in the order specified. Later defined values of configuration options will either override or amend the previous value, depending on which option it is. The effect of redefining an option is described in the documentation for that option. For example, setting Ciphers in the subconfiguration file will override the old value, but setting AllowUsers will amend the value.

Unlike sshd2_config, the subconfig files may have configuration blocks, or stanzas, in them. They are used per user. The subconfiguration heading is interpreted identically to what is described above (i.e., with UserSpecificConfig, the pattern is of the format "user[%group] [@host]".

The subconfig-file will be assumed by default to exist in the SSH2_DIR directory. However, this may be overridden by specifying a complete directory/file specification. For example:

UserSpecificConfig dilbert dka0:[sshconfigs]dilbert.dat

UserSpecificConfig boss@lima.beans.com pointhair.dat

In the first instance, an incoming connection for user dilbert will use the subconfig file dka0:[sshconfigs]dilbert.dat. In the second example, an incoming connection from user boss at system lima.beans.com will user ssh2:dir:pointyhair.dat.

Note! If the subconfig file cannot be found or cannot be parsed successfully for any reason, access to the system will be denied for the user to which the subconfig file applies.

### KEYBOARD-INTERACTIVE Notes:

At this point, KEYBOARD-INTERACTIVE mode is simply another form of password authentication. The user won’t notice anything different with this mode. In the future, Process Software may implement items such as system passwords, secondary passwords, and true VMS-style password changing using this authentication method. As other clients support the use of the KEYBOARD-INTERACTIVE authentication method for doing password authentication (without using any external callouts from the mechanism such as secureid cards), the server should support those clients.

### ForwardACL Notes

With this option, you can have more fine-grained control over what the client is allowed to forward, and to where. Format for this option is:

[allow|deny] [local|remote] user-pat forward-pat [originator-pat]

user-pat will be used to match the client-user, as specified under the option UserSpecificConfig. forward-pat is a pattern of format host-id[%port]. This has different interpretations, depending on whether the ACL is specified for local or remote forwards. For local forwards, the host-id will match with the target host of the forwarding, as specified under the option AllowHosts. port will match with the target port. Also, if the client sent a host name, the IP address will be looked up from the DNS, which will be used to match the pattern. For remote forwardings, where the forward target is not known (the client handles that end of the connection); this will be used to match with the listen address specified by the user (and as such is not as usable as with local forwards). port will match the port the server is supposed to be listening to with this forward. With local forwads, originator-pat will match with the originator address that the client has reported. Remember, if you do not administor the client machine, users on that machine may use a modified copy of ssh that can be used to lie about the originator address. Also, with NATs (Network Address Translation), the originator address will not be meaningful (it will probably be an internal network address). Therefore, you should not rely on the originator address with local forwads, unless you know exactly what you are doing. With remote forwards, originator-pat will match with the IP address of the host connecting to the forwarded port. This will be valid information, as it is the server that is checking that information.

If you specify any allow directives, all forwads in that class (local or remote) not specifically allowed will be denied (note that local and remote forwards are separate in this respect, e.g., if you have one "allow remote" definition, local forwards are still allowed, pending other restrictions). If a forward matches with both allow and deny directives, the forwarding will be denied. Also, if you have specified any of the options [Allow.Deny]TcpForwardingForUsers.Groups] or AllowTcpForwarding, and the forwarding for the user is disabled with those, an allow directive will not re-enable the forwarding for the user. Forwarding is enabled by default.

### MappingFileFormat

When certificates are used in user authentication, one or more mapping files determin whether the user can log to an account with a certificate. The mapping file must contain one or more lines in the following format:

account-id keyword arguments

Keyword must be one of the following: Email, EmailRegex, Subject, SerialAndIssuer, or SubjectRegex.

Arguments are different for each keyword. The following list describes each variation:

Email

arguments: an email address in standard format. If the certificate contains the email address as an alternate name, it is good for logging in as user account-id.

Subject

arguments: a subject name in DN notation (LDAP style). If the name matches the one in the certificate, the certificate is good for logging in as user account-id.

SerialAndIssuer

arguments: a number and an issuer name in DN notation (LDAP style), separated by whitespace. If the issuer name and serial number match those in the certificate, the certificate is good for logging in as user account-id.

EmailRegex

arguments: a regular expresssion (egrep syntax). If it matches an altername (of type email-address) in the certificate, the certificate is good lor logging in as user account-id. As a special feature, if account-id contains a string %subst%, it is replaced by the first parenthesized substring of the regular expression before comparing it with the account the user is trying to log into.

SubjectRegex

Works indentically to EmailRegex, except it matches the regular expression to the canonical subject name in the received certificate.

Empty lines and lines beginning with # are ignored.

EXAMPLE: MAPPINGFILE

guest email guest@domain.org
guest subject C=Fl,O=Company Ltd., CN-Guest User
guest SerialAndUser 123 C=Fl, O=Foo\Ltd., CN=Test CA
%subst% EmailRegex ([a-z]+)@domain.\org
%subst% Subjectregex ^C=Fl,O=Company,CN=([a-z]+)$

The example EmailRegex permits in users with email addresses with domain domain.org and usernames that contain only letters, each user to the account that corresponds to the username part of the email address.

The example SubjectRegex lets in all users with fields C=Fl and O=Company in the subject name if their CN field contains only letters and is the account name they are trying to log into.

Note the ^ and $ at the beginning and end of the regular expression; they are required to prevent the regular expression from matching less than the whole string (subject name).

Note also that all characters interpreted by the regular expression parser as special characters must be escaped with a backslash if they are a part of the subject name. This also means that the backslash in the SerialAndIssuer example would have to be escaped with another backslash if the same subject name was used in a SubjectRegex rule.

# Starting the SSH Server for the First Time

Follow these instructions for using SSH for the first time.

1 Use the TCPWARE CNFNET utility to configure the SSH server.

Note! TCPware must be running before issuing the SSHKEYGEN command.

2 Use SSHKEYGEN /SSH2 to generate an ssh2 key and to create the server keys in the SSH2_HOSTKEY_DIR directory:

$ DEFINE TCPWARE_SSH2_HOSTKEY_DIR -
_$ TCPWARE_SPECIFIC:[TCPWARE.SSH2.HOSTKEYS]

$ TCPWARE SSHKEYGEN /SSH2 /HOST
Generating 1024-bit dsa key pair
8 .oOo.oOoo.oO
Key generated.
1024-bit dsa, lillies@flower.plants.com, Mon Aug 09 2004 09:19:47
Private key saved to tcpware_ssh2_hostkey_dir:hostkey.
Public key saved to tcpware_ssh2_hostkey_dir:hostkey.pub

3 Copy the template configuration file to the ssh2_dir: directory renaming it SSHD2_CONFIG.:

$ COPY TCPWARE_COMMON:[TCPWARE.SSH2]SSHD2_CONFIG.TEMPLATE -
_$ TCPWARE_SPECIFIC:[TCPWARE.SSH2]SSHD2_CONFIG.

Note! As delivered, the template file provides a reasonably secure SSH environment. However, Process Software recommends this file be examined and modified appropriately to reflect the security policies of your organization.

4 Restart the SSH component. This creates the SSH server process and defines the SSH logical names.

$ @TCPWARE:RESTART S SH
$ SHOW PROCESS "SSHD Master"

7-JUL-2004 09:03:06.42 User: SYSTEM Process ID: 00000057
Node: PANTHR Process name: "SSHD Master"
Terminal:
User Identifier: [SYSTEM]
Base priority: 4
Default file spec: Not available
Number of Kthreads: 1
Devices allocated: BG1:
BG2:
$ SHOW LOGICAL/SYSTEM *SSH*
"TCPWARE_SSH2_HOSTKEY_DIR" =
"TCPWARE_SPECIFIC:[TCPWARE.SSH2.HOSTKEYS]"
"TCPWARE_SSH2_KNOWNHOSTS_DIR" =
"TCPWARE_SPECIFIC:[TCPWARE.SSH2.KNOWNHOSTS]"
"TCPWARE_SSH_ENABLE_SSH2_CONNECTIONS" = "1"
"SSH2_DIR" = "TCPWARE_SPECIFIC:[TCPWARE.SSH2]"
"SSH_DIR" = "TCPWARE_SPECIFIC:[TCPWARE]"
"SSH_EXE" = "TCPWARE_COMMON:[TCPWARE]"
"SSH_LOG" = "TCPWARE_SPECIFIC:[TCPWARE.SSH]"
"SSH_TERM_MBX" = "MBA36:"

## Configuring the SSH2 Server on a VMScluster with a Common System Disk

When configuring the SSH2 server on a VMScluster with a common system disk, you must create the appropriate directories on all cluster nodes other than the one on which TCPware was originally installed. Note that this does not need to be done for cluster members that do not share a common system disk.

The following procedure should be followed on each cluster node other than the cluster node on which TCPware was originally installed.

• Create the following directories:

$ CREATE/DIR TCPWARE_SPECIFIC[TCPWARE.SSH2]/PROT=(WO:RE,GR:RE)
$ CREATE/DIR TCPWARE_SPECIFIC[TCPWARE.SSH2.KNOWNHOSTS]/PROT=(WO:RE,GR:RE)
$ CREATE/DIR TCPWARE_SPECIFIC[TCPWARE.SSH2.HOSTKEYS]/PROT=(WO:RE,GR:RE)
$ CREATE/DIR TCPWARE_SPECIFIC[TCPWARE.SSH]/PROT=(WO:RE,GR:RE)

• Edit the TCPWARE_SPECIFIC:[TCPWARE_SSH2]SSHD_CONFIG file as necessary. This may be copied from another cluster node, or it may be created fresh from the SSHD_CONFIG.TEMPLATE file.

• Configure the SSH2 server using @TCPWARE:CNFNET SSH

• Generate the SSH2 host keys using NETCU SSHKEYGEN/SSH2/HOST

• (Re)start SSHD Master using @TCPWARE:RESTART SSH

## C hanging SSH2 Configuration File After Enabling SSH2

If you make a change to the SSH configuration file after you have enabled SSH, you must restart SSH for these changes to take effect.

@T CPWARE:R ESTART SSH

Note! When restarting SSH, all active SSH server sessions are terminated. Active client sessions are not affected.

## Connection and Login Process

To create a session, SSHD does the following:

1 SSHD_MASTER sees the connection attempt. It creates an SSHD process, passing the operating parameters to it. SSHD performs validation for the user.

2 Assuming the login is successful, SSHD creates a pseudoterminal for the user (an _FTAnn: device). This device is owned by the user attempting to log in.

3 SSHD creates an interactive process on the pseudoterminal, using the username, priority, and privileges of the user who is attempting to log in. If a command was specified, it is executed and the session is terminated.

4 SSH generates the file SSHD.LOG for each connection to the SSH server. Many connections result in many log files. Instead of purging the files on a regular basis, use the following DCL command to limit the number of versions:

$ SET FILE /VERSION_LIMIT=x TCPWARE_ROOT:[TCPWARE.SSH]SSHD.LOG

Note! The value for /VERSION_LIMIT must not be smaller than the maximum number of simultaneous SSH sessions anticipated. If the value is smaller, SSH users may be prevented from establishing sessions with the server.

### FILES

TCPWARE:HOSTS.EQUIV

Contains host names, one per line. This file is used during .rhosts authentication. Users on those hosts are permitted to log in without a password, provided they have the same username on both machines. The hostname may also be followed by a username. Such users are permitted to log in as any user on the remote machine (except SYSTEM). Additionally, the syntax +@group can be used to specify netgroups. Negated entries start with dash (-). If the client host/user is matched in this file, login is permitted provided the client and server usernames are the same. Successful RSA host authentication is required. This file should be world-readable but writeable only by SYSTEM.

It is never a good idea to use usernames in hosts.equiv. It means the named user(s) can log in as anybody, which includes accounts that own critical programs and directories. Using a username grants the user SYSTEM access. The only valid use for usernames is in negative entries.

Note! This warning also applies to rshell/rlogin.

TCPWARE:SHOSTS.EQUIV

Processed as TCPWARE:HOSTS.EQUIV. May be useful in environments that want to run both rshell/rlogin and ssh.

TCPWARE_SSH2_HOSTKEY_DIR:HOSTKEY

Contains the private part of the host key. This file does not exist when TCPware is installed. The SSH server starts only with this file. This file must be created manually using the command:

$ TCPWARE SSHKEYGEN /SSH2 /HOST.

This file should be owned by SYSTEM, readable only by SYSTEM, and not accessible to others.

To create a host key with a name that is different than what SSHKEYGEN creates, do one of the following:

• Generate with SSHKEYGEN /SSH2/HOST and simply rename the file(s).

• Generate without the /HOST switch and then name the file(s) whatever you want.

By default the logical name SSH2_DIR points to the TCPWARE_SPECIFIC:[TCPWARE.SSH2] directory.

Refer to the TCPware for OpenVMS User’s Guide, Chapter 16, for more details about SSHKEYGEN.

TCPWARE_SSH2_HOSTKEY_DIR:HOSTKEY.PUB

Contains the public part of the host key. This file should be world-readable but writeable only by SYSTEM. Its contents should match the private part. This file is not used for anything; it is only provided for the convenience of the user so its contents can be copied to known hosts files.

SSH2:SSH_RANDOM_SEED
SYS$LOGIN:[.SSH]RANDOM_SEED

Contains a seed for the random number generator. This file should only be accessible by system.

SSH2_DIR:SSHD2_CONFIG

Contains configuration data for the v2 SSHD server. This file should be writeable by system only, but it is recommended (though not necessary) that it be world-readable.

SYS$LOGIN:[.SSH2]SHOSTS

Permits access using SSH2 only. For SSH2, this file is the same as for .rhosts. However, this file is not used by rlogin and rshell daemon.

SYS$LOGIN:RHOSTS

This file contains host-username pairs, separated by a space, one per line. The given user on the corresponding host is permitted to log in without a password. The same file is used by rlogin and rshell. SSH2 differs from rlogin and rshell in that it requires RSA host authentication in addition to validating the hostname retrieved from domain name servers (unless compiled with the -with-rhosts configuration option). The file must be writeable only by the user. It is recommended that it not be accessible by others. It is possible to use netgroups in the file. Either host or username may be of the form +@groupname to specify all hosts or all users in the group.

SYS$LOGIN:[.SSH2]AUTHORIZATION

This file contains information on how the server verifies the identity of a user.

SYS$LOGIN:[.SSH2.KNOWNHOSTS]xxxxyyyy.pub

These are the public host keys of hosts that a user wants to log in from using "hostbased" authentication (equivalent to the SSH1's "RhostsRSAAuthentication"). Also, a user must set up his/her individual .SHOSTS or .RHOSTS file. If the username is the same in both hosts, it is adequate to put the public host key in SSH2_DIR:KNOWNHOSTS and add the host's name to the system-wide SHOSTS.EQUIV or RHOSTS.EQUIV file.

xxxx is the hostname (FQDN) and yyyy denotes the public key algorithm of the key ("ssh-dss" or "ssh-rsa").

For example flower.plants.com's host key algorithm is "ssh-dss". The hostkey would then be "flower_plants_com_ssh-dss.pub" in the [.SSH2.KNOWNHOSTS] directory.

## SSH2 AUTHORIZATION File Format

The Authorization file contains information on how the server verifies the identity of a user. This file has the same general syntax as the SSH2 configuration files. The following keywords may be used:

Table 26-3 SSH 2 AUTHORIZATION Keywords (Continued)

Keyword | Description
KEY | The filename of a public key in the [.SSH2] directory in the user's SYS$LOGIN directory. This key is used for identification when contacting the host. If there are multiple KEY lines, all are acceptable for login.
COMMAND | This keyword, if used, must follow the KEY keyword above. This is used to specifiy a "forced command" that executes on the server side instead of anything else when the user is authenticated. This option might be useful for restricting certain public keys to perform certain operations.

## SSH2 Logicals

These logicals are used with the SSH server in the system logical name table.

$ SHOW LOGICAL/SYSTEM *SSH*

SSH_DIR

Points to the directory where the master server log file is kept. Normally, this is TCPWARE_SPECIFIC:[TCPWARE].

SSH_EXE

Points to the directory where SSH executables are kept. Normally, this is TCPWARE_COMMON:[TCPWARE].

SSH_LOG

Points to the directory where the log files are kept. Normally, this is TCPWARE_SPECIFIC:[TCPWARE.SSH].

TCPWARE_LOG_SSH_MBX

Points to the OpenVMS mailbox used to log connection accept and reject messages. This must not be modified by the user.

TCPWARE_SSH_ACCESS_CHECK_OLD_STYLE

Use the NETWORK access mask instead of the REMOTE access mask to determin access during login

TCPWARE_SSH_ACCESS_USE_LOCAL

Use the LOCAL login mask to allow logins insetad of the NETWORK or REMOTE masks in SYSUAF.

TCPWARE_SSH_ACC_REJ_LOG_FILE

If the user has set a log file to log connection accept and reject messages, this logical will be defined and will provide the name of the log file. This logical is set by
@TCPWARE:CNFNET SSH, and should not be modified directly by the user.

TCPWARE_SSH_LOG_ACCEPTS

When set, causes the server to log successful connection requests as either an OPCOM message or a line in a log file. This logical is set by @TCPWARE:CNFNET SSH. A successful connection request doesn't equate to a successful authentication request. This logical should not be modified directly by the user.

TCPWARE_SSH_LOG_FILE

Define the default file spcification for the SSH server log file. The default is SSH_LOG:SSHD.LOG.

TCPWARE_SSH_LOG_REJECTS

When set, causes the server to log rejected connection requests as either an OPCOM message or a line in a log file. This logical is set by @TCPWARE:CNFNET SSH. This logical should not be modified directly by the user.

TCPWARE_SSH_MAX_SESSIONS

Defines the maximum number of concurrent SSH sessions allowed on the server system. This is defined with the CNFNET procedure. If not defined, this defaults to 1000.

SSH_TERM_MBX

Mailbox used by SSHD_MASTER to receive termination messages from SSHD daemon processes. Do not change this logical name. This is created by the SSHD_MASTER process.

TCPWARE_SSH_KEYGEN_MIN_PW_LEN

Defines the minimum passphrase length when one is to be set in SSHKEYGEN. If not defined, defaults to zero.

TCPWARE_SSH_PARAMETERS_n

These values are set by TCPware and must not be modified by the user.

TCPWARE_SSH_USE_SYSGEN_LGI

If defined, causes SSHD to use the VMS SYSGEN value of LGI_PWD_TMO to set the login grace time, overriding anything specified in the command line or the configuration file.

TCPWARE_SSH_ENABLE_SSH2_CONNECTIONS

Enables SSHD Master to accept SSH V2 sessions.

TCPWARE_SSH2_HOSTKEY_DIR

Directory containing the host keys for the SSH V2 server. Normally set to TCPWARE_SPECIFIC:[TCPWARE.SSH2.HOSTKEYS]

TCPWARE_SSH2_KNOWNHOSTS_DIR

Directory containing the public keys for known systems. Normally set to TCPWARE_SPECIFIC:[TCPWARE.SSH2.KNOWNHOSTS].

SSH2_DIR

Contains all SSH V2-specific files, such as configuration files. Normally set to TCPWARE_SPECIFIC:[TCPWARE.SSH2]

## SSH daemon Files

These files are used by or created by SSH when you log into a daemon. These files are not to be altered in any way.

SSH_LOG:SSHD.LOG

This log file is created by each SSHD daemon.

SSHD_MASTER.LOG

This log file is created by SSHD_MASTER.