2.7 Configuring for Two-factor Authentication
2.7.2 Configuring Bindings Clients for Two-factor Authentication
Client/server connections use %Service_Bindings. For these connections, the code required to use two-factor authenti-cation varies by programming language. (Note that Console and Terminal do not require any client-side configuration.) Supported languages include:
• C++
• Java and JDBC
• .NET
• ODBC
• Perl
• Python
Client-side code performs three operations:
1. After establishing a connection to the Caché server, it checks if two-factor authentication is enabled on the server.
Typically, this uses a method of the client’s connection object.
2. It gets the two-factor authentication token from the user. This generally involves user-interface code that is not specifically related to Caché.
3. It provides the token to the Caché server. This also typically uses a connection object method.
Important: Studio, which connects to the Caché server using %Service_Bindings, does not support two-factor authentication.
2.7.2.1 C++
With C++, support for two-factor authentication uses two methods of the tcp_conn class:
• bool tcp_conn::is_two_factor_enabled()
This method checks if two-factor authentication is enabled on the server. It returns a boolean; true means that two-factor authentication is enabled.
• bool tcp_conn::send_two_factor_token(const wchar_t* token, Conn_err* err)
This method provides the two-factor authentication token to the server. It returns a boolean; true means that the user has been authenticated. It takes two arguments:
– token, the two-factor authentication token that the user has received. Note that the client application is responsible for obtaining the value of the token from the user.
– err, an error that the method throws if the user does not successfully authenticate.
Important: If two-factor authentication is enabled on the server and the client code does not implement two-factor authentication calls, then the server will drop the connection with the client.
The following example uses an instance of a connection called conn:
34 Caché Security Administration Guide Authentication
1. It uses that instance’s methods to check if two-factor authentication is enabled.
2. It attempts to provide the token to the server and performs error processing if this fails. Note that the sample code here assumes that the application code has stored the security token in a variable of type std::string; it then uses the c_str method of the string class to extract the security token as a null-terminated string to pass to the server.
// Given a connection called "conn"
if (conn->is_two_factor_enabled()) {
// Prompt the user for the security token.
// Store the token in the "token" variable of type std::string.
Conn_err err;
if (!conn->send_two_factor_token(token.c_str(), &err;))
// Process the error from a invalid authentication token here.
}
Note: The light C++ binding does not support two-factor authentication.
2.7.2.2 Java and JDBC
With Java, support for two-factor authentication uses two methods of the CacheConnection class:
• public boolean isTwoFactorEnabled() throws Exception
This method checks if two-factor authentication is enabled on the server. It returns a boolean; true means that two-factor authentication is enabled.
• public void sendTwoFactorToken(String token) throws Exception
This method provides the security token to the server. It takes one argument, token, the security token that the user has received.
The following example uses an instance of a connection called conn:
1. It uses that instance’s methods to check if two-factor authentication is enabled.
2. It attempts to provide the token to the server and performs error processing if this fails.
Important: If two-factor authentication is enabled on the server and the client code does not implement two-factor authentication calls, then the server will drop the connection with the client.
// Given a connection called "conn"
if (conn.isTwoFactorEnabled()) {
// Prompt the user for the two-factor authentication token.
// Store the token in the "token" variable.
try {
conn.sendTwoFactorToken(token);
}
catch (Exception ex) {
// Process the error from a invalid authentication token here.
} }
2.7.2.3 .NET
For .NET, Caché supports connections with two-factor authentication with the managed provider and with ADO.NET.
Support for two-factor authentication uses two methods of the tcp_conn class:
• bool CacheConnection.isTwoFactorEnabledOpen()
This method opens a connection to the Caché server and checks if two-factor authentication is enabled there. It returns a boolean; true means that two-factor authentication is enabled.
• void CacheConnection.sendTwoFactorToken(token)
Configuring for Two-factor Authentication
This method provides the security token to the server. It has no return value. It takes one argument, token, the security token that the user has received. If there is a problem with either the token (such as if it is not valid) or the connection, then the method throws an exception.
Important: A client application makes a call to isTwoFactorEnabledOpen instead of a call to CacheConnection.Open.
The isTwoFactorEnabledOpen method requires a subsequent call to sendTwoFactorToken.
Also, if factor authentication is enabled on the server and the client code does not implement two-factor authentication calls, then the server will drop the connection with the client.
The following example uses an instance of a connection called conn:
1. It uses that instance’s methods to check if two-factor authentication is enabled.
2. It attempts to provide the token to the server and performs error processing if this fails.
// Given a connection called "conn"
try {
if (conn.isTwoFactorEnabledOpen()) {
// Prompt the user for the two-factor authentication token.
// Store the token in the "token" variable.
conn.sendTwoFactorToken(token);
} }
catch (Exception ex) { // Process exception }
2.7.2.4 ODBC
With ODBC, support for two-factor authentication uses two standard ODBC function calls (which are documented in the Microsoft ODBC API Reference):
• SQLRETURN rc = SQLGetConnectAttr(conn, 1002, &attr, sizeof(attr), &stringLengthPtr);
The SQLGetConnectAttr function, part of the Microsoft ODBC API, returns the current value of a specified connection attribute. The Caché ODBC client uses this function to determine if the server supports two-factor authentication. The value of the first argument is a handle to the connection from the client to the server; the value of the second argument is 1002, the ODBC attribute that specifies whether or not two-factor authentication is supported; the values of the subsequent arguments are for the string containing the value of attribute 1002, as well as relevant variable sizes.
• SQLRETURN rc = SQLSetConnectAttr(conn, 1002, unicodeToken, SQL_NTS);
The SQLSetConnectAttr function, also part of the Microsoft ODBC API, sets the value of a specified connection attribute. The Caché ODBC client uses this function to send the value of the two-factor authentication token to the server. The values of the four arguments are, respectively:
– The connection from the client to the server.
– 1002, the ODBC attribute that specifies whether or not two-factor authentication is supported.
– The value of the security token.
– SQLNTS, which indicates that the security token is stored in a string.
Important: If two-factor authentication is enabled on the server and the client code does not implement two-factor authentication calls, then the server will drop the connection with the client.
The following example uses an instance of a connection called conn:
1. It uses SQLGetConnectAttr to check if two-factor authentication is enabled.
36 Caché Security Administration Guide Authentication
2. It attempts to provide the token to the server with the SQLSetConnectAttr call and performs error processing if this fails. If SQLSetConnectAttr fails, the server drops the connection, so you need to reestablish the connection before you can attempt authentication again.
// Given a connection called "conn"
SQLINTEGER stringLengthPtr;
SQLINTEGER attr;
SQLRETURN rc = SQLGetConnectAttr(conn, 1002, &attr, sizeof(attr), &stringLengthPtr);
if attr {
// Prompt the user for the two-factor authentication token.
wstring token;
SQLRETURN rc = SQLSetConnectAttr(conn, 1002, token, SQL_NTS);
if !rc {
// Process the error from a invalid authentication token.
} }
2.7.2.5 Perl
With Perl, support for two-factor authentication uses two methods of the Intersys::PERLBIND::Connection class:
• is_two_factor_enabled()
This method checks if two-factor authentication is enabled on the server. It returns a integer; 1 means that two-factor authentication is enabled and 0 means that it is disabled.
• send_two_factor_token($token)
This method provides the two-factor authentication token to the server. It returns a integer; 1 indicates success and 0 indicates failure. Its argument, $token, is the two-factor authentication token that the user has received and then entered at the client prompt. Note that the client application is responsible for obtaining the value of the token from the user.
Important: If two-factor authentication is enabled on the server and the client code does not implement two-factor authentication calls, then the server will drop the connection with the client.
The following example uses an instance of a connection called conn:
1. It uses that instance’s methods to check if two-factor authentication is enabled.
2. It attempts to provide the token to the server and performs error processing if this fails.
// Given a connection called "conn"
if ($conn->is_two_factor_enabled()) { # Prompt the user for the security token.
# Store the token in the "token" variable of type std::string.
if (!$conn->send_two_factor_token($token)) {
# Process the error from a invalid authentication token here.
} else {
# two-factor authentication succeeded }
else {
# Handle if two-factor authentication is not enabled on the server.
}
Caché comes with sample programs that demonstrate two-factor authentication with Perl. These programs are in the install-dir\dev\perl\ directory, and are samples\two_factor.pl. For more information on Perl sample programs for use with Caché, see the “Sample Programs” section of the “ Caché Perl Binding ” chapter of Using Perl with Caché.
2.7.2.6 Python
With Python, support for two-factor authentication uses two methods of the intersys.pythonbind.connection class:
• is_two_factor_enabled()
This method checks if two-factor authentication is enabled on the server. It returns a boolean; true means that two-factor authentication is enabled.
Configuring for Two-factor Authentication
• send_two_factor_token(token)
This method provides the two-factor authentication token to the server. It returns a boolean; true means that the user has been authenticated. It takes one argument, token, the two-factor authentication token that the user has received.
Note that the client application is responsible for obtaining the value of the token from the user.
Note: Python leaves carriage returns in input. This means that, when processing the security token, it is necessary to strip any carriage returns out of it.
Important: If two-factor authentication is enabled on the server and the client code does not implement two-factor authentication calls, then the server will drop the connection with the client.
The following example uses an instance of a connection called conn:
1. It uses that instance’s methods to check if two-factor authentication is enabled.
2. It attempts to provide the token to the server and performs error processing if this fails.
// Given a connection called "conn"
if conn.is_two_factor_enabled():
# Prompt the user for the security token.
# Store the token in the "token" variable of type std::string.
# Make sure that the carriage returns are stripped from the string.
if !conn.send_two_factor_token(token):
# Process the error from a invalid authentication token here.
else:
# two-factor authentication succeeded else:
# Handle if two-factor authentication is not enabled on the server.
Caché comes with sample programs that demonstrate two-factor authentication with Python. These programs are in the install-dir\dev\Python\ directory; they are samples\two_factor.py for Python 2.6 and samples3\two_factor.py for Python 3.0.
For more information on Python sample programs for use with Caché, see the “Sample Programs” section of the “ Caché Python Binding ” chapter of Using Python with Caché.