﻿Common Authentication Service Adapter (CASA)

April 05, 2011


1.0  Overview

2.0  Documentation

3.0  Known Issues
     3.1  Secret ID Failure
     3.2  Upgrading the CASA Authentication Service
     3.3  Runtime Architecture Compatibility
     3.4  Unstable Login Conditions
     3.5  Manually Starting the Gnome Keyring
     3.6  Installing CASA Developer Packages
     3.7  Using CASA in chroot Environment

4.0  Open Source Code

5.0  Legal Notices


1.0  Overview

     Common Authentication Service Adapter (CASA)
     provides a common infrastructure for client
     authentication across the Linux and Microsoft
     Windows desktops. Novell products (such as
     GroupWise, GroupWise Messenger, iPrint, Novell
     iFolder, and the Novell clients for Windows and
     Linux) are integrated with the miCASA interface and
     can take advantage of the credential store that
     provides the cornerstone for CASA.

     CASA provides the following main components:

     -  CASA Identity Development Kit (IDK): The
        developer kit provides a set of APIs that
        application and service developers can use to
        write user/application credentials to the
        credential store. The APIs internally store the
        credentials passed onto them by the applications
        in miCASAd. There are C, C++, C# and Java
        bindings available for the CASA Identity
        Development Kit (IDK).

     -  Login Credential Capture Module: On Linux, the
        login credential capture module is implemented as
        a PAM module. This PAM module captures the user’s
        desktop login credentials and stores them in
        miCASAd using the IDK APIs. This PAM module is
        placed as the last module in the auth and session
        stacks of xdm, gdm, kdm, login and sshd PAM
        configuration files. In the auth stack, the
        functionality of this module is to store the
        credentials in miCASAd and in the session stack,
        then closes the user’s session with miCASAd.

     -  miCASAd: An active component that starts during
        boot time. 

        Linux:miCASAd stores and provides credentials or
        secrets based on the user identifier (uid) of the
        process that makes the IDK API calls. It is
        available in the run-levels 1, 2, 3 and 5. It
        runs with root privileges and is active as long
        as the system is up.

        Windows:CASA consists of a single "CASA.msi",
        which is the installation module that contains
        the following components that match their Linux
        counterparts:

        -  CASA-gui.msm

        -  CASA.msm

        A separate Windows package called
        "CASA-devel.msi" installs the CASA development
        kit.

        Credentials saved by user applications are
        encrypted and saved to the file system. When the
        user logs into the desktop, the credentials are
        read back into computer memory and made available
        to user applications.

        NOTE: Any pluggable authentication module (PAM)
        that uses the IDK APIs must set its effective
        user ID temporarily to that of the user logging
        in (the user returned by calling pam_get_user()),
        if the credentials need to be stored against that
        user. There might be cases where the user
        obtained through pam_get_user() might not be the
        one against whom the PAM module actually intends
        to store credentials.


