external/bsd/openldap/dist/doc/rfc/rfc2649.txt

   1
   2
   3
   4
   5
   6
   7 Network Working Group                                       B. Greenblatt
   8 Request for Comments: 2649                                     P. Richard
   9 Category: Experimental                                        August 1999
  10
  11
  12       An LDAP Control and Schema for Holding Operation Signatures
  13
  14 Status of this Memo
  15
  16    This memo defines an Experimental Protocol for the Internet
  17    community.  It does not specify an Internet standard of any kind.
  18    Discussion and suggestions for improvement are requested.
  19    Distribution of this memo is unlimited.
  20
  21 Copyright Notice
  22
  23    Copyright (C) The Internet Society (1999).  All Rights Reserved.
  24
  25 Abstract
  26
  27    In many environments clients require the ability to validiate the
  28    source and integrity of information provided by the directory.  This
  29    document describes an LDAP message control which allows for the
  30    retrieval of digitally signed information. This document defines an
  31    LDAP v3 based mechanism for signing directory operations in order to
  32    create a secure journal of changes that have been made to each
  33    directory entry.  Both client and server based signatures are
  34    supported.  An object class for subsequent retrieval are "journal
  35    entries" is also defined.  This document specifies LDAP v3 controls
  36    that enable this functionality.  It also defines an LDAP v3 schema
  37    that allows for subsequent browsing of the journal information.
  38
  39 Table of Contents
  40
  41    1. Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
  42    1.1 Audit Trail Mechanism  . . . . . . . . . . . . . . . . . . .   2
  43    1.2. Handling the Delete Operation . . . . . . . . . . . . . . .   5
  44    2. Signed Results Mechanism  . . . . . . . . . . . . . . . . . .   6
  45    3. Security Considerations and Other Notes   . . . . . . . . . .   7
  46    4. References  . . . . . . . . . . . . . . . . . . . . . . . . .   8
  47    5. Authors' Addresses  . . . . . . . . . . . . . . . . . . . . .   9
  48    6. Full Copyright Statement  . . . . . . . . . . . . . . . . . .  10
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58 Greenblatt & Richard          Experimental                      [Page 1]
  59 \f
  60 RFC 2649                LDAP Control and Schema              August 1999
  61
  62
  63 1.  Introduction
  64
  65    In many environments clients require the ability to validiate the
  66    source and integrity of information provided by the directory.  This
  67    document describes an LDAP message control which allows for the
  68    retrieval of digitally signed information.  The perspective of this
  69    document is that the origin of the information that is stored in LDAP
  70    v3 accessible directories is the LDAP v3 client that creates the
  71    information.  The source and integrity of the information is
  72    guaranteed by allowing for the digital signing of the operations that
  73    make changes to entries in the directory.  The source and integrity
  74    of an individual LDAP connection can be guaranteed by making use of
  75    an underlying session layer that provides such services, such as TLS.
  76    Note that the integrity of an individual connection does not, in and
  77    of itself guarantee the integrity of the data that comes across the
  78    connection.  This is due to the fact that the LDAP server is only
  79    capable of providing information that it has stored.  In distributed
  80    and replicated environments, the fact that an entry has been
  81    successfully retrieved from a server may not be completely
  82    reassuring, if the entry in question was replicated from an untrusted
  83    domain.
  84
  85    By making use of public key technology, and creating digitally signed
  86    transactions that are created by the LDAP v3 client as entries are
  87    created and modified, a complete journal of the history of the entry
  88    is available.  Since each entry in the journal has been digitally
  89    signed with the private key of the creator, or modifier of the entry,
  90    the source and integrity of the directory entry can be validated by
  91    verifying the signature of each entry in the journal.  Note that not
  92    all of the journal entries will have been signed by the same user.
  93
  94 1.1.  Audit Trail Mechanism
  95
  96    Signed directory operations is a straightforward application of
  97    S/MIME technology that also leverages the extensible framework that
  98    is provided by LDAP version 3.  LDAP version 3 is defined in [4], and
  99    S/MIME is defined in [2].  The security used in S/MIME is based in
 100    the definitions in [1].  The basic idea is that the submitter of an
 101    LDAP operation that changes the directory information includes an
 102    LDAP version 3 control that includes either a signature of the
 103    operation, or a request that the LDAP server sign the operation on
 104    the behalf of the LDAP client.  The result of the operation (in
 105    addition to the change of the directory information), is additional
 106    information that is attached to directory objects, that includes the
 107    audit trail of signed operations.  The LDAP control is (OID =
 108    1.2.840.113549.6.0.0):
 109
 110
 111
 112
 113
 114 Greenblatt & Richard          Experimental                      [Page 2]
 115 \f
 116 RFC 2649                LDAP Control and Schema              August 1999
 117
 118
 119       SignedOperation ::= CHOICE {
 120            signbyServer   NULL,
 121            signatureIncluded   OCTET STRING
 122        }
 123
 124    If the SignatureIncluded CHOICE is used, then the OCTET string is
 125    just an S/MIME message of the multipart/signed variety, that is
 126    composed of a single piece, that is the signature of the directory
 127    operation.  Multipart/signed MIME objects are defined in [3].  If the
 128    SignbyServer CHOICE us used, then the LDAP server creates the
 129    signature on behalf of the client, using its own identity and not the
 130    identity of the client, in order to produce the audit trail entry.
 131    In either case the successful result of processing the control is the
 132    creation of additional information in the directory entry that is
 133    being modified or created. The signature of the LDAP operation is
 134    computed on the LDAPMessage prior to the inclusion of the
 135    SignedOperation control. The procedure is as follows:
 136
 137       - Build LDAPMessage without the SignedOperation control
 138       - Compute signature on the above LDAPMessage
 139       - Create new LDAPMessage that includes the old MessageID,
 140         protocolOp and any control fields from the previous LDAPMessage,
 141         plus  the computed signature formatted as an S/MIME message.
 142
 143    No control is defined for the server to return in the LDAPResult as
 144    defined in [4].  The LDAP server MAY attempt to parse and verify the
 145    signature included in the SignedOperation control, but is not
 146    required to.  The server can accept the signed operation without
 147    verifying the signature.  Signature verification can be quite a
 148    lengthy operation, requiring complex certificate chain traversals.
 149    This allows a more timely creation of the audit trail by the server.
 150    Any LDAP client browsing the directory that retrieves the 'Changes'
 151    (defined in the following paragraphs) attributes, should verify the
 152    signature of each value according to the local signature verification
 153    policies.  Even if the LDAP server verifies the signature contained
 154    in the singed operation, the LDAP client has no way of knowing what
 155    policies were followed by the server in order to verify the
 156    signature.
 157
 158    If the LDAP server is unable to verify the signature and wishes to
 159    return an error then the error code unwillingToPerform(53) should be
 160    returned, and the entire LDAP operation fails.  In this situation, an
 161    appropriate message (e.g. "Unable to verify signature") MAY be
 162    included in the errorMessage of the LDAPResult.  The SignedOperation
 163    Control MAY be marked CRITICAL, and if it is CRITICAL then if the
 164    LDAP Server performs the LDAP operation, then must include the
 165    signature in the signedAuditTrail information.
 166
 167
 168
 169
 170 Greenblatt & Richard          Experimental                      [Page 3]
 171 \f
 172 RFC 2649                LDAP Control and Schema              August 1999
 173
 174
 175       The schema definition for the signedAuditTrail information is:
 176
 177       ( 1.2.840.113549.6.1.0
 178       NAME 'signedAuditTrail'
 179       SUP top
 180       AUXILIARY
 181       MUST (
 182       Changes
 183       )
 184          )
 185
 186       The format of the Changes attribute is:
 187
 188       ( 1.2.840.113549.6.2.0
 189       NAME 'Changes'
 190       DESC 'a set of changes applied to an entry'
 191       SYNTAX 'Binary' )
 192
 193       The actual format of the Changes attribute is:
 194
 195       Changes ::= SEQUENCE {
 196            sequenceNumber [0] INTEGER (0 .. maxInt),
 197            signedOperation [1] OCTET STRING }
 198
 199    The SignedOperation attribute is a multipart/signed S/MIME message.
 200    Part 1 of the message is the directory operation, and part 2 is the
 201    signature.  Sequence number 0 (if present) always indicates the
 202    starting point directory object as represented by the definitions in
 203    "A MIME Content-Type for Directory Information", as defined in [5].
 204    Subsequent sequence numbers indicate the sequence of changes that
 205    have been made to this directory object.  Note that the sequence of
 206    the changes can be verified due to the fact that the signed directory
 207    object will have a timestamp as part of the signature object, and
 208    that the sequence numbering as part of the change attribute should be
 209    considered to be an unverified aid to the LDAP client.  Sequence
 210    numbers are meaningful only within the context of a single directory
 211    entry, and LDAP servers are not expected to maintain these sequence
 212    numbers across all entries in the directory.
 213
 214    Some LDAP servers will only allow operations that include the
 215    SignedOperation control.  This is indicated by the inclusion of a
 216    'signedDirectoryOperationSupport' attribute in the rootDSE.  This
 217    attribute is defined as:
 218
 219
 220
 221
 222
 223
 224
 225
 226 Greenblatt & Richard          Experimental                      [Page 4]
 227 \f
 228 RFC 2649                LDAP Control and Schema              August 1999
 229
 230
 231       1.2.840.113549.6.2.2
 232       NAME 'signedDirectoryOperationSupport'
 233       DESC 'how many of the LDAP operations must be signed'
 234       SYNTAX 'Integer' SINGLE-VALUE )
 235
 236    The 'signedDirectoryOperationSupport' attribute above may have one of
 237    the values, '0', '1' or '2' with the following meanings:
 238
 239       - '0' Directory Operations may be signed
 240       - '1' Directory Operations must always be signed
 241       - '2' Directory Operations must never be signed
 242
 243    Some LDAP servers will desire that the audit trail be continuous, and
 244    not contain any gaps that would result from unsigned operations.
 245    Such server will include a signature on each LDAP operation that
 246    changes a directory entry, even when the LDAP client does not include
 247    a signed-Operation control.
 248
 249 1.2.  Handling the Delete Operation
 250
 251    The LDAP Delete operation represents an interesting case for Signed
 252    Directory Operations.  This is due to the case that subsequent to the
 253    successful completion of the Delete Operation, the object that would
 254    have held the latest 'Changes' attribute no longer exists.  In order
 255    to handle this situation, a new object class is defined to represent
 256    a directory object that has been deleted.
 257
 258       ( 1.2.840.113549.6.1.2
 259       NAME 'zombieObject'
 260       SUP top
 261       STRUCTURAL
 262       MUST (
 263       Cn $ Changes $ OriginalObject
 264       )
 265          )
 266
 267       The format of the OriginalObject attribute is:
 268
 269       ( 1.2.840.113549.6.2.1
 270       NAME OriginalObject
 271       DESC 'The LDAP URL of an object that has been deleted from the
 272       directory' SYNTAX 'Binary' )
 273
 274    The OriginalObject attribute contains the URL of the object that was
 275    deleted from the directory.  It is formatted in accordance with RFC
 276    2255.  Directory servers that comply with this specification SHOULD
 277    create a zombieObject when performing the delete Operation that
 278    contains a SignedOperation LDAPControl.  The Cn attribute of the
 279
 280
 281
 282 Greenblatt & Richard          Experimental                      [Page 5]
 283 \f
 284 RFC 2649                LDAP Control and Schema              August 1999
 285
 286
 287    zombieObject is synthesized by the LDAP server, and may or may not be
 288    related to the original name of the directory entry that was deleted.
 289    All changes attributes that were attached to the original entry are
 290    copied over to the zombieObject.  In addition the LDAP Server MUST
 291    attach the signature of the Delete operation as the last successful
 292    change that was made to the entry.
 293
 294 2.  Signed Results Mechanism
 295
 296    A control is also defined that allows the LDAP v3 client to request
 297    that the server sign the results that it returns.  It is intended
 298    that this control is primarily used in concert with the LDAPSearch
 299    operation.  This control MAY be marked as CRITICAL.  If it is marked
 300    as CRITICAL and the LDAP Server supports this operation, then all
 301    search results MUST be returned with a signature as attached in the
 302    SignedResult control if it is willing to sign results for this user.
 303    If the server supports this control but does not wish to sign the
 304    results for this user then the error code unwillingToPerform(53)
 305    should be returned, and the LDAP search will have failed.  In this
 306    situation, an appropriate message (e.g. "Unwilling to sign results
 307    for you!") MUST be included in the errorMessage of the LDAPResult.
 308    If the LDAPSigType has the value FALSE then the client is requesting
 309    that the server not sign this operation.  This may be done in
 310    situations where servers are configured to always sign their
 311    operations.
 312
 313    The LDAP control to include in the LDAP request is (OID =
 314    1.2.840.113549.6.0.1):
 315
 316       DemandSignedResult ::=  LDAPSigType
 317
 318       LDAPSigType ::= BOOLEAN
 319
 320    In response to a DemandSignedResult control, the LDAP v3 server will
 321    return a SignedResult control in addition to the normal result as
 322    defined by the operation (assuming that the server understands the
 323    con- trol, and is willing to perform it).  The SignedResult control
 324    MUST NOT be marked CRITICAL.  Some LDAP v3 servers may be configured
 325    to sign all of their operations.  In this situation the server always
 326    returns a SignedResult control, unless instructed otherwise by the
 327    DemandSigne-dResult Control.  Since the SignedResult control is not
 328    marked critical, the LDAP client is allowed to ignore it.  The
 329    signature field below includes the signature of the enitre LDAPResult
 330    formatted as an S/MIME pkcs-7/signature object, as defined in [2].
 331
 332
 333
 334
 335
 336
 337
 338 Greenblatt & Richard          Experimental                      [Page 6]
 339 \f
 340 RFC 2649                LDAP Control and Schema              August 1999
 341
 342
 343    The procedure for creating the signature of the signedResult control
 344    is the same as the procedure for the creation of the signedOperation
 345    control.  The LDAP control in the LDAP response is (OID =
 346    1.2.840.113549.6.0.2):
 347
 348       SignedResult ::= CHOICE {
 349            signature     OCTET STRING }
 350
 351 3.  Security Considerations and Other Notes
 352
 353       The base OIDs are:
 354
 355       rsadsiLdap ::= {1 2 840 113549 6}
 356       rsadsiLdapControls ::=  {1 2 840 113549 6 0}
 357       rsadsiLdapObjectClasses ::= {1 2 840 113549 6 1}
 358       rsadsiLdapAttributes ::= {1 2 840 113549 6 2}
 359
 360
 361       The complete ASN.1 module for this specification is:
 362
 363       SIGNEDOPERATIONS DEFINITIONS ::=
 364       BEGIN
 365
 366       SignedOperation ::= CHOICE {
 367            signbyServer   NULL,
 368            signatureIncluded   OCTET STRING
 369        }
 370
 371       Changes ::= SEQUENCE {
 372            sequenceNumber [0] INTEGER (0 .. maxInt),
 373            signedOperation [1] OCTET STRING }
 374
 375       DemandSignedResult ::=  LDAPSigType
 376
 377       LDAPSigType ::= BOOLEAN
 378
 379       SignedResult ::= CHOICE {
 380            signature     OCTET STRING }
 381
 382
 383       END
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394 Greenblatt & Richard          Experimental                      [Page 7]
 395 \f
 396 RFC 2649                LDAP Control and Schema              August 1999
 397
 398
 399    If any of the controls in this specification are supported by an LDAP
 400    v3 server then that server MUST make available its certificate (if
 401    any) in the userCertificate attribute of its rootDSE object.  The
 402    UserCertificate attribute is defined in [6], and contains the public
 403    key of the server that is used in the creation of the various
 404    signatures defined in this specification.
 405
 406    It is not the intention of this specification to provide a mechanism
 407    that guarantees the origin and integrity of LDAP v3 operations.  Such
 408    a service is best provided by the use of an underlying protocol such
 409    as TLS [8].  TLS defines additional features such as encryption and
 410    compression.  This specification does not define support for
 411    encrypted operations.
 412
 413    This memo proposes protocol elements for transmission and storage of
 414    the digital signatures of LDAP operations.  Though the LDAP server
 415    may have verified the operation signatures prior to their storage and
 416    subsequent retrieval, it is prudent for LDAP clients to verify the
 417    signatures contained in the chained attribute upon their retrieval.
 418    The issuing Certification Authorities of the signer's certificate
 419    should also be consulted in order to determine if the signer's
 420    private key has been compromised or the certificate has been
 421    otherwise revoked.  Security considerations are discussed throughout
 422    this memo.
 423
 424 4.  References
 425
 426    [1] Kaliski, B., "PKCS 7: Cryptographic Message Syntax Version 1-5",
 427        RFC 2315, March 1998.
 428
 429    [2] Dusse, S., Hoffman, P., Ramsdell, B., Lundblade, L. and L.
 430        Repka., "S/MIME Version 2 Message Specification", RFC 2311, March
 431        1998.
 432
 433    [3] Galvin, J., Murphy, S., Crocker, S. and N. Freed, "Security
 434        Multiparts for MIME: Multipart/Signed and Multipart/Encrypted",
 435        RFC 1847, October 1995.
 436
 437    [4] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access
 438        Protocol (v3)", RFC 2251, December 1997.
 439
 440    [5] Howes, T., Smith, M. and F. Dawson, "A MIME Content-Type for
 441        Directory Information", RFC 2425, September 1998.
 442
 443    [6] Wahl, M., "A Summary of the X.500(96) User Schema for use with
 444        LDAPv3", RFC 2256, December 1997.
 445
 446
 447
 448
 449
 450 Greenblatt & Richard          Experimental                      [Page 8]
 451 \f
 452 RFC 2649                LDAP Control and Schema              August 1999
 453
 454
 455    [7] Howes, T. and M. Smith, "The LDAP URL Format", RFC 2255, December
 456        1997.
 457
 458    [8] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", RFC
 459        2246, January 1999.
 460
 461 5.  Authors' Addresses
 462
 463    Bruce Greenblatt
 464    San Jose, CA 95119
 465    USA
 466
 467    Phone: +1-408-224-5349
 468    EMail: bgreenblatt@directory-applications.com
 469
 470
 471    Pat Richard
 472    Xcert Software, Inc.
 473    Suite 1001 - 701 W. Georgia
 474    Vancouver, BC
 475    CANADA V6G 1C9
 476
 477    EMail: patr@xcert.com
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506 Greenblatt & Richard          Experimental                      [Page 9]
 507 \f
 508 RFC 2649                LDAP Control and Schema              August 1999
 509
 510
 511 6.  Full Copyright Statement
 512
 513    Copyright (C) The Internet Society (1999).  All Rights Reserved.
 514
 515    This document and translations of it may be copied and furnished to
 516    others, and derivative works that comment on or otherwise explain it
 517    or assist in its implementation may be prepared, copied, published
 518    and distributed, in whole or in part, without restriction of any
 519    kind, provided that the above copyright notice and this paragraph are
 520    included on all such copies and derivative works.  However, this
 521    document itself may not be modified in any way, such as by removing
 522    the copyright notice or references to the Internet Society or other
 523    Internet organizations, except as needed for the purpose of
 524    developing Internet standards in which case the procedures for
 525    copyrights defined in the Internet Standards process must be
 526    followed, or as required to translate it into languages other than
 527    English.
 528
 529    The limited permissions granted above are perpetual and will not be
 530    revoked by the Internet Society or its successors or assigns.
 531
 532    This document and the information contained herein is provided on an
 533    "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
 534    TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
 535    BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
 536    HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
 537    MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
 538
 539 Acknowledgement
 540
 541    Funding for the RFC Editor function is currently provided by the
 542    Internet Society.
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562 Greenblatt & Richard          Experimental                     [Page 10]
 563 \f