Novell Home

Developing an NMAS Method

Novell Cool Solutions: Feature
By Gordon Mathis

Digg This - Slashdot This

Posted: 29 Sep 2005
 

Developing a Novell Modular Authentication Services (NMAS) method can be a challenging and even frustrating experience, especially if you are new to Novell products, which can be the case for some security vendors. Novell has a Developer Labs facility where, for a small fee, an experienced Novell engineer will work one-on-one with third party developers to build their NMAS method, while also providing training on any associated Novell products. This level of training has proven time and again to greatly reduce the time it takes to develop a new method. However, having stated that, I realize that many developers still prefer to do it themselves, so this article is designed to step a developer through writing a very basic NMAS method from start to finish. If more detailed information is required after reading this article, refer to the NMAS NDK documentation at http://developer.novell.com/ndk/nmas_doc.htm.

Many developers new to NMAS are security vendors and already have a product that is compatible with the Windows platform. Therefore, I will use the Windows platform for this article, but keep in mind that eDirectory is cross-platform. For a complete solution, some NMAS modules should be provided on NetWare and Linux platforms.

The benefit of NMAS is that it enables a security device to control access to the network rather than just gaining access to a stand-alone system. With NMAS you can create a method that will allow third party security devices to gain access to the Network. This is why NMAS is attractive to so many customers. To date, dozens of security vendors have developed NMAS methods.

Currently NMAS is dependent on Novell's eDirectory product and the NMAS server is installed with eDirectory. The NMAS client is included with the Novell Client.

Novell-supported platforms for eDirectory 8.7.3.7 are Windows 2000 Server with Service Pack 4 or later, and Windows Server 2003. However, Windows XP will work for testing purposes and is the platform I used for generating this article.

Installing the Novell Client and eDirectory 8.7.3

  1. Download eDirectory 8.7.3 (eDir_873_win_full.exe) from
    http://download.novell.com/Download?buildid=G4YlRnymPtU~

  2. Extract the eDir_873_win_full.exe to a temp directory: c:\downloads\eDir873

  3. Note: If re-installing eDirectory, delete the following directories. You may have to stop the dhost.exe service by using the Task Manager to free them.

    • C:\novell\nds
    • C:\Program Files\Common Files\novell

  4. Execute c:\downloads\eDir873\nt\Setup.exe

  5. Check both eDirectory and Novell Client.

  6. Select "Yes" to accept the license agreement.

  7. Select the Custom Installation so that you can remove the IPX protocol if installed and click Next

  8. Click Next

  9. Click Next

  10. Check Remove IPX if present and click Next

  11. Click Next

  12. Click Finish

  13. Note: The system will reboot at this point, but the installation should automatically continue once the system is restarted.

  14. After the system reboots, check the Workstation Only checkbox and log in with Administrator privileges.

  15. Click Next at the eDirectory Welcome dialog.

  16. Accept the license Agreement.

  17. Select the desired language and click Next.

  18. Click Next to accept the default location of C:\Novell\NDS.

  19. Click Yes create to create the directory

  20. Select the Create a new eDirectory tree radio button and click Next.

  21. Enter the following directory information to create new tree, then click Next:
    • Tree Name - CORP-TREE
    • Sever object context - CORP-NDS.novell
    • Admin Name - Admin
    • Admin Context - novell
    • Admin password - novell
  22. Click Next to accept the default port configuration.

  23. Click Next to accept the LDAP port configuration.

  24. Although not required, click the Clear All button to remove unused NMAS methods and click Next (this makes things less confusing later).

  25. Click Finish.

  26. Note: This has successfully installed eDirectory 8.7.3 which includes an older release of the NMAS server that will work fine for the following exercises. However, for the latest eDirectory patch SP7, which includes a new NMAS server version 2.3.9, see: http://support.novell.com/cgi-bin/search/searchtid.cgi?/2972138.htm.
    Before installing the NMAS 2.3.9 patch, you need to the following (otherwise you will be promptedand ask you to install them):

Installing ConsoleOne 1.3.6 on Windows

  1. Execute C:\downloads\eDir873\Console1\install.exe.

  2. Accept all the defaults for the remaining screens. You want all the snap-ins.