2.0  Documentation

     The following sources provide information about
     CASA:

     -  Product documentation included with the software:
        The download includes a single file: "CASA
        Administration Guide(casa_enu.pdf) "in the
        [install directory]\doc directory. 

     -  Novell CASA online product documentation: Common
        Authentication Service Adapter
        (http://developer.novell.com/wiki/index.php/Casa)

     -  Bandit Open Source Common Authentication Services
        Adapter (CASA) Documentation

     To read or print the documentation, you need Adobe
     Acrobat Reader.

     The document in this download was created as a
     standalone file; therefore, links to files in other
     downloads will not resolve.


3.0  Known Issues

     Here are some known issues when deploying CASA 1.7:

     -  Section 3.1, Secret ID Failure

     -  Section 3.2, Upgrading the CASA Authentication
        Service

     -  Section 3.3, Runtime Architecture Compatibility

     -  Section 3.4, Unstable Login Conditions

     -  Section 3.5, Manually Starting the Gnome Keyring

     -  Section 3.6, Installing CASA Developer Packages

     -  Section 3.7, Using CASA in chroot Environment

     3.1  Secret ID Failure

          Secrets with IDs using \ as a reserved
          character might fail. This will be fixed in a
          future release.


     3.2  Upgrading the CASA Authentication Service

          There is a know problem with upgrading the CASA
          authentication service (ATS) to a later
          release.

          If you upgrade manually, you must first stop
          the CASA ATS before applying the upgrade. You
          do this by issuing the following command:

          /etc/init.d/casa_atsd stop

          You may then proceed with the upgrade.

          If the upgrade occurs as part of an automated
          update, then the CASA ATS must be restarted
          using the following procedure:

           1. Find the CASA ATS process that needs to be
              killed by entering the following command:

              ps -ef | grep casaats

           2. Kill the listed ATS process.

           3. Restart the CASA ATS by entering the
              following command:

              /etc/init.d/casa_atsd start


     3.3  Runtime Architecture Compatibility

          To avoid runtime problems, do not install CASA
          32 bit architecture RPMs intended for 64 bit
          architecture machines.


     3.4  Unstable Login Conditions

          Because CASA is tied to the Linux login process
          via a PAM, events that cause the system to
          become inconsistent or unstable might prevent
          users from logging in to workstations. Some
          possible causes of inconsistency or instability
          are:

          -  Installing 32 bit CASA RPMs on a 64 bit OS

          -  Performing a hard reset on the machine

          Use the following steps to restore the ability
          to login:

           1. Reboot the machine.

           2. When boot loader menu appears, execute
              init=/bin/bash on the command option line.
              This causes the machine to boot into a
              command shell with root privileges.

           3. To prevent the CASA daemon from loading
              during bootup, enter the following at the
              command prompt:  chkconfig micasad off

           4. With a console-based text editor (e.g., Vi,
              Emacs), remove all lines referencing the
              pam_micasa module in the following PAM
              configuration files (some files may not
              exist, depending on which desktop managers
              are installed):

              -  "/etc/pam.d/gdm"

              -  "/etc/pam.d/xdm"

              -  "/etc/pam.d/kdm"

              -  "/etc/pam.d/sshd"

              -  "/etc/pam.d/login"

           5. At the command prompt execute init 5 to
              boot into runlevel 5 to obtain a graphical
              login prompt. You should be able to login
              at this point.

           6. To enable CASA to run at boot time, open a
              shell and at the prompt type chkconfig
              micasad 1235. This causes micasad to run at
              runlevels 1, 2, 3, and 5.

           7. After you have restored login capabilities,
              resolve the inconsistency that prevented
              the initial login. If you had installed a
              32 bit CASA package on a 64 bit OS,
              uninstall the 32 bit package and install a
              CASA package built for 64 bit
              architectures. If you are recovering from a
              hard reset, no further action should be
              needed.


     3.5  Manually Starting the Gnome Keyring

          When logged in to a KDE session, the
          gnome-keyring-daemon does not run by default.
          Therefore, all applications that access the
          daemon, including the CASAManager, will not be
          able to access or manage the gnome-keyring.

          You can manually start the daemon by running
          the following command from a shell prompt:
          gnome-keyring-daemon

          After the gnome-keyring-daemon starts, it
          prints the GNOME_KEYRING_SOCKET environment
          variable and its value to the terminal. In
          Gnome, the daemon starts and the environment
          variable loads into your X session environment
          by default. However, in KDE, you must manually
          load this environment variable:

           1. Run a command similar to the following
              command from a shell prompt (replacing the
              value of the environment variable with what
              the daemon output to the screen when you
              started it):

              export
              GNOME_KEYRING_SOCKET=/tmp/keyring-oaTsPs/so
              cket

           2. Run the CASAManager GUI (from the same
              terminal you exported the variable from).

              You can now manage and use the
              gnome-keyring in KDE just like you could if
              you were logged into Gnome.


     3.6  Installing CASA Developer Packages

          "CASA-devel "packages are available only for
          software development and are not automatically
          included when installing a production Novell
          Open Enterprise Server. Developers should
          install "CASA-devel "at the same time
          "Auth-token-server-devel" and
          "Auth-token-client-devel "are installed. CASA
          is an Open Source project found at
          http://forge.novell.com/modules/xfmod/project/?
          casa. Download "CASA-devel" from there. 


     3.7  Using CASA in chroot Environment

          For an application to access CASA in a change
          root (chroot) environment, the root user must
          do the following:

           1. Copy the micasa libraries to the chroot
              directory, as shown in the following
              example:

              cp /usr/lib/libmicasa* <chrootdir>/usr/lib/

           2. Create the CASA socket file in the chroot
              directory by linking the current CASA
              socket. An example of how to do this is
              explained below:

               2.a. From the "<chrootdir>/var/run"
                    directory, execute the following
                    command:

                    ln /var/run/.novellCASA


          NOTE: The chrootdir must be on the same disk
          partition as /var/run.


4.0  Open Source Code

     Novell, hereby, offers to give any third party a
     complete machine-readable copy of the source code of
     Common Authentication Service Adapter (CASA) under
     the terms of Sections 1 and 2 of version 2 of the
     GNU General Public License as published by the Free
     Software Foundation, on a medium customarily used
     for software interchange. Please contact Novell
     Developer Services if you require a copy of the
     same.


5.0  Legal Notices

     Novell, Inc. makes no representations or warranties
     with respect to the contents or use of this
     documentation, and specifically disclaims any
     express or implied warranties of merchantability or
     fitness for any particular purpose. Further, Novell,
     Inc. reserves the right to revise this publication
     and to make changes to its content, at any time,
     without obligation to notify any person or entity of
     such revisions or changes.

     Further, Novell, Inc. makes no representations or
     warranties with respect to any software, and
     specifically disclaims any express or implied
     warranties of merchantability or fitness for any
     particular purpose. Further, Novell, Inc. reserves
     the right to make changes to any and all parts of
     Novell software, at any time, without any obligation
     to notify any person or entity of such changes.

     Any products or technical information provided under
     this Agreement may be subject to U.S. export
     controls and the trade laws of other countries. You
     agree to comply with all export control regulations
     and to obtain any required licenses or
     classification to export, re-export, or import
     deliverables. You agree not to export or re-export
     to entities on the current U.S. export exclusion
     lists or to any embargoed or terrorist countries as
     specified in the U.S. export laws. You agree to not
     use deliverables for prohibited nuclear, missile, or
     chemical biological weaponry end uses. Please refer
     to the Novell International Trade Services Web page
     (http://www.novell.com/info/exports/) for more
     information on exporting Novell software. Novell
     assumes no responsibility for your failure to obtain
     any necessary export approvals.

     Copyright © 2007-2011 Novell, Inc. All rights
     reserved. No part of this publication may be
     reproduced, photocopied, stored on a retrieval
     system, or transmitted without the express written
     consent of the publisher.

     For Novell trademarks, see the Novell Trademark and
     Service Mark list
     (http://www.novell.com/company/legal/trademarks/tmli
     st.html).

     All third-party trademarks are the property of their
     respective owners.



