/* Editor Settings: expandtabs and use 4 spaces for indentation
 * ex: set softtabstop=4 tabstop=8 expandtab shiftwidth=4: *
 * -*- mode: c, c-basic-offset: 4 -*- */

/*
 * Copyright Likewise Software    2004-2008
 * All rights reserved.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or (at
 * your option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * for more details.  You should have received a copy of the GNU General
 * Public License along with this program.  If not, see
 * <http://www.gnu.org/licenses/>.
 *
 * LIKEWISE SOFTWARE MAKES THIS SOFTWARE AVAILABLE UNDER OTHER LICENSING
 * TERMS AS WELL.  IF YOU HAVE ENTERED INTO A SEPARATE LICENSE AGREEMENT
 * WITH LIKEWISE SOFTWARE, THEN YOU MAY ELECT TO USE THE SOFTWARE UNDER THE
 * TERMS OF THAT SOFTWARE LICENSE AGREEMENT INSTEAD OF THE TERMS OF THE GNU
 * GENERAL PUBLIC LICENSE, NOTWITHSTANDING THE ABOVE NOTICE.  IF YOU
 * HAVE QUESTIONS, OR WISH TO REQUEST A COPY OF THE ALTERNATE LICENSING
 * TERMS OFFERED BY LIKEWISE SOFTWARE, PLEASE CONTACT LIKEWISE SOFTWARE AT
 * license@likewisesoftware.com
 */

/*
 * Copyright (C) Likewise Software. All rights reserved.
 *
 * Module Name:
 *
 *        unprov.h
 *
 * Abstract:
 *
 *        Likewise Security and Authentication Subsystem (LSASS)
 *
 *        Authentication Provider Interface
 *
 * Authors:
 *        Wei Fu (wfu@likewisesoftware.com)
*/

/**
 * @file unprov.h
 * @brief Unprov plugin Interface
 */

#ifndef UNPROV_H_
#define UNPROV_H_

/**
 * @defgroup unprovplugin Unprov plugin Interface
 * @ingroup oem
 * @brief Unprov plugin interface
 *
 * This plugin provides mappings between names, SIDs, and UNIX IDs
 * (UIDs and GIDs).
 *
 * The default algorithm to generate a UID or GID from a SID essentially
 * hashes the domain portion of the SID into 12 bits and combines that
 * with the 19 lowest order bits of the RID:
 * @code
 * UID or GID = (hash-to-12-bits(DOMAIN-PART-OF-SID) <<19) | (RID mod 2^19)
 * @endcode
 * Look at @a LsaHashSecurityIdentifierToId for the actual implentation.
 *
 * The algorithm to convert from a UID or GID back to a SID extracts
 * the 19 RID bits from the UID or GID, combines them with each known
 * domain SID, uses the algorithm above to compute a UID or GID, and
 * looks for a match.
 *
 * @note This algorithm cannot handle RIDs greater than 2^19-1.
 */

/*@{*/

/**
 * @brief Initialize the plugin
 *
 * Initialize the plugin.
 *
 * @return A plugin-specific error code.
 */
DWORD
ADUnprovPlugin_Initialize(
    VOID
    );

/**
 * @brief Shutdown the plugin
 *
 * Shutdown the plugin.
 */
VOID
ADUnprovPlugin_Cleanup(
    VOID
    );

/**
 * @brief Determine whether the plugin supports aliases
 *
 * Determine whether the plugin supports aliases.
 *
 * @retval TRUE  The plugin supports aliases.
 * @retval FALSE The plugin does not support aliases.
 */
BOOLEAN
ADUnprovPlugin_SupportsAliases(
    VOID
    );

/**
 * @brief Convert a group or user SID to GID or UID
 *
 * Convert a group or user SID to GID or UID.
 *
 * @param[in] pState     The provider state context.
 * @param[in] bIsUser    Whether the object is a user.
 * @param[in] pszNT4Name The object's NT4 style name.  Only
 * required if @a ppszAlias is requested.
 * @param[in] pszSID     The object's SID.
 * @param[out] ppszAlias Optional, set to the object's name
 * @param[out] pdwId     Set to the object's uid or gid.
 *
 * @return A plugin-specific error code.
 */
DWORD
ADUnprovPlugin_QueryByReal(
    IN PLSA_AD_PROVIDER_STATE pState,
    IN BOOLEAN bIsUser,
    IN PCSTR pszNT4Name,
    IN PCSTR pszSID,
    OUT OPTIONAL PSTR* ppszAlias,
    OUT PDWORD pdwId
    );

/**
 * @brief Convert a group or user name to SID and GID or UID
 *
 * Convert a group or user name to SID and GID or UID.
 *
 * @param[in] pState     The provider state context.
 * @param[in] bIsUser    Whether the object is a user.
 * @param[in] pszAlias   The object's name.
 * @param[out] ppszSid   Set to the object's SID.
 * @param[out] pdwId     Set to the object's GID or UID.
 *
 * @return A plugin-specific error code.
 */
DWORD
ADUnprovPlugin_QueryByAlias(
    IN PLSA_AD_PROVIDER_STATE pState,
    IN BOOLEAN bIsUser,
    IN PCSTR pszAlias,
    OUT PSTR* ppszSid,
    OUT PDWORD pdwId
    );

/**
 * @brief Convert a GID or UID to SID and name
 *
 * Convert a GID or UID to SID and name.
 *
 * @param[in] pState     The provider state context.
 * @param[in] bIsUser    Whether the object is a user.
 * @param[in] dwId       The object's GID or UID.
 * @param[out] ppszSid   Set to the object's SID.
 * @param[out] ppszAlias Set to the object's name
 *
 * @return A plugin-specific error code.
 */
DWORD
ADUnprovPlugin_QueryById(
    IN PLSA_AD_PROVIDER_STATE pState,
    IN BOOLEAN bIsUser,
    IN DWORD dwId,
    OUT PSTR* ppszSid,
    OUT PSTR* ppszAlias
    );

/*@}*/

#endif /* UNPROV_H_ */
