doc/standardisation/draft-brezak-win2k-krb-authz-01.txt

   1
   2
   3
   4 Kerberos working group                                      John Brezak
   5 Internet Draft                                                Microsoft
   6 Document: draft-brezak-win2k-krb-authz-01.txt
   7 Category: Informational                                   October, 2002
   8
   9
  10  Utilizing the Windows 2000 Authorization Data in Kerberos Tickets for
  11                       Access Control to Resources
  12
  13
  14 Status of this Memo
  15
  16    This document is an Internet-Draft and is subject to all provisions
  17    of Section 10 of RFC2026 [1] except that the right to create
  18    derivative works is not granted. Internet-Drafts are working
  19    documents of the Internet Engineering Task Force (IETF), its areas,
  20    and its working groups. Note that other groups may also distribute
  21    working documents as Internet-Drafts. Internet-Drafts are draft
  22    documents valid for a maximum of six months and may be updated,
  23    replaced, or obsoleted by other documents at any time. It is
  24    inappropriate to use Internet- Drafts as reference material or to
  25    cite them other than as "work in progress."
  26
  27    The list of current Internet-Drafts can be accessed at
  28    http://www.ietf.org/ietf/1id-abstracts.txt
  29
  30    The list of Internet-Draft Shadow Directories can be accessed at
  31    http://www.ietf.org/shadow.html.
  32
  33 1. Abstract
  34
  35    Microsoft Windows 2000 includes operating system specific data in
  36    the Kerberos V5 [1] authorization data field that is used for access
  37    control. This data is used to create an NT access token. The access
  38    token is used by the system to enforce access checking when
  39    attempting to access objects. This document describes the structure
  40    of the Windows 2000 specific authorization data that is carried in
  41    that field for use by servers in performing access control.
  42
  43
  44 2. Conventions used in this document
  45
  46    All defined data structures are defined using "C" style constructs
  47    unless otherwise stated. All data is encoded as little-endian.
  48
  49    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
  50    "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in
  51    this document are to be interpreted as described in RFC-2119 [2].
  52
  53
  54 3. Top-Level PAC Structure
  55
  56    The PAC is generated by the KDC under the following conditions:
  57
  58
  59 Brezak                 Category - Informational                      1 \f
  60                Windows 2000 Kerberos Authorization Data   October 2002
  61
  62
  63      o during an AS request that has been validated with pre-
  64         authentication
  65      o during a TGS request when the client has no PAC and the target
  66         is a service in the domain or a ticket granting service
  67         (referral ticket).
  68
  69    The PAC itself is included in the IF-RELEVANT (ID 1) portion of the
  70    authorization data in a ticket. Within the IF-RELEVANT portion, it
  71    is encoded KERB_AUTH_DATA_PAC with ID 128.
  72
  73    The PAC is defined as a C data type, with integers encoded in
  74    little-endian order. The PAC itself is made up of several layers.
  75    The outer structure, contained directly in the authorization data,
  76    is as follows. The top-level structure is the PACTYPE structure:
  77
  78         typedef unsigned long ULONG;
  79         typedef unsigned short USHORT;
  80         typedef unsigned long64 ULONG64;
  81         typedef unsigned char UCHAR;
  82
  83         typedef struct _PACTYPE {
  84             ULONG cBuffers;
  85             ULONG Version;
  86             PAC_INFO_BUFFER Buffers[1];
  87         } PACTYPE;
  88
  89    The fields are defined as follows:
  90    cBuffers - contains the number of entries in the array Buffers
  91    Version - this is version zero
  92    Buffers - contains a conformant array of PAC_INFO_BUFFER structures
  93
  94    The PAC_INFO_BUFFER structure contains information about each piece
  95    of the PAC.
  96
  97         typedef struct _PAC_INFO_BUFFER {
  98             ULONG ulType;
  99             ULONG cbBufferSize;
 100             ULONG64 Offset;
 101         } PAC_INFO_BUFFER;
 102
 103    Type fields are defined as follows:
 104
 105    ulType - contains the type of data contained in this buffer. For
 106            Windows 2000 access control, it may be one of the following,
 107            which are explained further below:
 108
 109            #define PAC_LOGON_INFO               1
 110            #define PAC_SERVER_CHECKSUM          6
 111            #define PAC_PRIVSVR_CHECKSUM         7
 112
 113    Offset - contains the offset to the beginning of the data, in bytes,
 114            from the beginning of the PACTYPE structure. The data offset
 115            must by a multiple of 8. If the data pointed to by this
 116
 117 Brezak                 Category - Informational                      2 \f
 118                Windows 2000 Kerberos Authorization Data   October 2002
 119
 120
 121            field is complex, the data is typically NDR encoded. If the
 122            data is simple (indicating it includes no pointer types or
 123            complex structures) it is a little-endian format data
 124            structure.
 125
 126 4. PAC Credential Information (PAC_LOGON_INFO)
 127
 128    PAC_INFO_BUFFERs of type PAC_LOGON_INFO contain the credential
 129    information for the client of the Kerberos ticket. The data itself
 130    is contained in a KERB_VALIDATION_INFO structure, which is NDR
 131    encoded. The output of the NDR encoding is placed in the
 132    PAC_INFO_BUFFER structure of type PAC_LOGON_INFO.
 133
 134         typedef struct _KERB_VALIDATION_INFO {
 135             FILETIME Reserved0;
 136             FILETIME Reserved1;
 137             FILETIME KickOffTime;
 138             FILETIME Reserved2;
 139             FILETIME Reserved3;
 140             FILETIME Reserved4;
 141             UNICODE_STRING Reserved5;
 142             UNICODE_STRING Reserved6;
 143             UNICODE_STRING Reserved7;
 144             UNICODE_STRING Reserved8;
 145             UNICODE_STRING Reserved9;
 146             UNICODE_STRING Reserved10;
 147             USHORT Reserved11;
 148             USHORT Reserved12;
 149             ULONG UserId;
 150             ULONG PrimaryGroupId;
 151             ULONG GroupCount;
 152             [size_is(GroupCount)] PGROUP_MEMBERSHIP GroupIds;
 153             ULONG UserFlags;
 154             ULONG Reserved13[4];
 155             UNICODE_STRING Reserved14;
 156             UNICODE_STRING Reserved15;
 157             PSID LogonDomainId;
 158             ULONG Reserved16[2];
 159             ULONG Reserved17;
 160             ULONG Reserved18[7];
 161             ULONG SidCount;
 162             [size_is(SidCount)] PKERB_SID_AND_ATTRIBUTES ExtraSids;
 163             PSID ResourceGroupDomainSid;
 164             ULONG ResourceGroupCount;
 165             [size_is(ResourceGroupCount)] PGROUP_MEMBERSHIP
 166         ResourceGroupIds;
 167         } KERB_VALIDATION_INFO;
 168
 169    Reserved fields are not defined in this document and are not used in
 170    the construction of access control tokens.
 171
 172    The fields are defined as follows:
 173
 174
 175 Brezak                 Category - Informational                      3 \f
 176                Windows 2000 Kerberos Authorization Data   October 2002
 177
 178
 179    KickOffTime - the time at which the server should forcibly logoff
 180            the client. If the client should not be forced off, this
 181            field should be set to (0x7fffffff,0xffffffff). If a kickoff
 182            time is to be enforced, the service ticket lifetime will
 183            never exceed this value.
 184    UserId - This field contains the relative Id for the client. If
 185            zero, then the User ID is the first SID in the ExtraSids
 186            field.
 187    PrimaryGroupId - This field contains the relative ID for this
 188            clientÆs primary group.
 189    GroupCount - This field contains the number of groups, within the
 190            clientÆs domain, to which the client is a member.
 191    GroupIds - This field contains an array of the relative Ids and
 192            attributes of the groups in the clientÆs domain of which the
 193            client is a member.
 194    UserFlags - This field contains information about which fields in
 195            this structure are valid. The two bits that may be set are
 196            indicated below. Having these flags set indicates that the
 197            corresponding fields in the KERB_VALIDATION_INFO structure
 198            are present and valid.
 199
 200            #define LOGON_EXTRA_SIDS             0x0020
 201            #define LOGON_RESOURCE_GROUPS        0x0200
 202
 203    LogonDomainId - This field contains the SID of the clientÆs domain.
 204            This field is used in conjunction with the UserId,
 205            PrimaryGroupId,and GroupIds fields to create the user and
 206            group SIDs for the client.
 207    SidCount - This field contains the number of SIDs present in the
 208            ExtraSids field. This field is only valid if the
 209            LOGON_EXTRA_SIDS flag has been set in the UserFlags field.
 210    ExtraSids - This field contains a list of SIDs for groups to which
 211            the user is a member. This field is only valid if the
 212            LOGON_EXTRA_SIDS flag has been set in the UserFlags field.
 213    ResouceGroupCount - This field contains the number of resource
 214            groups in the ResourceGroupIds field. This field is only
 215            valid if the LOGON RESOURCE_GROUPS flag has been set in the
 216            UserFlags field._
 217    ResourceGroupDomainSid - This field contains the SID of the resource
 218            domain. This field is used in conjunction with the
 219            ResourceGroupIds field to create the group SIDs for the
 220            client.
 221    ResourceGroupIds - This field contains an array of the relative Ids
 222            and attributes of the groups in the resource domain of which
 223            the resource is a member.
 224
 225    When used in the KERB_VALIDATION_INFO, this is NDR encoded. The
 226    FILETIME type is defined as follows:
 227
 228         typedef unsigned int DWORD;
 229
 230         typedef struct _FILETIME {
 231             DWORD dwLowDateTime;
 232
 233 Brezak                 Category - Informational                      4 \f
 234                Windows 2000 Kerberos Authorization Data   October 2002
 235
 236
 237             DWORD dwHighDateTime;
 238         } FILETIME;
 239
 240    Times are encoded as the number of 100 nanosecond increments since
 241    January 1, 1601, in UTC time.
 242
 243    When used in the KERB_VALIDATION_INFO, this is NDR encoded. The
 244    UNICODE_STRING structure is defined as:
 245
 246         typedef struct _UNICODE_STRING
 247             USHORT Length;
 248             USHORT MaximumLength;
 249             [size_is(MaximumLength / 2), length_is((Length) / 2) ]
 250         USHORT *  Buffer;
 251         } UNICODE_STRING;
 252
 253    The Length field contains the number of bytes in the string, not
 254    including the null terminator, and the MaximumLength field contains
 255    the total number of bytes in the buffer containing the string.
 256
 257    The GROUP_MEMBERSHIP structure contains the relative ID of a group
 258    and the corresponding attributes for the group.
 259
 260         typedef struct _GROUP_MEMBERSHIP {
 261             ULONG RelativeId;
 262             ULONG Attributes;
 263         } *PGROUP_MEMBERSHIP;
 264
 265    The group attributes must be:
 266
 267         #define SE_GROUP_MANDATORY              (0x00000001L)
 268         #define SE_GROUP_ENABLED_BY_DEFAULT     (0x00000002L)
 269         #define SE_GROUP_ENABLED                (0x00000004L)
 270
 271    The SID structure is defined as follows:
 272
 273
 274         typedef struct _SID_IDENTIFIER_AUTHORITY {
 275             UCHAR Value[6];
 276         } SID_IDENTIFIER_AUTHORITY, *PSID_IDENTIFIER_AUTHORITY;
 277
 278    The constant value for the NT Authority is
 279
 280         #define SECURITY_NT_AUTHORITY           {0,0,0,0,0,5}
 281
 282         typedef struct _SID {
 283            UCHAR Revision;
 284            UCHAR SubAuthorityCount;
 285            SID_IDENTIFIER_AUTHORITY IdentifierAuthority;
 286            [size_is(SubAuthorityCount)] ULONG SubAuthority[*];
 287         } SID, *PSID;
 288
 289
 290
 291 Brezak                 Category - Informational                      5 \f
 292                Windows 2000 Kerberos Authorization Data   October 2002
 293
 294
 295    Other authorities are defined in the Microsoft Developer Network
 296    Development Kit 3.
 297    The SubAuthorityCount field contains the number of elements in the
 298    actual SubAuthority conformant array. The maximum number of
 299    subauthorities allowed is 15.
 300
 301    The KERB_SID_AND_ATTRIBUTES structure contains entire group SIDs and
 302    their corresponding attributes:
 303
 304         typedef struct _KERB_SID_AND_ATTRIBUTES {
 305             PSID Sid;
 306             ULONG Attributes;
 307         } KERB_SID_AND_ATTRIBUTES, *PKERB_SID_AND_ATTRIBUTES;
 308
 309    The attributes are the same as the group attributes defined above.
 310
 311 5. Signatures (PAC_SERVER_CHECKSUM and PAC_PRIVSVR_CHECKSUM)
 312
 313    The PAC contains two digital signatures: one using the key of the
 314    server, and one using the key of the KDC. The signatures are present
 315    for two reasons. First, the signature with the serverÆs key is
 316    present to prevent a client from generating their own PAC and
 317    sending it to the KDC as encrypted authorization data to be included
 318    in tickets. Second, the signature with the KDCÆs key is present to
 319    prevent an untrusted service from forging a ticket to itself with an
 320    invalid PAC. The two signatures are sent in PAC_INFO_BUFFERs of type
 321    PAC_SERVER_CHECKSUM and PAC_PRIVSVR_CHECKSUM respectively.
 322
 323
 324    The signatures are contained in the following structure:
 325
 326         typedef struct _PAC_SIGNATURE_DATA {
 327             ULONG SignatureType;
 328             UCHAR Signature[1];
 329         } PAC_SIGNATURE_DATA, *PPAC_SIGNATURE_DATA;
 330
 331    The fields are defined as follows:
 332
 333    SignatureType - This field contains the type of checksum used to
 334            create a signature. The checksum must be a keyed checksum.
 335
 336    Signature - This field consists of an array of bytes containing the
 337            checksum data. The length of bytes may be determined by the
 338            wrapping PAC_INFO_BUFFER structure.
 339
 340    For the serverÆs checksum, the key used to generate the signature
 341    should be the same key used to encrypt the ticket. Thus, if the
 342    enc_tkt_in_skey option is used, the session key from the serverÆs
 343    TGT should be used. The Key used to encrypt ticket granting tickets
 344    is used to generate the KDCÆs checksum.
 345
 346    The checksums are computed as follows:
 347
 348
 349 Brezak                 Category - Informational                      6 \f
 350                Windows 2000 Kerberos Authorization Data   October 2002
 351
 352
 353      1. The complete PAC is built, including space for both checksums
 354      2. The data portion of both checksums is zeroed.
 355      3. The entire PAC structure is checksummed with the serverÆs key,
 356         and the result is stored in the serverÆs checksum structure.
 357      4. The serverÆs checksum is then checksummed with the KDC's key.
 358      5. The checksum with the KDC key is stored in the KDC's checksum
 359         structure.
 360
 361 6. PAC Request Pre-Auth Data
 362
 363    Normally, the PAC is included in every pre-authenticated ticket
 364    received from an AS request. However, a client may also explicitly
 365    request either to include or to not include the PAC. This is done by
 366    sending the PAC-REQUEST preauth data.
 367
 368    This is an ASN.1 encoded structure.
 369
 370         KERB-PA-PAC-REQUEST     ::= SEQUENCE {
 371                 include-pac[0] BOOLEAN -- if TRUE, and no pac present,
 372                                        -- include PAC.
 373                                        ---If FALSE, and pac
 374                                        -- PAC present, remove PAC
 375         }
 376
 377    The fields are defined as follows:
 378
 379    include-pac - This field indicates whether a PAC should be included
 380            or not. If the value is TRUE, a PAC will be included
 381            independent of other preauth data. If the value is FALSE,
 382            then no PAC will be included, even if other preauth data is
 383            present.
 384
 385    The preauth ID is:
 386         #define KRB5_PADATA_PAC_REQUEST         128
 387
 388 7. Security Considerations
 389
 390    Before the PAC data is used for access control, the
 391    PAC_SERVER_CHECKSUM signature MUST be checked. This will verify that
 392    the provider of the PAC data knows the server's secret key.
 393    Validation of the PAC_PRIVSVR_CHECKSUM is OPTIONAL. It is used to
 394    verify that the PAC was issued from the KDC and not placed in the
 395    ticket by someone other than the KDC with access to the service key.
 396
 397    Caution must be used with accepting the SIDs present in the logon-
 398    info part of the PAC. Only SIDs from a domain that is authoritative
 399    for a particular domain's SIDs should be used in the construction of
 400    access tokens. If a SID is found to be from outside of a domain's
 401    authoritative SID namespace, it MUST be ignored for purposes of
 402    access control.
 403
 404 8. References
 405
 406
 407 Brezak                 Category - Informational                      7 \f
 408                Windows 2000 Kerberos Authorization Data   October 2002
 409
 410
 411
 412    1 Kohl, J., Neuman, C., "The Kerberos Network Authentication Service
 413       (V5)", RFC 1510, September 1993
 414
 415    2 Bradner, S., "Key words for use in RFCs to Indicate Requirement
 416      Levels", BCP 14, RFC 2119, March 1997
 417
 418    3 Microsoft Developer's Network - http://msdn.microsoft.com
 419
 420
 421 9. Author's Addresses
 422
 423    John Brezak
 424    Microsoft Corporation
 425    One Microsoft Way
 426    Redmond, Washington
 427    Email: jbrezak@microsoft.com
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465 Brezak                 Category - Informational                      8 \f
 466                Windows 2000 Kerberos Authorization Data   October 2002
 467
 468
 469
 470 Full Copyright Statement
 471
 472    Copyright (C) The Internet Society (1999).  All Rights Reserved.
 473
 474    This document and translations of it may be copied and furnished to
 475    others, and derivative works that comment on or otherwise explain it
 476    or assist in its implementation may be prepared, copied, published
 477    and distributed, in whole or in part, without restriction of any
 478    kind, provided that the above copyright notice and this paragraph
 479    are included on all such copies and derivative works.  However, this
 480    document itself may not be modified in any way, such as by removing
 481    the copyright notice or references to the Internet Society or other
 482    Internet organizations, except as needed for the purpose of
 483    developing Internet standards in which case the procedures for
 484    copyrights defined in the Internet Standards process must be
 485    followed, or as required to translate it into languages other than
 486    English.
 487
 488    The limited permissions granted above are perpetual and will not be
 489    revoked by the Internet Society or its successors or assigns.
 490
 491    This document and the information contained herein is provided on an
 492    "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
 493    TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
 494    BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
 495    HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
 496    MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE."
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523 Brezak                 Category - Informational                      9 \f