Testing the eDirectory Installation

  1. Log in to eDirectory by right-clicking the N in the icon tray and selecting NetWare Login.

  2. Enter the username (admin) and password and click OK.

  3. Right-click the N in the icon tray again and select NetWare Connections. Notice that admin is authenticated.

  4. Use ConsoleOne (Icon on desktop) to create a new user in eDirectory.
  5. Expand the NDS tree and select the organization object (novell), and then click the new user button in the tool bar.

  6. The only fields that are required for a user object are the Name and Surname.

  7. Note: Remember the username, because you will use it later.

Downloading Sample Code and Required NDK's

Although there is sample code included with the NMAS Novell Developer Kit (NDK), I will be referring to a very basic NMAS method I placed on Novell Forge - this sample code should simplify the process. The sample code has been compiled with Microsoft's Visual Studio 6.0, and there are build.bat files for each component. I have also included the binaries, which need to be placed in the correct location. (This is in case you do not have the Visual C++ compiler installed and cannot compile the code.)

  1. Download and install the Novell Modular Authentication Services NDK
    http://developer.novell.com/ndk/nmas.htm

  2. Download and install the NLM and NetWare Libraries for C NDK. The NMAS NDK is dependent on this NDK.
    http://developer.novell.com/ndk/clib.htm

  3. Download the sample code mini.zip for this article
    http://forge.novell.com/modules/xfref_library/detail.php?reference_id=2624

Creating a basic NMAS method

The NMAS method consists of three modules. The first module is the Login Client Modules (LCM). The LCM is typically a .dll and runs on a Windows client. The second module is the Login Server Module (LSM), which is either a .dll, .nlm, or .so since the LSM is typically a cross-platform module. The third module is the Method Management Interface (MMG), which is typically an iManager Plug-in or a ConsoleOne Snap-in. It is used to set the login credential on a user object in eDirectory.

Each NMAS method has a unique method ID number assigned by Novell. If you are developing a new method, you should complete the form at http://developer.novell.com/devres/vresource/vresform.html to obtain a range of numbers. After completing the form you will be assigned a range of 16 method ID numbers that can be used to create several different methods. For example, if a company has several security devices they may wish to use a different ID number for each device.

The following will step you through creating very basic LCM, LSM, and MMG modules that could be used to start creating your own NMAS method. Please note the sample code below uses the method ID of 1, which is reserved by Novell.

Installing the Sample Login Method

  1. Log in to eDirectory as admin.

  2. From ConsoleOne, expand the NDS tree, including the Security container object.

  3. Right-click the Authorized Login Methods container and select New -> Object -> SAS:NMAS Login Method
  4. Click OK.

  5. From the New Login Method Window, use the browse button to select the c:\mini\method\config.txt file.
  6. Click Open.

  7. Follow the prompts (take all defaults).

