/*
 * Copyright (c) Likewise Software.  All rights Reserved.
 *
 * This library is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the license, or (at
 * your option) any later version.
 *
 * This library 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 Lesser
 * General Public License for more details.  You should have received a copy
 * of the GNU Lesser 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
 * LESSER 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
 */

/*
 * Module Name:
 *
 *        fsd-guide.doxy
 *
 * Page Name:
 *
 *        fsd-security.doxy
 *
 * Abstract:
 *
 *        Security documentation section of the file system driver guide
 *
 * Authors: Rafal Szczesniak (rafal@likewise.com)
 *
 */

/**
@page fsd-security Security

@section security-introduction Introduction

Likewise environment implements Windows security model therefore it is
organised around the following concepts:

  - Each user or group is identified by a #SID (Security Identifier)
  - Accessing resources (e.g. files and directories) is possible by using #ACCESS_TOKEN.
    It is created everytime user successfully connects to the system.
  - Resources are protected by means of security descriptors which specify
    what type of access can be granted (or denied) to whom
  - In some cases where special access rights are needed, or a resource is not
    protected with security descriptor, user may use privileges it has granted
    in the local system

@subsection security-sid Security Identifier (#SID)

Each user and group is identified by unique SID. Typically, #SID is assigned by
the local system or domain controller. However, #SID can also be well-known, either
because one of its parts - RID (Relative Identifier) - is well-known or because
the entire #SID is well-known.

Since Likewise runs on Linux and FreeBSD systems, users and groups can also have
unix user and group ids assigned, so it is possible to map uid or gid to
the corresponding #SID.

@subsection security-token Access Token (#ACCESS_TOKEN)

Access token describes user security context. It includes the following elements:
  - User #SID
  - Primary Group #SID
  - List of groups the user is member of, if any
  - List of privileges granted, if any

Since Likewise does not run on Windows, access token is not associated with every
process. Instead, it has to be created when needed (typically soon after authentication
phase or creating a user connection context), by calling one of @ref LwMapSecurity
functions:
  - #LwMapSecurityCreateAccessTokenFromUidGid (passing user uid and gid)
  - #LwMapSecurityCreateAccessTokenFromUnicodeStringUsername (passing username)
  - #LwMapSecurityCreateAccessTokenFromAnsiStringUsername (passing username)
  - #LwMapSecurityCreateAccessTokenFromWC16StringUsername (passing username)
  - #LwMapSecurityCreateAccessTokenFromCStringUsername (passing username)
  - #LwMapSecurityCreateAccessTokenFromGssContext (passing gss security context)
  - #LwMapSecurityCreateAccessTokenFromNtlmLogon (passing #LW_MAP_SECURITY_NTLM_LOGON_INFO logon info)

Each of these functions, apart from arguments identifying a user, require
a pointer to #LW_MAP_SECURITY_CONTEXT. Refer to @ref LwMapSecurity API documentation
for more information on creating and maintaining @ref LwMapSecurity context.

@subsection example-token Example: Creating access token from username

@code
NTSTATUS ntStatus = STATUS_SUCCESS;
PACCESS_TOKEN accessToken = NULL;

// Here, we're assuming that LW_MAP_SECURITY_CONTEXT has already
// been created and UserName is available.

ntStatus = LwMapSecurityCreateAccessTokenFromCStringUsername(
                        Context,
                        &accessToken,
                        UserName);
if (ntStatus != STATUS_SUCCESS)
{
    goto cleanup;
}

cleanup:
// Release the token once we're done
RtlReleaseAccessToken(&accessToken);

@endcode

@subsection security-sd Security Descriptors

*/
