How do we create a map file to allow login to SSH Tectia Server using certificate authentication?

The map file on the server side is used to map a certificate to a user account based on the data in the user certificate.

Certificate authentication is only supported in commercially licensed distributions of SSH Tectia. Please see general instructions on how to configure SSH Tectia for user certificate authentication in the Certificate Authentication section of Administrator's Guide.

Examine the User Certificate To create correct entries in the map file, you need to know the field names and expected values from the certificate to be used for user authentication. Certificate fields and values can be seen by logging specific SSH Tectia PKI and certificate related modules. Note that while in debug mode, the server daemon will accept only one connection and then die. The server must be then restarted in order to receive new connections. To avoid this, see the sshd2 man page for more information on the -D debugging option.

1. Start the certificate validation daemon in debug mode by using the following command:

   $ ssh-certd -d "*=4,Pki=7,Certd=7" > /etc/ssh2/serverdebug_cert 2>&1 

Note: if you are using SSH Tectia prior than 4.1.x, use

sshd2 -d "*=4,Pki=7,Certd=7" > /etc/ssh2/serverdebug_cert 2>&1

1. Connect to the server with SSH Tectia Client, using a certificate for user authentication. Whether the authentication is successful or not, contents of the certificate attempted for authentication will be found in the debug output.

2. Close the connection and open the server debug file /etc/ssh2/serverdebug_cert. The user certificate that the client offered to the server in the authentication process can be seen in the debug output. From this information, you can determine the certificate fields and values to use in your map file:

certificate = { certificate-field = value }

For example, the user certificate could contain the following fields and values:

certificate = {
serial-number = 1164823
subject-name = <C=FI, O=SSH, CN=Test User, OU=SSH>
issuer-name = <C=FI, O=SSH, CN=Secure Shell Test CA>
not-before = 2002 Mar 26th, 08:10:30 GMT
not-after = 2003 Mar 26th, 08:40:30 GMT
subject-alt-names = {
email = testuser@ssh.com
}
extended-key-usage = {
clientAuth (1.3.6.1.5.5.7.3.2)
}
}

Server Configuration

The map file is specified after the CA certificate in the server configuration file /etc/ssh2/ssh_certd_conf. For example:

Pki /etc/ssh2/ca-cert.crt
MapFile /etc/ssh2/cert-user-mapping 

Ensure that "publickey" is an allowed authentication method for both the client and server.

Map File

Mappings are made with the keywords Email, EmailRegex, Subject, SubjectRegex or SerialAndIssuer. Arguments for each keyword are different, as seen in the examples below.

Email

User account -> Certificate mapping can be done using the standard formatted email address found in the subject alternative name (certificate field subject-alt-names). Note that the email keyword cannot be used to map an email address stated for example in the subject-name field of the certificate.

testuser email testuser@ssh.com

Subject

When using the Subject keyword, mapping is done using the subject name in the DN notation (certificate field subject-name). When mapping with the Subject keyword, the complete LDAP style DN notation is required.

testuser subject C=FI, O=SSH, OU=SSH, CN=Test User

SerialAndIssuer

The mapping is made with two arguments, serial number (certificate field serial-number) and issuer name in DN notation (certificate field issuer-name). The arguments are separated with a white space. The complete DN is required for the issuer name.

testuser SerialAndIssuer 1164823 C=FI, O=SSH, CN=Secure Shell Test CA

EmailRegex

When using email regular expression syntax, a part of the standard formatted email address found in the subject alternative name (certificate field subject-alt-names) can be mapped to the corresponding account ("testuser" when above certificate is used). The patterns are matched using SSH_REGEX_SYNTAX_EGREP. In the example below, the username part of the email address for all users @ssh.com is mapped to a corresponding user account.

%subst% emailregex ([a-z]+)@ssh.com

SubjectRegex

When using subject regular expression syntax, mapping is done using part of the subject name in the DN notation (certificate field subject-name) to corresponding account ("Test" when above certificate is used). Note that the account name cannot contain spaces or other illegal characters. The patterns are matched using SSH_REGEX_SYNTAX_EGREP. In the example below, the first word of the CN value is mapped to a corresponding user account.

%subst% subjectregex C=FI, O=SSH, OU=SSH, CN=([A-Z,a-z]+) User