Building and Installing the LSM on the Server

  1. Review the c:\mini\lsm\lsm.cpp file

  2. Notice that this sample code uses the MAF protocol functions to communicate with the LCM and eDirectory. The LCM will have corresponding MAF functions. The second parameter on the MAF_End function of the LSM will ultimately determine whether the user is authenticated to the network. The LSM is always invoked first and is passed the user credentials from the Novell Client. If it successfully loads, then the corresponding LCM is invoked. Debugging an LSM on Windows is easily done by putting "__asm int 3" in the entry function. This will cause Windows to break and allow you to use Visual Studio's Visual Debugger to debug your code.

    In order to test a .dll LSM we need to use the debug version of NMAS. This version expects to find the LSM on the file system (c:\novell\nds\nmas\lsm), as opposed to the release version of NMAS, which expects to find the LSM in eDirectory as login method object (LMO). We will take a closer look at the signing process that converts the .dll to and .lmo later.

    EXTERNC NMASEXPORT int LSM00000001(MAF_Handle mh) 
    {
    // __asm int 3
    
    	int ccode = MAF_Begin(mh);
    
    	char testPassword[50];
    	long tLength = sizeof(testPassword);
    
    	if ((ccode = MAF_Read(mh, &tLength, testPassword)))
    	{
    		MAF_End(mh, ccode, 0, 0);
    		return -1;
    	}
    
    	char storedPassword[50];
    	long sLength = sizeof(storedPassword);
    
    	ccode = MAF_GetAttribute(mh, NMAS_AID_USER_SECRET_DATA, secretTag, &sLength, storedPassword);
    
    	int authenticated = NMAS_E_AUTH_FAILURE;
    
    	if(tLength == sLength && !strnicmp(testPassword, storedPassword, sLength))	
    		authenticated = NMAS_SUCCESS;		
    
    	ccode = MAF_Write (mh, sizeof(int), &authenticated);
    	
    	MAF_End(mh, authenticated, 0, 0);
    
    	return 0;
    }
  3. Create the directory structure c:\novell\nds\nmas\lsm on Windows NT/2000/XP system, which is used by the debug version of NMAS.

  4. Note: nmas\lsm is not there by default.

  5. From a Command Prompt Window, execute the c:\mini\lsm\build.bat batch file to compile the lsm.cpp file. This will build the LSM module and place it in the c:\novell\nds\nmas\lsm directory.

  6. Important: Make sure there are no errors generated from the previous step. It is best that you execute all the build.bat files from a Command Prompt Window instead of from Windows so you don't miss any compile errors.

  7. Create a single-line text file c:\novell\nds\nmas\lsm\idlist.txt that contains the following line:

  8. 0x01 lsm.dll LSM00000001
  9. Rename the release version of NMAS server c:\novell\nds\nmas.dlm to nmas.dlm.rel (save the release version for later).

  10. Copy the debug version of the NMAS server
    (C:\Novell\ndk\nmas\nmas_server_sdk\win32\bin\debug\nmas.dlm) to c:\novell\nds

  11. Restart the eDirectory service by selecting Novell eDirectory Services from Control Panels Window and clicking Shutdown. Wait until the Shutdown button is disabled, and then click Startup. (You may have wait an additional 15-30 seconds after the Startup button is active for server to start. The server is started when the list is populated with running .dlm's)


  12. Note: You can also stop and start the eDirectory service using the services icon in the Administrative Tools under control panel window.

Building and Installing the LCM on the Client (can be the same system)

  1. Review the c:\mini\lcm\lcm.cpp file

  2. Once again, notice that we are using the MAF protocol functions to communicate with the LSM. Both the LSM and LCM do a MAF_Begin and MAF_End, but if one reads the other one writes, and vice versa. The LCM is the module that interfaces with the security device to retrieve the user's security credential. In this sample code we simply display a DialogBox which prompts for a password. Note that this password is not the NDS password.
    EXTERNC __declspec(dllexport) int LCM00000001(MAF_Handle mh) 
    {	 	
    int ccode = DialogBox(Instance, MAKEINTRESOURCE(IDD_DIALOG1), 0, PasswordDlgProc);
    
    if(ccode = MAF_Begin(mh))
    		return 0;
    
    char buffer[80];
    	long length = sizeof(buffer);
    
    ccode = MAF_WriteRead(mh, strlen(password), password, &length, buffer);
    
    	if(!ccode)
    		ccode = *(int *) buffer;
    
    	MAF_End(mh, ccode, 0, 0);
    
    	return 0;
    }
  3. Execute the c:\NMAS Labs\lab1\lcm\build.bat batch file to compile the lcm.cpp file. This will build the LCM module and place it in the C:\Windows\System32 directory. (If Windows 2000 or NT change Windows\System32 to WinNT\System32)

  4. Execute the c:\mini\lcm\RegisteryEntry.reg file to create a new registry entry at HKEY_LOCAL_MACHINE\SOFTWARE\Novell\NMAS\1.0\LCM Paths

  5. Run regedit and verify that there is a new registry entry with the following values:
    • Value name: 00000001
      Value data: C:\Windows\System32\lcm.dll

  6. Important: Restart the system so that the lcm.dll is detected. Failure to do so will result in a -1663 error.

Build the MMG and initialize a user object.

When NMAS is installed, it extends the eDirectory schema to provide Config and Secret Store attributes used for storing data on either a user object or a LMO object. Data that is specific to a user is generally stored on a user object, while information that is common to all users would be stored on the method's LMO object. NMAS provides client management APIs to read and write from the Config Store, but only write to the Secret Store. Only LSM's can read from the Secret Store. The following code is a very simple application that writes a password to the NMAS Secret Store using the NMAS_PutLoginSecret API.

  1. Review the c:\mini\lsm\mmg.cpp file.
  2. int main(int argc, char* argv[])
    {
    	nuint32 methodID = 1;
    
    	wchar_t treeName[80];
    	printf("Enter the tree name: ");
    	_getws(treeName);
    
    	wchar_t userDN[80];
    	printf("Enter the user DN (example: username.novell): ");
    	_getws(userDN);
    
    	char password[80];
    	printf("Enter the secret password: ");
    	gets(password);
    
    	int passwordLength = strlen(password);
    
    	int ccode = NMAS_PutLoginSecret(treeName, 
    								userDN, 
    								sizeof(methodID),
    								&methodID, 
    								secretTag, 
    								passwordLength,
    								password);
    	
    	printf("NMAS_PutLoginSecret returned: %d\n", ccode);
    		
    	return 0;
    }
  3. Execute the c:\NMAS Labs\lab2\mmg\build.bat file to compile the mmg.cpp file

  4. Make sure the server is started, then log in as admin using the NDS sequence. It should already be the default sequence at this point. (Select the NDS sequence from the NMAS tab of the Novell Client).

  5. Execute the c:\mini\mmg\mmg.exe application. This will prompt for the Tree name, a user DN, and a new password.
  6. Use the user object you created after installing eDirectory. Its DN value should be <username>.novell if you followed the instructions above.


  7. Example:

      C:\NMAS Labs\lab2\mmg>mmg
      Enter the tree name: CORP-TREE
      Enter the user DN (example: username.novell): jdoe.novell
      Enter the secret password: password
      NMAS_PutLoginSecret returned: 0 //Make sure it returns a 0 here

Testing the Method, Using the Debug Version of NMAS

  1. Right-click the N in the icon tray at the bottom of the screen and select NetWare Connections.

  2. Detach from all connections by selecting a connection from the list and clicking the Detach and Refresh buttons.

  3. Right-click the N again and select NetWare Login.

  4. Enter the new username you created in the username field.

  5. Click Advance, then click the NMAStab.



  6. Click Sequences and select the lsm sequence.
  7. Click OK.


  8. Click OK to log in.



  9. When prompted, enter the password you assigned with the mmg.exe application.

  10. Check the NetWare connections to verify that you have valid IP connection.

Signing an NMAS Method

The release version of NMAS looks for signed NMAS methods (.LMO) in eDirectory, not on the file system. The following steps will help you sign the method we created to generate the required .LMO file. Once you have the .LMO file, you will re-install the method and switch back to the release version of NMAS.

  1. Copy c:\novell\nds\nmas\lsm\lsm.dll to the c:\mini\sign directory.

  2. From a Command Prompt, execute c:\mini\sign\keygen.bat to generate a method signing key pair.


  3. Example:

     >cd c:\mini\method
    >keygen
    Enter Vendor Name: ACME, Inc.
    Password: ******
    Retype Password: ******
  4. Execute c:\mini\sign\cr.bat to generate a certificate signing request for your public key and specify an authentication grade.

  5. Grade Hex Value
    Logged In 0x00000000  
    Biometric 0x00200000
    Password 0x00800000
    Token 0x00400000
    Biometric and Password 0x00A00000
    Biometric and Token 0x00600000
    Password and Token 0x00C00000
    Biometric and Password and Token   0x00E00000

    Example:

    >cr 0x00000000
    Password: ******

    Note: At this point you would need to send the Certificate Signing Request (CSR) csr.ber to devsup@novell.com to be signed by Novell. Make sure you include your method ID#, the LSM's entry function name (e.g., LSM00000xxx), and the Grade. You would receive two files from Novell: cert.ber (your signed certificate) and mib.ber (your module identification block). You would copy those files to your module-signing directory and use them with the sign.bat file.

    With the cert.ber and mib.ber from Novell, you are ready to execute sign.bat to complete the signing process. For security reasons, we will not complete this last step. Instead, you should use the c:\mini\sign\LSM.DLL.LMO file provided.

    Note: This step has already been done for you - it is shown here only as an example.

    Execute c:\mini\sign\sign.bat to sign the method and create the .lmo file

    Example:
    >sign lsm.dll lsm.dll LSM00000001
    Password: ******	

    Copy LSM.DLL.LMO from the c:\mini\sign directory to the c:\mini\method directory.

    Installing the Method into eDirectory

    In order to use the release version of NMAS, you need to modify the config.txt to include the LSM.DLL.LMO, and then re-install the method. In the following steps you will notice that we have to remove the sequence and method before re-installing the same method from the config.txt file. By default, a new sequence with the same name as the method is created when you install a method.

    1. Modify the c:\mini\method\config.txt so it includes lsm.dll.lmo

    2. Example:
      Name = lsm
      Vendor = Novell
      Grade = Password
      Method id = 1
      Description file = descrip.txt
      License file = license.txt
      Support file = support.txt
      Logo file = novell.gif
      LSM WINNT = lsm.dll.lmo
    3. Log in to eDirectory as admin.

    4. From ConsoleOne, select the Security container.

    5. Select the properties of the Login Policy object.

    6. Select lsm from the Defined Login Sequences combo box.
    7. Click Delete Sequence at the bottom of the window.

    8. Click Apply button and then Close.

    9. Expand the tree to the Authorized Login Methods and delete the lsm method.

    10. Right-click the Authorized Login Methods container and select New -> Object -> SAS:NMAS Login Method.
    11. Click OK.
    12. From the New Login Method Window, use the browse button to select the c:\NMAS Labs\lab3\Method\config.txt file.
    13. Click Open.

    14. Follow the prompts (take all defaults).

    Switching from the Debug to the Release Version of NMAS

    1. Rename c:\novell\nds\nmas.dlm to nmas.dlm.dbg

    2. Rename c:\novell\nds\nmas.dlm.rel to nmas.dlm

    3. Restart the eDirectory service.

    Using the New Sample Method to Log In

    1. Right-click the N in the icon tray at the bottom of the screen and select NetWare Connections.

    2. Detach from all connections by selecting a connection from the list and clicking the Detach and Refresh buttons.

    3. Right-click the red N again and select NetWare Login.

    4. Enter the new username you created for the username field.

    5. Click Advance.
    6. Click the NMAS tab and make sure the lsm sequence is selected.

    7. Click OK to log in.

    Troubleshooting

    Here are some of the common errors that you might experience when doing NMAS and some suggestions on how to fix them.

    Problem – No textual error messages from the Novell Client, simply shows 0xFFFFFxxx with error messages.
    Solution – Download and install the Novell Client 4.91 or newer from http://download.novell.com/index.jsp

    or

    Solution – eDirectory server is not running. Start the eDirectory service by selecting Novell eDirectory Services from Control Panel window and click Startup.

    or



    Solution –
    1. Make sure you can run your LSM using the debug version of NMAS. The debug version loads a command prompt window.
    2. Make sure your .dll is in the \novell\nds\nmas\lsm directory and that the idlist.txt is correct.
    3. Use depends.exe on the lsm.dll to make sure all dependencies are being met. One missing dependency will cause it not to load. (It my be necessary to add c:\novell\nds to the PATH environment variable.)
    4. Put "__asm int 3" in the entry function and try debugging with Visual Debugger.


    Solution –
    1. Make sure your lcm.dll is in the C:\windows\system32 directory and is identified by the entry in the Windows registry.
    2. Restart the workstation so that the lcm.dll is detected.
    3. Use depends.exe on the lcm.dll to make sure all dependencies are being met.
    4. Launch C:\windows\system32\loginw32.exe from Visual Studio to debug the lcm.dll


    Solution –
    1. You have not set the user credential using your MMG module.
    2. You are using the wrong password (use the method password, not the NDS password).


    Solution –
    1. Try using the system's IP address for the Tree name under the NDS tab.

    Problem – No sequences other than the default NDS sequence.
    Solution –

    1. Use ConsoleOne or iManager to install a method from a config.txt file.


    Novell Cool Solutions (corporate web communities) are produced by WebWise Solutions. www.webwiseone.com

© 2014 Novell